MCP Knowledge Graph for Claude Code: Setup & Config

What you can do with MCP Knowledge Graph in Claude Code

Choose it for local relational memory with separate project, global, and topic-specific stores.

• Remember project facts and relationships between assistant sessions.
• Look up known entities or search observations by keyword.

Before you start: MCP Knowledge Graph in Claude Code

• Node.js 22 or newer
• An MCP-compatible AI platform

Replace the sample global memory path with your chosen directory. A project-root directory named exactly .aim takes priority when detected. Named contexts create additional JSONL databases automatically.

MCP Knowledge Graph Claude Code configuration

1. Choose Claude Code configuration scope

   For MCP Knowledge Graph, open Project scope: .mcp.json at the repository root. Project JSON: merge into mcpServers; user scope: use the CLI.

2. Add MCP Knowledge Graph to Claude Code

   Use the mcp-knowledge-graph entry below in mcpServers. Keep MCP Knowledge Graph's documented stdio connection fields and your other Claude Code entries.

3. Check MCP Knowledge Graph in Claude Code

   MCP Knowledge Graph: Inspect claude mcp list and /mcp status.

{
  "mcpServers": {
    "mcp-knowledge-graph": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-knowledge-graph",
        "--memory-path",
        "/Users/yourusername/.aim"
      ],
      "env": {}
    }
  }
}

claude mcp add-json --scope project 'mcp-knowledge-graph' '{"type":"stdio","command":"npx","args":["-y","mcp-knowledge-graph","--memory-path","/Users/yourusername/.aim"],"env":{}}'

MCP Knowledge Graph tools available to Claude Code

MCP Knowledge Graph's stored tool list documents 10 tools; compare it with Claude Code's connected tool list, because the stored list is not a live check.

aim_memory_store

For MCP Knowledge Graph's aim_memory_store, review the permission request and arguments in Claude Code before approval.

Create persistent records for people, projects, concepts, or other entities.

aim_memory_link

For MCP Knowledge Graph's aim_memory_link, review the permission request and arguments in Claude Code before approval.

Connect stored entities using a named directional relationship.

aim_memory_add_facts

For MCP Knowledge Graph's aim_memory_add_facts, review the permission request and arguments in Claude Code before approval.

Append observations to an existing entity while ignoring duplicates.

aim_memory_forget

For MCP Knowledge Graph's aim_memory_forget, review the permission request and arguments in Claude Code before approval.

aim_memory_remove_facts

For MCP Knowledge Graph's aim_memory_remove_facts, review the permission request and arguments in Claude Code before approval.

aim_memory_unlink

For MCP Knowledge Graph's aim_memory_unlink, review the permission request and arguments in Claude Code before approval.

aim_memory_read_all

For MCP Knowledge Graph's aim_memory_read_all, review the permission request and arguments in Claude Code before approval.

aim_memory_search

For MCP Knowledge Graph's aim_memory_search, review the permission request and arguments in Claude Code before approval.

Match keywords against entity names, types, and observations without case sensitivity.

aim_memory_get

For MCP Knowledge Graph's aim_memory_get, review the permission request and arguments in Claude Code before approval.

Retrieve entities by exact name and include relationships between the selected records.

aim_memory_list_stores

For MCP Knowledge Graph's aim_memory_list_stores, review the permission request and arguments in Claude Code before approval.

MCP Knowledge Graph: full stored tool descriptions

Troubleshooting MCP Knowledge Graph in Claude Code

• If MCP Knowledge Graph fails to start, check npx mcp-knowledge-graph (Node.js/npm), the working directory, and Claude Code's selected scope; inspect claude mcp list and /mcp.
• MCP Knowledge Graph uses stdio here: Claude Code must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Requires Node.js 22 or newer.
• Known limitation: Project detection depends on the exact .aim directory name.
• Known limitation: Inconsistent context naming can create redundant databases.
• General Claude Code troubleshooting lives in the /clients/claude-code guide.

Frequently asked questions