Skip to content

Knowledge Graph API

Jump to bottom
Maxim Mironenko edited this page Mar 16, 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_register_session(cwd?)

Registers a session for sync tracking. Returns a session_id and start_ts used by other tools. Call this first at session start.

Parameters:

Param Type Required Description
cwd string No Project root directory path

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

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

kg_read(session_id?)

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

Parameters: Optional session_id to scope project graph.

Returns: JSON with user and project sections, each containing nodes and edges. Includes HEALTH: X nodes, Y edges, Z orphans (A%), avg B edges/node.

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

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_search(query, level?, session_id?)

Full-text search across node IDs, gists, notes, and touches. Searches both active and archived nodes.

Parameters:

Param Type Required Description
query string Yes Search term (case-insensitive substring match)
level string No "user" or "project" — omit to search both
session_id string No Required for project-level search

Returns: Matching nodes with their full content.

When to use: Finding specific knowledge without loading the entire graph, locating archived nodes for recall.

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. Saves to disk immediately (write-through).

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. Returns tip to connect with kg_put_edge if node has 0 edges.

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 (grace period).

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