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 six graph structures, then exposes them as 58 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

volumes:
  models:

See docs/docker.md for details.

What it does

| Feature | Description | |---------|-------------| | Docs indexing | Parses markdown into heading-based chunks with cross-file links and code block extraction | | Code indexing | Extracts AST symbols (functions, classes, interfaces) via tree-sitter | | File index | Indexes all project files with metadata, language detection, directory hierarchy | | Knowledge graph | Persistent notes and facts with typed relations and cross-graph links | | Task management | Kanban workflow with priorities, assignees, and cross-graph context | | Skills | Reusable recipes with steps, triggers, and usage tracking | | Hybrid search | BM25 keyword + vector cosine similarity with BFS graph expansion | | Real-time | File watching + WebSocket push to UI | | Multi-project | One process manages multiple projects from a single config | | Workspaces | Share knowledge/tasks/skills across related projects | | Auth & ACL | Password login (JWT), API keys, 4-level access control |

58 MCP tools

| Group | Tools | |-------|-------| | Context | get_context | | Docs | list_topics, get_toc, search, get_node, search_topic_files | | Code blocks | find_examples, search_snippets, list_snippets, explain_symbol | | Cross-graph | cross_references | | Code | list_files, get_file_symbols, search_code, get_symbol, search_files | | Files | list_all_files, search_all_files, get_file_info | | Knowledge | create_note, update_note, delete_note, get_note, list_notes, search_notes, create_relation, delete_relation, list_relations, find_linked_notes, add_note_attachment, remove_note_attachment | | Tasks | create_task, update_task, delete_task, get_task, list_tasks, search_tasks, move_task, link_task, create_task_link, delete_task_link, find_linked_tasks, add_task_attachment, remove_task_attachment | | Skills | create_skill, update_skill, delete_skill, get_skill, list_skills, search_skills, recall_skills, bump_skill_usage, link_skill, create_skill_link, delete_skill_link, find_linked_skills, add_skill_attachment, remove_skill_attachment |

Web UI

Dashboard, Knowledge (notes CRUD), Tasks (kanban board with drag-drop), Skills (recipes), Docs browser, Files browser, Prompts (AI prompt generator), Search (cross-graph), Graph (Cytoscape.js visualization), 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$..."   # generated by: graphmemory users add

server:
  jwtSecret: "your-secret"
  defaultAccess: rw

UI login: email + password → JWT cookies (httpOnly, SameSite=Strict)
API access: Authorization: Bearer <apiKey>
ACL: graph > project > workspace > server > defaultAccess (deny / r / rw)

See docs/authentication.md.

Development

npm run dev              # tsc --watch (backend)
cd ui && npm run dev     # Vite on :5173, proxies /api → :3000
npm test                 # 1240 tests across 28 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.

Graphmemory

Install / Use

README