claude-mem-graph

claude-mem-graph

Causal tracing layer over claude-mem. Reads claude-mem's SQLite database, builds an in-memory knowledge graph, and exposes MCP tools for tracing the story around observations.

Why

claude-mem stores observations as flat rows with keyword/vector search. It can find things, but can't tell you what led to what. This plugin adds causal tracing: what happened before this observation, what happened after, what files connect it to other work, and which sessions continue previous sessions.

Use flat search to find the node. Use graph neighbors to trace the story around it.

How it works

On startup, the MCP server:

1. Opens ~/.claude-mem/claude-mem.db (read-only)
2. Loads observations and sessions
3. Builds an in-memory graph with 5 node types and 10 edge types
4. Extracts 1,300+ causal edges from observation narrative text
5. Serves queries via stdio MCP

No background worker. No writes to claude-mem's database. No HTTP port.

SessionStart trim hook

Optional. On session start, emit a compact context block listing the N most recent observations for the current project, falling back to top-N when the recency window is empty. This is the lightweight alternative to claude-mem's full ~50-observation injection.

Configured via env vars (typically set in ~/.claude/settings.json):

Var	Default	Meaning
CLAUDE_MEM_GRAPH_TRIM_N	10	Max observations to include.
CLAUDE_MEM_GRAPH_TRIM_HOURS	24	Recency window in hours. Falls back to top-N when empty.
CLAUDE_MEM_GRAPH_TRIM_DB	~/.claude-mem/claude-mem.db	Override the db path.

The hook always exits 0 and emits no output on any error or when no observations exist for the current project. To use this in place of claude-mem's own SessionStart injection, disable that hook in your settings — both injecting context produces duplicated noise.

MCP Tools

Tool	Purpose
graph_search	Cross-project keyword search across all observation text fields. Returns results ranked by recency, relevance, and graph connectivity.
graph_neighbors	Trace connections from a known observation (1-2 hops). Shows causal chains, shared files, session context. This is the core value.
graph_timeline	Chronological project history showing which sessions continue previous work.
graph_file_history	Find all observations that read or modified a file, across all projects.
graph_playbook_lineage	Surface every observation a named playbook produced (matched via metadata.playbook_id), grouped by run, plus the union of files those observations modified. Stamping is LLM-mediated today via CEO_PLAYBOOK_ID (claude-ceo).
graph_rebuild	Refresh the graph from the database.

Examples

Find and trace a causal chain

> Use graph_search to find observations about "HubSpot migration"

graph_search(task_description="hubspot migration")
→ 15 results including #380 "HubSpot Contact Lists API Migration from v1 to v3"

> Now trace what's connected to #380

graph_neighbors(observation_id=380)
→ informed_by: #375 "Fixed incorrect string literal usage of Hubspot constant"
→ depends_on: #383 "Restored clean HubSpot provider file"
→ led_to: #382 "HubSpot List ID Migration from v1 to v3"
→ touches: src/HubSpot/V3Client.php, src/HubSpot/Client.php
→ produced_by: session sess-a (April 1 work session)

See project history with session arcs

> Show me the wp-content timeline since March

graph_timeline(project="wp-content", since="2026-03-01")
→ 2026-03-16 — session abc12345 [completed]
    - #340 bugfix: Fixed auto-upgrade tax calculation
    - #341 change: Added order notes for tax adjustments
→ 2026-03-27 — session def67890 (continues abc12345) [completed]
    - #380 discovery: HubSpot Contact Lists API Migration
    - #382 feature: HubSpot List ID Migration

Find what touched a file across projects

> What observations involved UserVat.php?

graph_file_history(file_path="plugins/omappv4-core/src/Checkout/Taxes/Vat/UserVat.php")
→ wp-content:
    - #340 bugfix: Fixed auto-upgrade tax calculation
    - #354 bugfix: Prevent empty-string country from poisoning cache
→ wp-content-vat-fix:
    - #360 change: Added trim() to country field handling

Check usage analytics

npm run stats

Shows calls by tool, daily trends, top queries, workflow patterns (search→neighbors vs standalone), empty result rate, and most-traced observation IDs.

Data Model

Nodes: Observation, Session, Project, Concept, File

Edges: