kg-memory-mcp

An in-memory knowledge graph MCP server that gives coding agents structural and semantic recall over codebases. Indexes Python source, ADR documents, and project configuration via tree-sitter parsing and optional LLM extraction, then exposes 7 tools over the Model Context Protocol for search, traversal, context retrieval, and natural-language Q&A.

Key Features

• Structural indexing via tree-sitter -- extracts modules, classes, functions, imports, call graphs, and inheritance hierarchies from Python source

• ADR indexing -- parses architectural decision records into first-class graph nodes with GOVERNS edges linking decisions to the code they affect

• LLM semantic extraction -- enriches the graph with concepts, trade-offs, design principles, and cross-references that only exist in prose

• 3-tier entity reconciliation -- deduplicates nodes via exact match, fuzzy match, and LLM-based semantic similarity

• 7 MCP tools -- search, relate, context, path, ask, reindex, status

• Interactive graph visualization -- React + Sigma.js explorer with filtering, search, and node navigation

• Fast restarts -- persists the graph to .kg-index.json; cold start loads from cache in milliseconds

• Per-project configuration -- drop a .mcp.json in any project root to enable

Related MCP server: budget-aware-mcp

Architecture

Codebase Files
     |
     v
+------------------+     +------------------+
| tree-sitter      |     | LLM Extraction   |
| (Python, MD)     |     | (litellm)        |
| Structural parse |     | Semantic parse   |
+--------+---------+     +--------+---------+
         |                        |
         v                        v
    +----+------------------------+----+
    |      In-Memory Knowledge Graph   |
    |   9 node types, 14 edge types    |
    |   5 O(1) indexes                 |
    +----+-------------------+---------+
         |                   |
         v                   v
  +------+------+    +------+------+
  | 7 MCP Tools |    | Viz Server  |
  | (stdio)     |    | (HTTP)      |
  +-------------+    +-------------+

Quick Start

1. Install

cd kg-memory-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .

# Optional: file watcher for auto-reindex on save
pip install -e ".[watcher]"

2. Configure for a project

Create .mcp.json in your project root:

{
  "mcpServers": {
    "kg-memory": {
      "command": "/path/to/kg-memory-mcp/.venv/bin/kg-memory-mcp",
      "env": {
        "KG_PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

3. Start Claude Code

cd /path/to/your/project
claude

The MCP server launches automatically, indexes the codebase, and the 7 tools become available.

4. (Optional) Enable LLM extraction

Add to the env section of .mcp.json:

{
  "KG_LLM_ENABLED": "true",
  "KG_LLM_MODEL": "openai/gpt-4o-mini",
  "OPENAI_API_KEY": "sk-..."
}

This adds concepts, decisions, and trade-offs extracted from ADRs and documentation.

5. (Optional) Graph visualization

cd viz && npm install && npm run build && cd ..
kg-memory-viz --project-root /path/to/your/project
# Open http://localhost:8765

Indexing Pipeline

The pipeline has four phases, orchestrated by server.py:reindex().

Phase 1: Structural Indexing (tree-sitter)

Three indexers run without any LLM calls.

Python Indexer

Parses all .py files using tree-sitter-python. Extracts:

Edges created from code structure:

Properties captured per node: path, line, docstring, params, decorators, bases, return type.

ADR Indexer

Parses docs/adr/*.md files using tree-sitter-markdown. Uses a two-pass approach:

First pass -- for each ADR file:

• Creates an adr node with title, status, decision summary, and principles

• Extracts concept nodes from Decision subsection headings

• Creates GOVERNS edges via two strategies:

  • Path-based: backtick code spans matching module paths are resolved against the graph's path index

  • Identifier-based: PascalCase/snake_case identifiers in backticks are resolved against the graph's name index (prefers class nodes)

• Creates DEFINES edges linking the ADR to its concepts

Second pass -- resolves REFERENCES edges between ADRs (cross-references like ADR-0003).

Config Indexer

Parses CLAUDE.md (or configured project instructions file). Creates config nodes from h2 sections and extracts concept nodes from markdown tables.

Phase 2: LLM Semantic Extraction (optional)

When KG_LLM_ENABLED=true, the LLMExtractor sends each ADR's full text to the LLM and extracts:

All ADR extractions run concurrently via asyncio.gather(). Per-item Pydantic validation ensures one bad extraction doesn't drop the entire batch. Node IDs use SHA-256 hashes for deterministic, idempotent re-extraction.

What LLM extraction adds that structural indexing misses:

Structural indexing sees code and heading text. LLM extraction reads prose -- the "why" behind architecture. It captures rationale ("We chose Redis over Kafka because..."), design constraints ("Must support at-least-once delivery"), and trade-off reasoning that only exists in natural language. For a project with 15 ADRs, this typically adds 50-100+ semantic nodes and 100-200+ edges.

Phase 3: Entity Reconciliation

Deduplicates nodes created by different indexers without destructive merging.

Tier 1 -- Exact match: Normalizes names (lowercase, collapse whitespace, strip separators). Applies an alias dictionary ("kg" -> "knowledge graph", "mcp" -> "model context protocol", etc.). Creates SAME_AS edges with confidence 1.0.

Tier 2 -- Fuzzy match: Uses difflib.SequenceMatcher across 4 name/canonical combinations. Thresholds: >= 0.85 -> SAME_AS, >= 0.70 -> RELATED_TO.

Tier 3 -- LLM semantic match (only with LLM enabled): Pre-filters to concept/decision pairs sharing significant words. Batches 10 pairs per LLM call, up to 5 concurrent calls, hard-capped at 200 pairs. Thresholds: >= 0.85 -> SAME_AS, >= 0.60 -> RELATED_TO.

Transitive closure via Union-Find groups all SAME_AS pairs into clusters. Both nodes are preserved -- linked, not merged.

Phase 4: Persistence

The graph serializes to .kg-index.json via orjson with atomic write (temp file + rename). On next startup, the cache loads in milliseconds, skipping the full indexing pipeline.

Graph Schema

9 Node Types

14 Edge Types

MCP Tools Deep-Dive

All tools return markdown-formatted text designed for LLM consumption.

kg_search

Search the graph by keyword or concept name.

Scoring algorithm -- each node is scored against the query on a 4-tier scale:

Results are sorted by score descending. Type-specific details are included: file path for files, title for ADRs, definition for concepts, path and line number for classes/functions.

Example: kg_search("scoring", node_types=["class", "function"]) returns the Scorer class, compute_decay_score function, and other scoring-related symbols -- ranked by relevance.

kg_relate

Expand the neighborhood of a node via BFS traversal.

Traverses both outgoing and incoming edges. Results are grouped by node type with edges shown as source --[TYPE]--> target.

Example: kg_relate("adr:0008", depth=2) returns the ADR's decisions, trade-offs, concepts, governed files, and the classes/functions in those files -- a 2-hop view of everything ADR-0008 touches.

kg_context

Get full structured context for a specific file.

Unlike generic BFS, this follows specific semantic paths:

1. Structure: classes and functions contained in the file (CONTAINS)

2. Imports: what this file imports (IMPORTS outgoing)

3. Dependents: who imports this file (IMPORTS incoming)

4. Governing ADRs: which ADRs govern this file (GOVERNS incoming)

5. Decisions: architectural decisions from those ADRs (DECIDED_IN)

6. Related concepts: concepts defined by those ADRs (DEFINES)

7. Entity links: reconciled duplicates (SAME_AS)

Example: kg_context("src/context_graph/domain/scoring.py") returns the file's classes, functions, what ADRs govern it (ADR-0008), key decisions like "Use Ebbinghaus decay scoring", related concepts, and who depends on this file.

kg_path

Find the shortest path between two nodes.

Uses BFS over both edge directions. Returns the path as an indented chain showing each node's name, type, and ID.

Example: kg_path("concept:ebbinghaus_decay", "file:src/scoring.py") might return: concept:ebbinghaus_decay -> adr:0008 -> file:src/scoring.py -- showing how the concept connects to the implementation through the ADR.

kg_ask

Natural-language Q&A grounded in the knowledge graph. Requires KG_LLM_ENABLED=true.

How it works:

1. Searches the graph for the 10 most relevant nodes

2. Expands the top 5 results by 1 hop to gather surrounding context

3. Formats node properties (docstrings, decisions, definitions) as context

4. Sends to the LLM with a structured prompt: WHY (motivation) -> WHAT (how it works) -> WHERE (code references)

5. Appends a Sources section with provenance

Example: kg_ask("How does memory consolidation work?") searches for consolidation-related functions, ADRs, and concepts, then synthesizes a narrative explanation citing specific files and decisions.

kg_reindex

Trigger a full rebuild of the knowledge graph.

Executes all 4 pipeline phases: structural indexing -> LLM extraction -> reconciliation -> persistence. Returns node/edge counts and breakdown by type.

kg_status

Show current graph statistics and server state. Takes no parameters.

Returns: total nodes/edges, counts by type, file watcher status, LLM model/enabled state, last indexed timestamp, reconciliation cluster count.

Graph Visualization

The viz/ directory contains a React + Sigma.js interactive graph explorer.

Tech stack: Vite, React 18, TypeScript, Tailwind CSS, Sigma.js v3 (WebGL), graphology, ForceAtlas2 layout.

Features:

• ForceAtlas2 force-directed layout (handles 1000+ nodes via WebGL)

• Filter by node type and edge type with instant toggle (Sigma reducers, no re-render)

• 4 filter presets: Architecture, Call Graph, ADRs, Show All

• Full-text search with type-priority matching and camera auto-center

• Click any node to see properties, connections grouped by edge type, and navigate to neighbors

• Node drag-and-drop, zoom controls, keyboard shortcuts (Escape, / to search)

• Search-selected nodes reveal their neighbors even when filtered out

Running:

cd viz && npm install && npm run build && cd ..
kg-memory-viz --project-root /path/to/project
# Open http://localhost:8765

The viz server is a zero-dependency Python HTTP server that reads .kg-index.json and serves the React build.

Configuration Reference

Configuration can also be set in kg-memory.toml at the project root, with optional [aliases] for entity reconciliation.

Project Structure

kg-memory-mcp/
  src/kg_memory/
    server.py              MCP server entry point, startup, reindex orchestration
    graph.py               KnowledgeGraph, Node, Edge, 9 NodeTypes, 14 EdgeTypes
    retrieval.py           Search, BFS traversal, shortest path, file context
    extraction.py          LLMExtractor: ADR/config extraction, Q&A, reconciliation
    reconciliation.py      3-tier entity reconciliation (exact, fuzzy, LLM)
    persistence.py         orjson serialize/deserialize to .kg-index.json
    config.py              ProjectConfig from env vars / kg-memory.toml
    watcher.py             Watchdog file watcher for incremental reindex
    tools.py               7 MCP tool definitions and handlers
    viz_server.py          HTTP server for graph visualization
    indexers/
      __init__.py          Orchestrates all indexers, incremental reindex routing
      python_indexer.py    tree-sitter Python: modules, classes, functions, edges
      adr_indexer.py       tree-sitter Markdown: ADRs, concepts, GOVERNS edges
      config_indexer.py    tree-sitter Markdown: config sections, table concepts
  viz/
    src/
      App.tsx              Main layout, state management, keyboard shortcuts
      types.ts             TypeScript types, node/edge color maps
      hooks/useGraphData.ts  Fetch API, build graphology instance
      components/
        GraphCanvas.tsx    Sigma.js container, ForceAtlas2, reducers, drag
        FilterPanel.tsx    Node/edge type toggles, presets
        SearchBar.tsx      Debounced search, type-priority results
        NodeDetail.tsx     Selected node properties and connection browser
        StatsBar.tsx       Graph statistics bar
  tests/
    test_graph.py          Graph data model tests
    test_extraction.py     LLM extraction tests
    test_reconciliation.py Entity reconciliation tests
    test_retrieval.py      Search and traversal tests
    test_persistence.py    Serialization tests
    test_config.py         Configuration tests
  pyproject.toml           Package config, dependencies, CLI entry points

License

MIT