Context Graph

Persistent, multi-dimensional semantic memory for AI assistants.

Context Graph is an MCP server that gives AI assistants like Claude long-term memory with 13 specialized embedding dimensions. Every memory is embedded simultaneously across semantic, causal, temporal, code, entity, and structural spaces — then fused at search time using Reciprocal Rank Fusion to surface results that no single perspective could find alone.

Store a memory  ──►  13 embedders fire in parallel  ──►  RocksDB + HNSW indexes
Search a query  ──►  6 embedders retrieve candidates ──►  RRF fusion  ──►  ranked results

Most memory systems for AI use a single embedding model and basic vector search. Context Graph takes a fundamentally different approach:

Multi-perspective retrieval. A query like "Why does auth fail under load?" searches simultaneously through semantic similarity (E1), causal reasoning (E5), code patterns (E7), entity linking (E11), graph structure (E8), and paraphrase matching (E10). Each perspective catches what the others miss.

Asymmetric causal reasoning. Three embedders store dual vectors for directional queries. "What caused X?" and "What did X cause?" return different results because cause and effect are embedded separately with directional boosting.

Temporal awareness without temporal bias. Time-based embedders (freshness, periodicity, sequence) are applied as post-retrieval boosts, not during retrieval. This prevents recent memories from drowning out relevant older ones.

56 MCP tools. Not just store-and-search — full causal chain building, entity extraction with TransE predictions, topic discovery via HDBSCAN, code-aware search with AST chunking, file watching, provenance tracking, and LLM-powered relationship discovery.

Production-grade storage. RocksDB with 51 column families, HNSW indexes for O(log n) K-NN search, soft-delete with 30-day recovery, background compaction, and graceful degradation when components fail.

• Rust 1.75+ (stable)
• CUDA toolkit (for GPU-accelerated embeddings via candle)
• RocksDB system library

git clone https://github.com/contextgraph/contextgraph.git
cd contextgraph
make build

# Stdio mode (default — for Claude Code / Claude Desktop)
context-graph-mcp

# TCP mode (remote clients)
context-graph-mcp --transport tcp --port 3100

# Daemon mode (shared server, load models once)
context-graph-mcp --daemon

# Fast startup (models load in background)
context-graph-mcp --no-warm

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "context-graph": {
      "command": "context-graph-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}

Once connected, Claude has access to all 56 MCP tools — persistent memory, causal reasoning, entity linking, code search, and more — with no further configuration.

Every memory is embedded across 13 spaces simultaneously. Each acts as an independent "knowledge lens."

Individual embedders can also be queried directly via search_by_embedder for specialized single-perspective queries (code, causal, entity).

Predefined profiles control how embedders are weighted during multi-space search:

Custom profiles can be created per-session via create_weight_profile.

A query like "Why does the authentication service fail under load?":

1. Intent detection — classified as causal (seeking effects of load)
2. Strategy selection — multi_space with causal_reasoning weight profile
3. Parallel retrieval across 6 active embedders:
   • E1: Semantic HNSW search for "authentication service fail load"
   • E5: Asymmetric causal search (query as cause, searching effect index, 1.2x boost)
   • E7: Code embeddings catch relevant auth service implementations
   • E8: Graph connections find structurally related memories
   • E10: Paraphrase matching catches rephrasings of the same concept
   • E11: Entity linking identifies "authentication service" as a known entity
4. RRF fusion — rankings merged: weight_i / (rank_i + 60) across all embedders
5. Post-retrieval boosts — E2 freshness decay prioritizes recent memories
6. Causal gate — high-confidence causal scores get 1.10x boost, low-confidence get 0.85x demotion
7. Return — top-k results with per-embedder breakdown and full provenance

┌─────────────────────────────────────────────────────┐
│                   MCP Clients                       │
│          (Claude Code, Claude Desktop)              │
└──────────────────────┬──────────────────────────────┘
                       │ JSON-RPC 2.0
                       │ (stdio / TCP)
┌──────────────────────▼──────────────────────────────┐
│              Context Graph MCP Server               │
│                   56 MCP Tools                      │
├─────────────────────────────────────────────────────┤
│  ┌─────────┐  ┌──────────┐  ┌────────────────────┐ │
│  │ Handlers│  │ Transport│  │  Background Tasks  │ │
│  │ (tools) │  │ Layer    │  │  - HNSW compaction │ │
│  │         │  │          │  │  - Soft-delete GC  │ │
│  │         │  │          │  │  - Graph builder   │ │
│  │         │  │          │  │  - File watcher    │ │
│  └────┬────┘  └──────────┘  └────────────────────┘ │
├───────┼─────────────────────────────────────────────┤
│  ┌────▼──────────────────────────────────────────┐  │
│  │          13-Embedder Pipeline                 │  │
│  │  E1 Semantic    E5 Causal     E9  HDC        │  │
│  │  E2 Freshness   E6 Keyword    E10 Paraphrase │  │
│  │  E3 Periodic    E7 Code       E11 Entity     │  │
│  │  E4 Sequence    E8 Graph      E12 ColBERT    │  │
│  │                               E13 SPLADE     │  │
│  └────┬──────────────────────────────────────────┘  │
│  ┌────▼──────────────────────────────────────────┐  │
│  │          RocksDB + HNSW Indexes               │  │
│  │  51 Column Families  │  usearch K-NN Graphs   │  │
│  └───────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘

15 HNSW indexes use usearch for O(log n) K-NN search: 11 base embedder indexes plus 2 asymmetric indexes for E5 (cause/effect) and 2 for E10 (paraphrase/context). E6/E13 (sparse) use inverted indexes. E12 (ColBERT) uses MaxSim token-level scoring. HNSW graphs are persisted to RocksDB and compacted on a 10-minute background interval.

1. CLI arguments (highest)
2. Environment variables (CONTEXT_GRAPH_ prefix)
3. Config files (config/default.toml, config/{env}.toml)
4. Defaults (lowest)

[mcp]
transport = "stdio"
tcp_port = 3100
bind_address = "127.0.0.1"
max_payload_size = 10485760
request_timeout = 30
max_connections = 32

[storage]
backend = "rocksdb"

[watcher]
enabled = true
watch_paths = ["./docs"]
extensions = ["md"]

[watcher.code]
enabled = false
watch_paths = ["./crates"]
extensions = ["rs"]
use_ast_chunker = true
target_chunk_size = 500

The CLI provides Claude Code hooks for automatic memory capture during sessions:

# Set up hooks for Claude Code
context-graph-cli setup

# Manual memory operations
context-graph-cli memory capture --content "learned something" --rationale "important pattern"
context-graph-cli memory inject --query "authentication patterns"
context-graph-cli topic portfolio
context-graph-cli warmup   # Pre-load embeddings into VRAM

Context Graph is designed to keep working when components fail:

• LLM unavailable: 52 of 56 tools work normally. Only trigger_causal_discovery, get_causal_discovery_status, discover_graph_relationships, and validate_graph_link require the LLM feature. Build without llm to skip LLM dependencies (~500MB smaller binary).
• Embedder failure: The pipeline handles individual embedder loading failures. Search falls back to available embedders with degraded-mode tracking.
• Soft-delete: All deletions are soft with a 30-day recovery window. A background GC task runs every 5 minutes to clean up expired deletions.
• HNSW compaction: Background task rebuilds HNSW indexes every 10 minutes. Safe concurrent reads during rebuild.

To build without CUDA (CPU-only embeddings):

cargo build --release --no-default-features --features llm

To build without LLM support (smaller binary, 52 tools):

cargo build --release --no-default-features --features cuda

# Run all tests
make test

# Run E2E hook tests
make test-e2e

# Run MCP server tests
make test-mcp

# Quick check (no linking)
make check

# Lint
make clippy

# Disk usage report
make disk-check

contextgraph/
├── crates/
│   ├── context-graph-mcp/          # MCP server, transport, tool handlers
│   ├── context-graph-core/         # Domain types, config, traits, weight profiles
│   ├── context-graph-storage/      # RocksDB persistence, 51 column families
│   ├── context-graph-embeddings/   # 13-model embedding pipeline (candle)
│   ├── context-graph-graph/        # Knowledge graph with vector search
│   ├── context-graph-cuda/         # GPU acceleration
│   ├── context-graph-cli/          # CLI and Claude Code hooks
│   ├── context-graph-causal-agent/ # LLM-based causal discovery
│   ├── context-graph-graph-agent/  # LLM-based graph relationship discovery
│   ├── context-graph-benchmark/    # Performance benchmarking suite
│   └── context-graph-test-utils/   # Shared test helpers
├── config/                         # Configuration files (TOML)
├── scripts/                        # Build and maintenance scripts
└── Makefile                        # Build targets

• MCP Version: 2024-11-05
• Message Format: Newline-delimited JSON (NDJSON)
• RPC: JSON-RPC 2.0

Licensed under either of:

• Apache License, Version 2.0
• MIT License

at your option.