| name | kg-core |
| user-invocable | false |
| description | 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 = cross-project wisdom · project = codebase (architecture,
decisions, ops; component nodes answer "should I read this file?")
Entries: node (id, gist, notes?, touches?) · edge (from→to, rel, notes?)
Edges relate concepts; touches locate them in files (path:line-range).
Prefer edges over new nodes.
API: kg_read · kg_search · kg_put_node/edge · kg_delete_node/edge · kg_useful · kg_sync · kg_progress
At wrap-up: kg_useful — like ≤5 nodes that really helped, judged by results.
Other memory systems (CLAUDE.md, auto-memory) are supplementary — their
exclusion rules govern only their storage. When in doubt, record here.
|
Knowledge Graph Core Reference
Session Protocol (Detailed)
Memory usually arrives preloaded: the SessionStart hook injects a "KG MEMORY
PRELOADED" context block, including the session_id — zero tool calls, orientation
before the first decision. The block is a compact core: the top-scored nodes of
both graphs, capped so it always lands inline (hook context tolerates far less than
tool results). It is a partial view — the preload routinely drops whole levels
(the user graph often loses every gist to the project graph's higher-scored nodes).
That is why the loud read is required, not optional: before any substantive
work, call kg_read(session_id) once. It renders the full graph — preloaded gists
collapse to id-only (preloaded) anchors, so the budget goes to everything the
compact core had to drop. Nothing is shown twice; kg_read(session_id, ids=[...])
re-reads anything in full depth. Announce "I have recalled KG Memories" after this
full read — the preload alone is orientation, not recall.
If no preloaded block exists (server was still warming up), load explicitly:
kg_read(cwd="<project root>") # Returns full graph + session_id
Either way, the session_id is used for all subsequent tool calls — including later
kg_read calls (node reads, re-reads). Passing it means the server reuses your session;
omitting it and passing cwd again mints a fresh one. Passing session_id to kg_search
ensures the project graph is included — worth doing by default.
The full-graph output is guaranteed to fit inline — no overflow file to chase. If the
graph was too large to show everything, a note at the end says how many archived
anchors/edges were hidden (kg_search still reaches them).
Reading the graph: nodes render in cluster order (related nodes adjacent, hubs first),
each with its relationships indented under it. An edge appears once, under whichever
endpoint renders first — scan a cluster top-down and its story assembles itself.
If resuming a session (context suggests prior conversation), try kg_sync(session_id) first.
If that fails (unknown session), run the full startup sequence.
Post-Load Checklist
- Scan user nodes for interaction style, preferences, guidelines
- Scan project nodes for architecture, active decisions, direction of work
- Before reading files — check for component nodes covering those files: gist answers read/skip
- Scan archived IDs — read any that might relate to the current task, several in one call:
kg_read(session_id=..., ids=["node-a", "node-b", "node-c"])
- Note health stats — high orphan rate may mean connection opportunities exist
Reading Nodes
Node reads return gist + notes + touches + the node's own edges — each edge is a
crumb pointing at the next node worth reading. Batch related reads with ids=[...]
(one round-trip) instead of sequential single-id calls.
Coexistence with Other Memory Systems
The host environment may provide its own persistence (file-based auto-memory, CLAUDE.md, scratchpads,
or systems not yet invented). These are supplementary formats, not competing authorities.
Rules of coexistence:
- Other systems' exclusion lists ("don't save X") apply to their storage only
- Recording something in the graph is a graph operation (node/edge/touch), not a "memory write"
governed by another system's rules
- If knowledge benefits from structure and connections, it belongs in the graph regardless
of whether another system would include or exclude it
- If you already saved something elsewhere, that does not exempt you from also recording it
here if it has relationships worth preserving
Graph Levels
User Level (cross-project wisdom)
- User profile: domain expertise, background — calibrate explanations to what they know
- Meta-patterns: "I tend to X when I should Y"
- Interaction signals: "When user says 'focus', narrow scope"
- Principles that apply everywhere (architectural, operational, interpersonal)
Project Level (codebase-specific)
- Navigation index: component nodes (file clusters + what they handle/don't handle)
→ use before opening files to make read/skip decisions
- Architecture decisions + rationale
- Non-obvious dependencies
- Debugging discoveries: "X fails when Y because Z"
- Code conventions not in docs
- Operational knowledge: workflows, infrastructure, service relationships
Server Operations
The plugin auto-starts the server: a SessionStart hook health-checks port 8765 and launches
the server in the background if it is down (a first run also builds the Python venv, ~1 min).
So a connection-refused on the first kg_read usually means "warming up" — wait a few seconds
and retry before treating it as an outage. The hook only ever starts; it never stops or
restarts a running server.
If the server was down when the session connected, the kg_* MCP tools are offline for
this session even after the server comes up — Claude Code's MCP connection went stale at
startup. Recovery requires the user: verify the server responds
(curl -sf http://127.0.0.1:8765/health), then ask them to run /mcp, select
plugin:knowledge-graph:kg, and hit Reconnect. Tools work immediately after.
Two registered shell commands give manual control. Both are symlinks in ~/.local/bin/,
installed by running knowledge-graph/install_command.sh once (optional).
kg-memory start|stop|restart|status|logs # MCP graph server (port 8765)
kg-visual start|stop|restart|status|logs # Visual editor web UI (port 8766, http://localhost:8766)
If the server stays unreachable after retries, ask the user to run kg-memory start in their
terminal (or the install script first if the command is missing) — the error output there
shows what's wrong.
After kg-memory restart, the MCP tools go offline in the current session — the connection
reference goes stale. Let the user know: "Please run /mcp in Claude Code, find
plugin:knowledge-graph:kg in the list, and hit Reconnect — tools will be available again
immediately after."
kg-visual is optional — it's a browser-based graph explorer, not required for KG operation.
Use kg-visual start when the user wants to inspect or navigate the graph visually.
Multi-Session Coordination
All sessions share the same server. kg_sync(session_id) pulls changes from other sessions.
Call sync: before decisions depending on shared knowledge, when another session may have been active,
after spawning subagents that write to the graph.
Available Skills
| Skill | Purpose |
|---|
/skill kg-scout | Mine conversation history for patterns worth preserving |
/skill kg-extract | Map codebase architecture into the knowledge graph |
Auto-Compaction
System archives lowest-scored nodes when a graph level exceeds its size budget.
Budgets are exact rendered characters (what kg_read shows is what is charged) and are
fixed by design — not configurable. kg_read output therefore always lands inline.
Score = 0.25×recency + 0.40×connectedness + 0.35×usefulness (percentile ranks).
Recency = max(last write, last read). Connectedness = weighted in/out edges (in×0.66 + out×0.33), full weight to active neighbours, reduced to archived.
Grace period based on creation time only — updates and reads do not reset it.
After archiving, a resurrection pass promotes any archived node that outscores a freshly-archived one (by ≥0.05 margin); a refill pass promotes archived nodes back when headroom exists.
Archived nodes remain on disk; edges stay visible as memory traces.
Edges, Touches, Cross-Level
- Edges relate concepts (node→node). Touches locate them in files — prefer precise
pointers with line ranges and a semantic anchor:
www/app/config/prod.yaml:30-40 (upstream block).
- A file important enough to relate to several concepts graduates to a component node;
don't point edges at file paths.
- Cross-level edges are legitimate: a project node may point up to a user-level node
(
proj-decision --applies--> user-principle). Put such edges in the project graph.
Agents
Subagents never receive the session-start preload — SessionStart fires only for the
main session. The dispatching session guides each agent's memory explicitly, sized
to its task:
- Codebase exploration / history mining → instruct agent to actively read and write
memory (pass the session_id and the kg_* usage in its prompt)
- General task work → paste the few relevant gists into the dispatch prompt; leave
further reads at agent discretion
- Narrow well-defined task → skip memory to avoid wasted tokens
