Skip to content

Knowledge Graph API

Jump to bottom
Maxim Mironenko edited this page Feb 6, 2026 · 8 revisions

Knowledge Graph API

All tools are exposed via MCP and called by Claude Code automatically. You don't call these directly — Claude does, guided by the CLAUDE.md template.

Session Lifecycle Tools

kg_read()

Loads the full active graph (both user and project levels). Returns all non-archived nodes and all edges.

Parameters: None required. Optional session_id to scope project graph.

Returns: JSON with user and project sections, each containing nodes and edges.

When it's called: Start of every session, automatically via CLAUDE.md hook.

kg_register_session(project_path?)

Registers a session for sync tracking. Returns a session_id and start_ts used by other tools.

Parameters:

Param Type Required Description
project_path string No Path to project (auto-resolved to absolute)

Returns: {"session_id": "abc12345", "start_ts": 1706000000.0}

When it's called: Start of every session, right after kg_read().

kg_sync(session_id)

Gets changes made by other sessions since this session started. Returns diff of nodes and edges modified by other session IDs.

Parameters:

Param Type Required Description
session_id string Yes Your session ID from kg_register_session

Returns: Diff with user and project sections showing changed nodes/edges.

When to use: Before important decisions, after spawning subagents, periodically in long sessions (~30 min).

kg_session_stats(session_id)

Returns session duration, operation count, and current graph sizes.

Parameters:

Param Type Required Description
session_id string Yes Session ID

Returns:

{
  "session_id": "abc12345",
  "duration_seconds": 1800,
  "op_count": 15,
  "project_path": "/home/user/my-project",
  "graphs": {
    "user": {"nodes": 12, "edges": 8},
    "project": {"nodes": 25, "edges": 30}
  }
}

kg_ping()

Health check. No parameters. Returns server version and active session count.

Graph Write Tools

kg_put_node(level, id, gist, notes?, touches?, session_id?)

Creates or updates a node. If the node exists, fields are overwritten. If the node was archived, it's automatically unarchived.

Parameters:

Param Type Required Description
level "user" or "project" Yes Graph level
id string Yes Node ID (kebab-case convention)
gist string Yes Short description — the core insight
notes string[] No Additional context, caveats
touches string[] No Related files or artifacts
session_id string No For project-level ops and sync tracking

Side effects: Triggers auto-compaction check. Broadcasts change to WebSocket clients.

Example:

kg_put_node(
  level="project",
  id="api-rate-limiting",
  gist="Redis-backed sliding window; 429 response includes Retry-After header",
  touches=["src/middleware/rate_limit.py"],
  notes=["window size configurable via env var RATE_LIMIT_WINDOW"]
)

kg_put_edge(level, from, to, rel, notes?, session_id?)

Creates or updates an edge. from and to can be node IDs or file paths — nodes for those IDs don't need to exist.

Parameters:

Param Type Required Description
level "user" or "project" Yes Graph level
from string Yes Source node ID or file path
to string Yes Target node ID or file path
rel string Yes Relationship type (kebab-case)
notes string[] No Context about this relationship
session_id string No For sync tracking

Example:

kg_put_edge(
  level="project",
  from="auth-module",
  to="src/config.yaml",
  rel="reads-config",
  notes=["JWT secret and token TTL"]
)

kg_delete_node(level, id, session_id?)

Deletes a node and all edges connected to it (both incoming and outgoing).

Returns: Node ID deleted and count of edges removed.

kg_delete_edge(level, from, to, rel, session_id?)

Deletes a specific edge. All three identifiers (from, to, rel) must match exactly.

Returns: {"deleted": true/false}

kg_recall(level, id, session_id?)

Unarchives a previously archived node. Clears _archived and _orphaned_ts flags. Bumps the version timestamp, which protects the node from immediate re-archival (7-day grace).

Errors: Returns error if node doesn't exist or isn't archived.

Progress Tools

For long-running tasks like scout and extract that may span sessions.

kg_progress_get(task_id, level?)

Reads persistent progress for a task. Stored in _meta.progress inside the graph JSON.

Parameters:

Param Type Required Description
task_id string Yes e.g. "scout", "extract"
level string No Default: "user"

Returns: Whatever state object was last saved, or empty if no progress exists.

kg_progress_set(task_id, state, level?, session_id?)

Writes progress state. Overwrites previous state entirely.

Parameters:

Param Type Required Description
task_id string Yes Task identifier
state object Yes Arbitrary JSON state to persist
level string No Default: "user"
session_id string No Required for project level

Example:

kg_progress_set(
  task_id="scout",
  state={
    "last_ts": 1706000000,
    "sessions_reviewed": ["abc123"],
    "patterns_found": ["docker-networking"]
  }
)

Edge and Node ID Conventions

  • Node IDs: kebab-case, descriptive, include domain hint. Good: auth-token-refresh. Bad: refresh.
  • Edge relationships: kebab-case verbs. Common: depends-on, requires, implements, configures, persists, calls, related-to.
  • Touches/from/to: Can be file paths (src/auth/handler.py) or node IDs — mixing is fine.

Clone this wiki locally