Menu
Map codebase architecture into the knowledge graph
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Operations runbook for the knowledge-graph plugin: install and first run, plugin updates, server lifecycle (start/stop/restart/logs), autostart via systemd, connecting Claude Desktop/Cowork, configuration, backup and restore, and troubleshooting (tools offline, -32000 errors, stale data, Desktop issues). Use when something needs setting up, breaks, or the user asks to manage the memory server or "read the docs and do what's needed".
Knowledge Graph — persistent memory, your twin across sessions. Primary context before reaching for any other tool. Session start: memory usually arrives PRELOADED — a "KG MEMORY PRELOADED" block with session_id already in context. It is a compact core: a PARTIAL view, not the graph. REQUIRED before any substantive work: kg_read(session_id) once — it renders everything the preload dropped without repeating it. If no block: kg_read(cwd="<project root>") first. The session_id goes on ALL later kg_* calls. Announce "I have recalled KG Memories" only AFTER that full read. Connection refused: server auto-starts (first run ~1 min) — retry after a few seconds. Still offline: user runs /mcp → plugin:knowledge-graph:kg → Reconnect. Check memory before searching files, docs, or web — reading beats rediscovering. Working currency: gists + edges. Notes are on-demand depth — kg_read(id), or ids=[...] for several related nodes in ONE call. Writes mid-conversation are cheap — capture as things happen. Levels: user = cr
Knowledge graph maintenance. Tend the garden — regular, light care keeps it healthy. Woven into every session. GARDEN RHYTHM — three modes, applied as needed: Water (routine): after each task, glance at 2–3 recently-touched nodes. Gists still accurate? Notes worth adding? Do touches still point where they claim (files drift)? Prune (when dense): merge duplicate nodes, shorten verbose gists (→ notes), split oversized nodes, remove stale touches, delete edges to removed concepts. Fertilize (on use): when a node proves valuable, connect it to newly-discovered related nodes. One new edge makes a node far more durable. AFTER CAPTURE: when you save a node, immediately ask — - Do any adjacent nodes now need updating? - Is this a duplicate of something existing? Merge if so. - Does this node's gist still fit, or did context shift? REACTIVE TRIGGERS (act immediately, mid-conversation): Uncertainty (spinning wheels,
Knowledge capture rules. Capture mid-conversation, not after — context is cached, so a write costs almost nothing now but saves full re-derivation next session. Good moments to capture (as things happen, not at task end): - Opened files with no component node → a brief node now saves a re-read later - Discovered how two things connect → an edge, while the insight is fresh - Understood why something works a certain way → a note on the existing node - 10+ min debugging resolved → root cause node before moving on - User expressed a preference, style, or constraint → user-level node - User corrected your approach → capture what was missed, not just the fix - Explained something non-obvious → node before it scrolls away - Approach agreed with user → capture the methodology, not just the decision - Architectural decision made → node with rationale in notes - Context window feels deep → a good moment to check for anything unrecorded When reading a file with no component node, consider creating
Knowledge recall rules. Active every session, integrated with all task work. After kg_read, scan all node IDs and gists — anything that feels related to the current task is worth reading in full, several at once: kg_read(session_id, ids=[...]). Lean toward reading more rather than less; a wrong guess costs one tool call, missing context costs the whole task. Gists + edges are the working currency (WHAT + how things relate). Notes hold rationale (WHY) — read a node in full when a decision depends on the reasoning. Node reads also return the node's edges: each one is the next crumb. Three tiers — nodes shift as the graph grows: active → id + gist visible in kg_read archived → id only; edges visible as crumb trails orphaned → invisible in kg_read; reachable via kg_search Following crumbs: an edge pointing to an archived id is an invitation — reading it promotes it and surfaces any orphaned neighbors. Batch the whole trail into one ids=[...] call when several nodes look related. No edges? Scan the arc
Mine conversation history for patterns and insights worth preserving
| name | kg-extract |
| user-invocable | true |
| description | Map codebase architecture into the knowledge graph |
Extract builds a two-tier navigation index in the project graph. The goal is precise: let future sessions answer "should I read this file?" without opening it.
Filenames and directory listings tell you what exists. The KG tells you what each piece handles and — equally important — what it doesn't, so skip decisions are reliable.
Directory-scale orientation. Answers: "which part of the codebase?"
kg_put_node(level="project", id="auth-subsystem",
gist="JWT issue/verify + refresh flow. No user lookup, no permissions — those are in user-subsystem.",
touches=["src/auth/"])
File-cluster-scale. Answers: "which file within that area?" One node covers 1–5 tightly related files that always change together.
kg_put_node(level="project", id="auth-token-signing",
gist="Signs/verifies JWTs only. Key rotation logic here, not in middleware.",
touches=["src/auth/jwt.ts", "src/auth/keys.ts"])
Component nodes are never created upfront in bulk — only when you actually explore that area during a task. They accumulate naturally as the codebase is worked on.
| Type | Tier | What it represents |
|---|---|---|
subsystem | 1 | Major bounded area (auth, payments, ingestion pipeline) |
component | 2 | Specific file cluster with a single clear responsibility |
resource | — | External state: database, cache, queue, third-party API |
entry | — | Invocation surface: HTTP route group, CLI command, cron, event |
contract | — | Shared interface: API schema, event type, shared types package |
The skip signal comes from knowing what's not here, not just what is.
| Pattern | Example |
|---|---|
| scope + explicit exclusion | "Stripe webhook ingestion — signature validation + idempotency. No business logic." |
| what it owns vs. delegates | "Rate limiting middleware. Reads Redis counters; does not write them — see rate-counter component." |
| surprising non-obvious fact | "Config parser runs at import time — any module reading config must import this first or gets stale values." |
Bad gist: "Authentication module" — tells you nothing about whether to open the file.
Good gist: "JWT issue/verify only — stateless, no DB calls, no session state" — skip decision made.
A touch that names a whole file saves a search; a touch that names a line range saves the read itself. When a specific block is what matters, point at it — with a short semantic anchor so the pointer survives line drift:
touches=["src/auth/jwt.ts:88-120 (rotation schedule)", "config/prod.yaml:30-40 (upstream block)"]
Whole-file touches are right for component nodes (the cluster is the unit); ranged pointers are right for knowledge nodes about one specific spot. Never point edges at file paths — edges relate concepts; touches locate them.
| Edge | Meaning |
|---|---|
calls | Runtime dependency (A uses B) |
persists | Reads/writes a resource |
serves | Handles an entry point |
exposes | Provides a contract |
consumes | Depends on a contract |
configures | Config artifact affects behavior |
guards | Middleware/validation wrapping another component |
kg_progress(session_id, task_id="extract")
Glob("**/package.json") # or pyproject.toml, go.mod, Cargo.toml
Glob("src/**", limit=2) # directory shape only
Glob("**/README*")
Identify: main directories, entry points, config files, key abstractions.
Map the 5–10 subsystems. Fast, coarse. Connect them to resources and entries.
kg_put_node(level="project", id="api-subsystem",
gist="HTTP layer: routing, validation, response shaping. No business logic.",
touches=["src/api/"])
kg_put_node(level="project", id="postgres-db",
gist="Primary store. Schema via Alembic migrations.", touches=["migrations/"])
kg_put_edge(level="project", from="api-subsystem", to="postgres-db",
rel="persists", notes=["via domain-subsystem ORM calls"])
Save progress:
kg_progress(session_id, task_id="extract", state={
"tier1_done": true,
"subsystems": ["api", "domain", "data", "auth"],
"last_updated": "2026-05-01"
})
When you open files in an area, add a component node for the file cluster. Do not create component nodes for areas you haven't touched.
kg_put_node(level="project", id="auth-token-signing",
gist="Signs/verifies JWTs. Key rotation here. Middleware is separate.",
touches=["src/auth/jwt.ts", "src/auth/keys.ts"])
kg_put_edge(level="project", from="auth-subsystem", to="auth-token-signing",
rel="contains")
Good: First session on a new codebase · after major refactor · user asks to map it
Bad: Mid-task (just add component nodes for what you're actually touching) · graph near token limit · project is small enough to Glob in one pass
# Tier 1 — Subsystems
kg_put_node(level="project", id="api-subsystem",
gist="FastAPI routes + request validation. No business logic — delegates everything to domain.",
touches=["src/api/"])
kg_put_node(level="project", id="domain-subsystem",
gist="Business rules + orchestration. Framework-free. Entry point for all logic.",
touches=["src/domain/"])
kg_put_node(level="project", id="data-subsystem",
gist="SQLAlchemy models + async sessions. Schema owned here via Alembic.",
touches=["src/data/", "migrations/"])
kg_put_node(level="project", id="postgres-db", gist="Primary store.")
kg_put_node(level="project", id="redis-cache", gist="Session store + rate limit counters.")
kg_put_edge(level="project", from="api-subsystem", to="domain-subsystem", rel="calls")
kg_put_edge(level="project", from="domain-subsystem", to="data-subsystem", rel="calls")
kg_put_edge(level="project", from="data-subsystem", to="postgres-db", rel="persists")
kg_put_edge(level="project", from="api-subsystem", to="redis-cache",
rel="persists", notes=["rate limiting only"])
# Tier 2 — Components (added later, as files are explored)
kg_put_node(level="project", id="auth-middleware",
gist="Validates JWT on every request. Injects user_id into request state. Does NOT issue tokens.",
touches=["src/api/middleware/auth.py"])
kg_put_edge(level="project", from="auth-middleware", to="api-subsystem", rel="guards")