Epistemic Graph Memory

A local knowledge graph that gives AI coding agents long-term project memory.
5,000 lines of Python. Zero cloud dependencies. One pip install.

python -m pip install 'epistemic-graph-memory[all]'

The problem

AI coding agents reconstruct project context from scratch every session. They re-read files they've already read, re-derive architecture they've already derived, and lose decisions made yesterday. Claude Code, Cursor, Codex, OpenCode — they all forget.

The solution

A SQLite-backed knowledge graph that lives in your project at .agents/graph_memory.sqlite. It ingests your codebase's AST (functions, classes, call graphs, imports), records agent decisions in an append-only ledger, detects when agents contradict each other, and produces deterministic snapshots that inject directly into agent system prompts — with byte-stable caching so prompt caches stay hot.

All 20 MCP tools, a 30-command CLI, lifecycle hooks for 9 agent harnesses, and a streamable HTTP endpoint for remote agents.

What it actually does

Code understanding. Parses Python, TypeScript, JS/JSX, Go, and Rust via Tree-sitter. Extracts signatures, docstrings, line ranges, call graphs, and inheritance. Cross-file call resolution wires stubs to real definitions across your entire repo. Batch ingestion processes this repo's 37 files in 0.45 seconds; unchanged re-ingests take 0.06 seconds (hash-skip).

Agent memory. Every decision an agent makes — what it changed, why, when — goes into an append-only Decision_Ledger. A reflection engine digests the last 30 days of real decisions into structured memory cards. When two agents disagree about a fact (different values for the same field), the contradiction is recorded and surfaced — no silent overwrites.

Trust decay. Facts decay over time with effective = base × 0.5^(days/30). Re-verifying a fact resets it to 100%. Derived facts re-verify themselves: if the source file is byte-identical to the hash recorded at ingest, the signature and call edges extracted from it are still true, so the lifecycle hooks refresh those nodes with no agent effort — and a node that owns no file (call stub, import target, MOC, project root) is refreshed only when everything feeding it is fresh, so an edited file correctly keeps its dependents decayed. Stale, unreferenced nodes get garbage-collected. This means the graph self-maintains — old assumptions fade, recent verifications stay sharp.

Prompt injection. graph-memory snapshot produces a deterministic, content-fingerprinted Markdown snapshot. If nothing changed, you get the exact same bytes — so Claude's prompt cache, Cursor's context cache, whatever — stays warm. Zero wasted tokens on unchanged context.

Transport. Runs over stdio MCP (Claude Desktop, Cursor, Codex) and streamable HTTP MCP (OpenCode, Docker, remote agents). One binary, both transports. Health check at /health.

Import / export. Migrating from mem0? graph-memory import-mem0 export.json. Have a CLAUDE.md? graph-memory import-md CLAUDE.md. Want a browsable Obsidian vault with [[wikilinks]] for every graph edge? graph-memory export-obsidian ~/vault.

Setup

python -m pip install 'epistemic-graph-memory[all]'

The core package is stdlib-only (SQLite, JSON, regex) and installs everywhere with zero compiled dependencies. Two optional extras add the heavy features:

pip install epistemic-graph-memory                # core only, stdlib
pip install 'epistemic-graph-memory[ast]'         # + code ingestion
pip install 'epistemic-graph-memory[mcp]'         # + MCP stdio
pip install 'epistemic-graph-memory[http]'        # + MCP over HTTP
pip install 'epistemic-graph-memory[all]'         # + everything

Android / Termux: [mcp] pulls pydantic → pydantic-core, which has no Android wheel and tries to build Rust for a target rustup doesn't support — a multi-minute stall that ends in failure. pip install epistemic-graph-memory (core) finishes in seconds and gives you the graph, search, and Markdown import. AST and MCP need their extras and full toolchain support.

MCP configuration

Add to your agent's MCP config:

{
  "mcpServers": {
    "graph-memory": {
      "command": "graph-memory-mcp"
    }
  }
}

For remote-only agents (OpenCode, Docker):

graph-memory-mcp-http                    # http://127.0.0.1:8765/mcp

Then point your agent at http://127.0.0.1:8765/mcp.

Security (v3.8.0): The HTTP server defaults to localhost (127.0.0.1) and includes DNS rebinding protection. For remote deployment:

• Set GRAPH_MEMORY_API_KEY environment variable to require authentication
• Use a reverse proxy (nginx, Caddy) with TLS
• Bind to 0.0.0.0 only behind a firewall/VPN
• Never expose the server directly to the public internet (it provides full filesystem and database access)

GRAPH_MEMORY_API_KEY=your-secret-key graph-memory-mcp-http

One-command agent hooks

graph-memory hook install                 # auto-detect and configure all frameworks
graph-memory hook install --framework cursor
graph-memory hook status

This wires lifecycle capture into Claude Code, ZCode, Cursor, Codex, OpenCode, Antigravity, Qoder, and Hermes — PostToolUse triggers incremental AST ingest of edited files (<5ms), session-end distills transcripts into graph facts, and session-start refreshes all snapshots.

CLI

# Ingest entire codebase (polyglot AST + call graphs)
graph-memory ingest-code .

# Re-parse a single changed file (<5ms, skips if unchanged)
graph-memory ingest-file src/engine.py

# Generate prompt-cache-stable snapshot
graph-memory snapshot --max-tokens 600 --min-trust 0.7

# Search nodes (FTS5 + identifier substring fallback)
graph-memory search "effective_tr"
graph-memory search "trust decay"

# Decision audit trail
graph-memory query-history --agent Hermes --days 7

# Contradiction detection
graph-memory contradictions

# Stale-node garbage collection
graph-memory prune --days 60

# Mechanical re-verification (hash-stable AST facts; curated nodes via test suite)
graph-memory verify
graph-memory verify --tests

# Scheduled verification (launchd / systemd / Task Scheduler, no daemon)
graph-memory schedule install --interval 1d

# Import existing memories
graph-memory import-md CLAUDE.md
graph-memory import-mem0 memories.json

# Export to Obsidian vault
graph-memory export-obsidian ~/vaults/my-project

# HTML / 3D visualization
graph-memory export-html graph.html
graph-memory export-3d graph_3d.html

MCP tools

Architecture

graph_memory/
├── core/
│   ├── engine.py        # SQLite graph engine: CRUD, trust decay, ledger, search, batch upsert, contradictions, prune
│   ├── ingest.py        # Tree-sitter AST ingestion, batch pipeline, cross-file call resolution
│   ├── importers.py     # Markdown + mem0 import
│   ├── obsidian.py      # Obsidian vault export with [[wikilinks]]
│   ├── snapshot.py      # Deterministic, cache-stable snapshot generation
│   ├── memory.py        # Data-driven reflection engine
│   ├── lifecycle.py      # Harness-agnostic event dispatcher
│   ├── distill.py       # Session transcript micro-compaction
│   ├── knowledge.py     # Knowledge-card extraction + repo-wiki export
│   └── summarizer.py    # Optional: Gemini MOC summarization (opt-in, GEMINI_API_KEY)
├── mcp/
│   ├── server.py        # Stdio MCP server (20 tools)
│   └── http_server.py   # Streamable HTTP MCP transport
├── integrations/
│   ├── framework_hooks.py  # 9-framework auto-install + lifecycle wiring
│   └── scheduler.py     # OS-native scheduled verification (launchd/systemd/schtasks)
└── cli.py               # 30-command CLI

Storage: Single SQLite file per project at .agents/graph_memory.sqlite. WAL mode for concurrent safety. FTS5 for full-text search. No external databases, no servers, no cloud — the only network call anywhere is the opt-in summarize-mocs command, which uses Gemini via GEMINI_API_KEY.

Node types: Fact_Node (deterministic ground truth from AST/Git), Knowledge_Node (architecture, design decisions), Episode_Node (completed task sequences), Release_Node (published versions).

Trust model: Query-time decay — effective = base × 0.5^(Δdays/half_life). Re-verification resets to 100%. Stale, unreferenced nodes get soft-deleted by the prune command.

Numbers

License

MIT — Divyansh Ailani