Knowledge Graph

Knowledge Graph

Agents forget everything between sessions and re-derive the architecture by reading code — slow, token-hungry, and lossy for things code can't say (why a decision was made, which subsystem bites). The fix is a small, committed knowledge graph the agent reads first and updates as it works. Plain files by default: greppable by any agent, reviewable in PRs, no dependencies. A database only when scale genuinely demands it.

Pick the right tier — most repos stop at 0 or 1

• Tier 0 — one agents file. CLAUDE.md / AGENTS.md with architecture notes. If the repo's durable knowledge fits in ~100 lines, stop here; a graph would be ceremony.
• Tier 1 — file graph (the default). .knowledge/ with one markdown file per entity and typed relation lines. Right for most real projects. Everything below describes this tier; exact format in references/formats.md.
• Tier 2 — SQLite. Same node/edge model in one sqlite3 file. Escalate only past ~200 entities or when you need real traversal (transitive impact, shortest path). Schema + recursive-CTE queries and a file→SQLite migration in references/formats.md.
• Tier 3 — real graph DB (Kuzu, Neo4j). Only when the application needs graph queries. For agent memory it's overkill: a server or bindings other agents won't have, invisible to grep, unreviewable in diffs. Recommend against unless asked.

Tier 1 layout

.knowledge/
  README.md            # 5 lines: what this is, how to query, the update rule
  entities/<id>.md     # id = <type>-<name>: service-orders, decision-auth-jwt, gotcha-sqlite-wal

Entity types that earn their keep: service/module (code units), store (DBs, queues), decision (what + why + alternatives rejected), gotcha (traps that cost someone an hour), flow (cross-module paths: "checkout touches these five things"). Skip entities for things one ls reveals.

Each entity: frontmatter (id, type, anchors: — real file paths it describes), 3–8 lines of prose an agent can't get faster from the code, and typed relation lines (- depends_on: service-users). Relations are the payoff — backlinks service-users answers "what breaks if I change users?" without reading a line of code.

Querying — it's just grep

scripts/kg.sh bundles the common queries: list, show <id>, links <id> (outgoing), backlinks <id> (who points here — reverse edges are the high-value query), stale (anchors pointing at deleted files), orphans (unlinked entities), anchored <path> (entities whose anchors cover a file — the read-protocol query), new <type> <name>. No script available? Plain grep does everything: grep -l 'depends_on: service-users' .knowledge/entities/*.md.

The two protocols that keep it alive

A stale graph is worse than none — the agent trusts it and acts on lies. Two rules, stated in .knowledge/README.md so every agent sees them:

Read protocol (session start / task start). Before exploring code for a task, run kg.sh anchored <path> for the files in scope; read the hits and their 1-hop neighbors first. Then explore only what the graph doesn't cover.

Write protocol (same commit as the code).

• Touched code that an entity anchors? Update the entity in the same commit if the description or relations changed.
• Made a non-obvious choice? Add a decision-* entity — what, why, what was rejected.
• Lost >30 min to something surprising? Add a gotcha-*. That's the highest-ROI entity type.
• Run kg.sh stale in CI or pre-commit so renames/deletions can't silently rot anchors.

Keep it small: prune entities whose knowledge became obvious from the code; a 40-entity graph that's true beats a 400-entity graph nobody trusts.