graphmemory

An MCP server that builds a semantic graph memory from a project directory. Indexes markdown docs, TypeScript/JavaScript source code, and all project files into graph structures, then exposes them as 70 MCP tools + REST API + Web UI.

Quick start

npm install -g @graphmemory/server
cd /path/to/my-project
graphmemory serve

That's it. No config file needed — the current directory becomes your project. Open http://localhost:3000 for the web UI.

The embedding model (~560 MB) downloads on first startup and is cached at ~/.graph-memory/models/.

Connect an MCP client

Claude Code:

claude mcp add --transport http --scope project graph-memory http://localhost:3000/mcp/my-project

Claude Desktop — add via Settings > Connectors, enter the URL:

http://localhost:3000/mcp/my-project

Cursor / Windsurf / other clients — enter the URL directly in settings:

http://localhost:3000/mcp/my-project

The project ID is your directory name. Multiple clients can connect simultaneously.

With a config file

For multi-project setups, custom embedding models, auth, or workspaces — create graph-memory.yaml:

projects:
  my-app:
    projectDir: "/path/to/my-app"
  docs-site:
    projectDir: "/path/to/docs"
    graphs:
      code:
        enabled: false

graphmemory serve --config graph-memory.yaml

See docs/configuration.md for full reference and graph-memory.yaml.example for all options.

Docker

docker run -d \
  --name graph-memory \
  -p 3000:3000 \
  -v $(pwd)/graph-memory.yaml:/data/config/graph-memory.yaml:ro \
  -v /path/to/my-app:/data/projects/my-app:ro \
  -v graph-memory-models:/data/models \
  ghcr.io/graph-memory/graphmemory-server

Docker Compose:

services:
  graph-memory:
    image: ghcr.io/graph-memory/graphmemory-server
    ports:
      - "3000:3000"
    volumes:
      - ./graph-memory.yaml:/data/config/graph-memory.yaml:ro
      - /path/to/my-app:/data/projects/my-app
      - models:/data/models
    restart: unless-stopped
    depends_on:
      redis:
        condition: service_healthy

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    volumes:
      - redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 3

volumes:
  models:
  redis-data:

Redis is optional. Remove the redis service and depends_on if you don't need shared session store or embedding cache.

See docs/docker.md for details.

What it does

70 MCP tools

Web UI

Dashboard, Knowledge (notes CRUD), Tasks (kanban board with drag-drop), Skills (recipes), Docs browser, Code browser (symbols, edges, source), Files browser, Prompts (AI prompt generator), Search (cross-graph), Tools (MCP explorer), Help.

Light/dark theme. Real-time WebSocket updates. Login page when auth is configured.

Authentication

users:
  alice:
    name: "Alice"
    email: "alice@example.com"
    apiKey: "mgm-key-abc123"
    passwordHash: "$scrypt$65536$..."   # generated by: graphmemory users add

server:
  jwtSecret: "your-secret"
  defaultAccess: rw
  redis:                              # optional: session store + embedding cache
    enabled: true
    url: "redis://localhost:6379"

• UI login: email + password → JWT cookies (httpOnly, SameSite=Strict)

• API access: Authorization: Bearer <apiKey>

• OAuth 2.0: Authorization Code + PKCE (S256) with frontend consent page at /ui/auth/authorize; also supports client credentials and refresh tokens

• OAuth endpoints: /api/oauth/userinfo, /api/oauth/introspect, /api/oauth/revoke, /api/oauth/end-session

• ACL: graph > project > workspace > server > defaultAccess (deny / r / rw)

• Redis (optional): when server.redis is configured, used for OAuth session store and embedding cache

See docs/authentication.md.

Development

npm run dev              # tsc --watch (backend)
cd ui && npm run dev     # Vite on :5173, proxies /api → :3000
npm test                 # 1809 tests across 45 suites

Documentation

Full documentation is in docs/:

• Concepts: docs indexing, code indexing, tasks, skills, knowledge, file index

• Architecture: system architecture, graphs overview, search algorithms, embeddings

• API: REST API, MCP tools guide, WebSocket

• Operations: CLI, configuration, Docker, npm

• Security: authentication, security

• UI: architecture, features, patterns

• Development: testing, API patterns

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

For security vulnerabilities, see SECURITY.md.

License

Elastic License 2.0 (ELv2) — free to use, modify, and self-host. Not permitted to offer as a managed/hosted service.