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. ## Beyond the curated graph: session memory The `.knowledge/` graph is *semantic* memory — deliberate, reviewed, committed. Its complement is *episodic* memory: observations captured automatically from sessions (what was tried, decided, discovered), stored locally and gitignored, with the good parts **promoted** into the graph instead of rotting in a log. When a repo needs that layer — "the agent keeps re-learning what it did last week" — see `references/session-memory.md`: the capture/consolidate/retrieve pipeline distilled from mem0, claude-mem, and Letta, plus a single-binary Go blueprint (SQLite + FTS5, lifecycle hooks, progressive-disclosure retrieval, `promote` bridging into `.knowledge/`). No Python, no servers, works with any agent. ## With other skills - **`orchestrate` skill**: the planner reads the graph during analysis and points each task brief at the relevant entity files; worker `Discovered` notes in results reports get merged into the graph during integration — parallel work becomes a knowledge harvest. - **`debug` skill**: a confirmed root cause that was expensive to find is a `gotcha-*` entity. - Works for any agent: it's markdown in the repo. Non-Claude agents get "read `.knowledge/README.md` first" in their brief or agents file. ## Setup checklist (new repo) 1. Create `.knowledge/README.md` (query + update rules, 5 lines) and `entities/`. 2. Seed 5–15 entities from the current architecture: the modules, the stores, standing decisions, known gotchas. Don't inventory everything — seed what you had to *learn*, not what you can *see*. 3. Copy `kg.sh` into the repo (`scripts/` or keep calling it from the installed skill) and wire `kg.sh stale` into CI. 4. Add one line to `CLAUDE.md`/`AGENTS.md`: "Read `.knowledge/README.md` before exploring; follow its update rule." Formats, relation vocabulary, SQLite schema and migration: `references/formats.md`. Episodic session memory (auto-capture, hooks, Go blueprint): `references/session-memory.md`.