Epistemic Graph Memory (v3.0.0)

A universal, long-term project memory and structural context tool for AI coding agents (Antigravity, Hermes, Claude, Cursor, Codex, OpenHands, Ollama).

Epistemic Graph Memory provides a local, SQLite-backed knowledge graph with Dynamic Epistemic Trust Decay, First-Class Decision Audit Ledgers, Codebase AST Call-Graph Awareness, Hermes-Class Prompt Snapshots, and Continuous Micro-Compaction.

Exposed natively via the Model Context Protocol (MCP) and CLI.

🌟 Core Features (v3.0.0)

1. 🌲 Hermes-Class Declarative Memory & Auto-Recall Snapshots

• Prompt-Cache Friendly Snapshots (graph-memory snapshot): Automatically generates ultra-dense, 500-token Markdown snapshots of active, high-trust graph facts (effective_trust >= 0.7) and recent milestones to inject into LLM system prompts on session startup.
• Continuous Micro-Compaction (distill_session): Based on Hermes Agent micro-compaction principles, verbatim user intent is preserved, while large assistant tool outputs and file reads are continuously distilled into structured graph facts.
• Episodic Session Logging & FTS5 Search (search-sessions): Logs all multi-session conversation history into SQLite FTS5 for zero-friction historic turn retrieval.

2. ⏳ Dynamic Epistemic Trust Decay

• Cognitive Forgetting Math: Calculates dynamic, query-time trust decay without mutating baseline data: $$\text{Effective Trust} = \text{Base Trust Score} \times \left(0.5^{\frac{\Delta t}{30.0}}\right)$$
• Automatic Re-Verification: Re-verifying a node or re-parsing code updates last_verified_at = now(), immediately restoring effective trust to 100%.
• Decay Retrieval Filtering: search_nodes and serialize_subgraph automatically filter out stale entities below min_trust.

3. 📜 First-Class Multi-Agent Decision Ledger

• Append-Only Audit Trail (Decision_Ledger): Tracks which agent made what decision, why (rationale), and when.
• CLI & MCP Querying: Query decision history by agent, node ID, or timeframe (graph-memory query-history --agent Hermes).

4. 🔍 Codebase AST & Call Graph Awareness

• Polyglot AST Ingestion (ingest-code): Deterministic parsing of Python, TypeScript (.ts, .tsx), JavaScript (.js, .jsx), Go, and Rust repositories via Tree-sitter.
• Production Call Graphs & Inheritance: Extracts function call chains (Func_A -[CALLS]-> Func_B) and class inheritance (Class_Sub -[EXTENDS]-> Class_Base).
• Code Snippets & Line Bounds: Extracts exact function signatures, docstrings, line bounds (L10-L45), and code snippets (read_code_snippet).
• <5ms Single-File Re-parsing (ingest-file): Incremental single-file re-parsing for instant updates during editing.
• Ghost Component Pruning: Automatically prunes obsolete function/class nodes when source files are updated.

5. 🔀 Entity Merging & Canonical Pointers

• Soft-Delete Merging (merge_nodes / merge): Merges duplicate entities with canonical pointer resolution (resolve_canonical_id), alias array tracking, and full history propagation.

6. 🎨 2D & GPU-Accelerated 3D Visualizations

• Interactive HTML Export (export_html): Visualizes graph nodes, relationships, and trust scores in interactive 2D.
• 3D WebGL Viewer (export-3d): GPU-accelerated 3D force-directed graph visualizer (vis-network@9.1.9).

📦 Installation

pip install epistemic-graph-memory[all]

Note: The [all] extra installs polyglot Tree-sitter AST parser bindings.

🔌 MCP Server Configuration

To use Epistemic Graph Memory natively inside Claude Desktop, Cursor, Antigravity, Hermes, or Codex, add the following to your MCP configuration:

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

🚀 Quickstart

1. Ingest Codebase AST & Build Graph

# Parse full codebase AST, call graphs, and inheritance
graph-memory ingest-code .

# Incrementally re-parse a single modified file (<5ms)
graph-memory ingest-file graph_memory/core/engine.py --agent Antigravity --rationale "Refactored trust decay"

2. Generate Active Prompt Snapshot (Hermes Auto-Recall)

# Output prompt-cache friendly Markdown snapshot for system prompt injection
graph-memory snapshot --max-tokens 600 --min-trust 0.7

3. Query Decision History & Search

# Query agent decision audit ledger
graph-memory query-history --agent Hermes --limit 10

# FTS5 search across graph nodes
graph-memory search "effective trust"

# FTS5 search across episodic session logs
graph-memory search-sessions "tree-sitter fallback"

4. Graph Maintenance & 3D Visualization

# Lint for orphan nodes and dangling edges
graph-memory lint --fix

# Perform SQLite database vacuum
graph-memory consolidate

# Export WebGL 3D GPU-Accelerated Graph Viewer
graph-memory export-3d memory_3d.html

🛠️ MCP Tool Reference

💡 Architecture Protocols

Entity Ontologies

• Fact_Node: Ground-truth facts derived deterministically from AST, Git, or session distillation.
• Knowledge_Node: High-level architecture, module summaries, and design decisions.
• Episode_Node: Workflows, completed task sequences, and milestone records (linked with FOLLOWED_BY edges).
• Release_Node: Formally published software versions and package release records.

📜 Lineage & Acknowledgments

Graph-Memory was inspired by the Open Knowledge Format (OKF) and the Hermes Agent memory architecture.

• SQLite WAL & FTS5: Powered by local SQLite WAL mode for concurrent multi-agent safety and FTS5 for high-speed indexing.
• Tree-Sitter: Powered by Tree-sitter for polyglot AST parsing.

📄 License

MIT License. Created by Divyansh Ailani.