How It Works

How It Works

Architecture Overview

┌─────────────────────────────────────────────────┐
│            Claude Code Sessions                  │
│  Session A        Session B        Session C     │
└──────┬───────────────┬────────────────┬──────────┘
       │               │                │
       │  Stateless HTTP (MCP protocol) │
       └───────┬───────┘                │
               ▼                        │
    ┌──────────────────────┐            │
    │  MCP Streamable HTTP │            │
    │  Server (port 8765)  │◄───────────┘
    │                      │
    │  - MCP tools (/)     │
    │  - REST API (/api/*) │
    │  - WebSocket (/ws)   │
    └──────────┬───────────┘
               │
               ▼
    ┌──────────────────────┐
    │ MultiProjectGraphStore│
    │  - In-memory graphs  │
    │  - Write-through     │
    │  - Auto-compact      │
    └──────────┬───────────┘
               │
        ┌──────┴──────┐
        ▼             ▼
~/.knowledge-graph/
├── user.json          (global)
├── sessions.json
└── projects/
    ├── my-app/graph.json
    └── other/graph.json

Two-Level Model

Knowledge is split into two levels, all stored centrally:

Level	What Goes Here	Storage Location
user	Cross-project wisdom: preferences, meta-learnings, architectural principles, personal patterns	~/.knowledge-graph/user.json
project	Codebase-specific: architecture decisions, dependencies, debugging discoveries, conventions	~/.knowledge-graph/projects/<slug>/graph.json

The user graph is a singleton — one file, always loaded. Project graphs are loaded on demand when a session registers with a project_path.

Nodes and Edges

The graph has two entry types:

Nodes — Named concepts, patterns, or insights:

{
  "id": "auth-token-refresh",
  "gist": "JWT refresh uses sliding window; silent failure if session expired",
  "notes": ["discovered during auth debugging 2025-01"],
  "touches": ["src/auth/refresh.py"]
}

Edges — Relationships between nodes, files, or concepts:

{
  "from": "auth-module",
  "to": "session-handler",
  "rel": "requires-init",
  "notes": ["token validation assumes active session"]
}

Edges can reference node IDs or file paths directly — you don't need a node for every file.

Data Flow

1. Session starts → the SessionStart hook preloads the rendered graph (both levels) plus a session_id into context before the first message — zero tool calls. If the server was still warming up, Claude falls back to calling kg_read(cwd) explicitly.
2. During work → Claude calls kg_put_node/kg_put_edge to capture insights
3. Write-through → Every mutation saves to disk immediately (atomic write: temp file + rename)
4. Background maintenance → Periodic thread (30s) runs compaction and orphan pruning
5. Multi-session → Other sessions call kg_sync(session_id) to get changes since their start time

All operations go through the shared in-memory store. Write-through ensures disk is always up-to-date.

Auto-Compaction

Maintenance runs after every write and on the periodic background tick. At most one of archive/refill acts per tick:

Pass 1 — Archive (when the active graph exceeds its character budget):

1. Score each eligible node using three percentile-ranked signals:
   • Recency — max(last_write_ts, last_read_ts). Reading a node in full refreshes its recency.
   • Connectedness — Weighted in/out edges: in_degree × 0.66 + out_degree × 0.33. An edge to an active neighbour counts at full weight; an edge to an archived neighbour counts at 0.2 (so a cluster that archived together isn't scored as fully disconnected); edges to orphaned nodes count for nothing.
   • Usefulness — decaying kg_useful endorsements (90-day half-life): at session wrap-up the agent marks up to 5 nodes that actually helped, judged against real results. Reads don't count — a good gist never needs the full read.
2. Final score = 0.25 × recency + 0.40 × connectedness + 0.35 × usefulness (tie-aware percentile ranks)
3. Archive lowest-scoring nodes until graph is under COMPACTION_TARGET_RATIO (0.8) of the character budget
4. Grace period — Nodes created recently are never archived (see KG_GRACE_PERIOD_DAYS). Grace is based on creation time only — updates and reads do not reset it.

Archived nodes get _archived: true. Their edges to active nodes remain visible as memory traces — strings you can pull. An edge between two archived nodes is hidden (you hold neither end), reappearing automatically once either end is promoted. Use kg_read(session_id, id) to promote a node back to active.

Pass 1b — Resurrection (runs after archiving): Re-scores archived + active nodes together. If any pre-existing archived node outscores a just-archived node by ≥0.05, they swap — the better-scoring archived node is restored to active (bounded so a swap never pushes the graph back over the limit). This ensures archiving history doesn't permanently strand nodes that became well-connected after the fact.

Pass 1r — Refill (when the active graph sits below the fill ceiling): The reverse of archiving. Whenever active tokens are below COMPACTION_TARGET_RATIO (0.8) of the limit, the highest-scored archived nodes are promoted back to active until the ceiling is reached. Promotion is iterative — after each promotion the remaining candidates are re-scored, because the promoted node's edges just became live and raise its neighbours' connectedness. This lets a dense archived cluster lead itself back: pull the hub, its satellites re-rank to the top, pull them next. A candidate too large for the remaining headroom is skipped (it doesn't block smaller candidates behind it). Refill never runs on a tick that just archived, and the 0.8 ceiling sits safely below the 1.0 archive threshold — the two passes cannot thrash.

Pass 2 — Orphan (when the archived section exceeds 30% of the character budget):

1. Measure archived anchor lines — each costs exactly its rendered ID line in kg_read output
2. When archived chars exceed ARCHIVED_BUDGET_RATIO (30%) of the budget, demote lowest-connectivity archived nodes to orphaned (_orphaned_ts = now)
3. Orphaned nodes are invisible in kg_read and kg_sync — they no longer consume context

Three-Tier Node States

State	In kg_read	In kg_search	Recovery
active	gist + its live edges visible	✓	—
archived	ID + edges to active nodes visible	✓	kg_read(session_id, id) → promotes to active (refill also promotes automatically when budget allows)
orphaned	invisible	✓ flagged	search → kg_read(session_id, id)

Chain rescue: reading an archived node promotes it to active AND rescues any of its orphaned neighbors back to archived — their IDs and edges reappear as crumbs to follow.

Permanent deletion: orphaned nodes with no recall after KG_ORPHAN_GRACE_DAYS (365 days) are permanently deleted from disk.

Size Accounting (render == charge)

The system measures exact rendered characters to decide when to compact — it builds the same render plan kg_read shows and measures those very lines, so the budget and the visible output can never disagree:

Component	Cost
Active node	its rendered id: gist line (notes/touches are on-demand, not charged)
Archived node	its rendered ID "anchor" line
Orphaned node	0 (invisible)
Live edge	its citation line, charged once (cited under its first-rendered endpoint)
Archived–archived edge	0 (suppressed — a string you can't pull)

A single predicate, core.utils.edge_is_live, decides what counts as a live edge, and both the renderer and the estimator use it. The budgets are fixed by design (17,500 chars per level; 40,000 per read) — the arithmetic guarantees kg_read output always lands inline in Claude's context.

Transport: Stateless HTTP

The server uses MCP's Streamable HTTP transport in stateless mode. Each request is independent — no session IDs preserved between HTTP requests by the MCP layer.

This is because Claude Code's MCP client doesn't preserve session IDs between requests. The server was tested with stateful mode and it failed — Claude Code simply doesn't send the mcp-session-id header back.

Session tracking for sync (kg_sync) is handled at the application level, not the transport level.

Concurrency

• Thread-safe via threading.RLock on the graph store
• Multiple Claude Code sessions can read/write simultaneously
• Last write wins — no conflict resolution beyond that
• The kg_sync tool lets sessions pull changes made by other sessions