semantic-memory
A typed knowledge graph with provenance, bitemporal search, contradiction detection, and 48 MCP tools. Available now as a Rust crate and MCP server. Works with Claude Desktop, Cursor, Hermes, and any MCP-compatible client.
TL;DR — semantic-memory is a local-first knowledge graph for AI agents. Unlike Zep, MemGPT, or ChatGPT memory, it has provenance on every fact, bitemporal search (it knows what it believed on any date), typed graph edges, contradiction detection, factor graph belief propagation, and RL-trained adaptive retrieval routing. It runs on your machine — no cloud, no API keys, no telemetry. 7,228 facts, 48 MCP tools, 15 HTTP endpoints, 126 MB DB.
7,228 facts
15,413 chunks
877 documents
48 MCP tools
15 HTTP endpoints
126 MB DB
02How It Works
Two crates work together: the library and the MCP server. The library is the knowledge graph engine. The MCP server exposes it to AI agents.
semantic-memory (Rust library)
The core knowledge graph engine. Stores facts as typed nodes with heterogeneous edges (semantic, temporal, causal, entity). Every fact has provenance — source attribution, confidence score, and a receipt. Facts can be superseded when better evidence arrives. The system is bitemporal — it tracks when facts were valid and when they were superseded.
- Hybrid search: BM25 + vector + RRF (Reciprocal Rank Fusion)
- Adaptive routing: RL-trained policy learns which retrieval stages help which query types (class A through E)
- Contradiction detection: decoder syndrome analysis finds conflicting facts among search results
- Factor graph belief propagation: heterogeneous typed edges become factors; confidence propagates across the graph
- Community detection: Leiden-inspired community detection for knowledge graph compression
- Topology analysis: finds structural voids (MissingContext, MissingLink, ContradictionGap)
- Lifecycle management: identifies subtraction candidates (low-structuring-score facts safe to forget/compress)
- Auto-management: integrity checks (WAL, FTS, HNSW), vacuum, re-embed, reconcile — all via HTTP
semantic-memory-mcp (MCP server)
The MCP server wraps the library in 48 tools and 15 HTTP endpoints. It works with Claude Desktop, Cursor, Hermes, and any MCP-compatible client. Tool profile gating (lean / standard / full) keeps the tool list manageable — 34 daily-use tools in lean mode, 14 admin/audit tools hidden until needed.
- 34 daily-use tools: search, search_with_routing, get_fact, list_facts, add_fact, update_fact, supersede_fact, add_graph_edge, list_graph_edges, graph_path, get_fact_neighbors, discord_search, community, topology, detect_contradictions, decoder_analyze, factor_graph, verify_claim, create_claim, add_evidence, judge_support, and more
- 14 admin/audit tools: reconcile, vacuum, reembed_all, embeddings_are_dirty, get_search_receipt, replay_search_receipt, query_claim_versions, query_relation_versions, query_episodes, query_entity_aliases, query_evidence_refs, import_envelope, import_status, list_imports
- 15 HTTP endpoints: /health, /search, /search-routed (full pipeline: decoder + discord + factor-graph), /discord, /rerank, /stats, /add, /record-outcome (RL feedback), /verify-integrity (real check), /maintenance/check, /maintenance/vacuum, /maintenance/reembed, /maintenance/reconcile, /maintenance/compact-hnsw
- RL routing persistence: every search outcome feeds the adaptive retrieval policy via /record-outcome. The policy is stored in SQLite and loaded on every search_with_routing call
- Claude Code plugin: hooks for auto-recall (pre-LLM), auto-capture (post-LLM), dedup guard (pre-tool), receipts (post-tool), primer (session start), and maintenance (daily cron)
03Install and Configure
Install the MCP server, add it to your client config, and you're done. Works with any MCP-compatible client.
Step 1: Install the binary
cargo install semantic-memory-mcp
Step 2: Add to Claude Desktop
Add this to your Claude Desktop config (Settings → Developer → Edit Config):
{
"mcpServers": {
"semantic_memory": {
"command": "semantic-memory-mcp",
"args": [
"--memory-dir", "~/.semantic-memory/sm.db",
"--embedder", "candle",
"--http-port", "1738",
"--tool-profile", "lean"
]
}
}
}
Step 3: Add to Cursor
Add this to your Cursor MCP settings:
{
"mcpServers": {
"semantic_memory": {
"command": "semantic-memory-mcp",
"args": ["--memory-dir", "~/.semantic-memory/sm.db"]
}
}
}
Tool profiles
Three profiles control which tools are visible to the agent:
- lean (default, 34 tools) — daily-use: search, graph traversal, fact CRUD, claim verification. Hides admin/audit tools
- standard (45 tools) — adds maintenance, audit, and bitemporal query tools. For power users
- full (48 tools) — everything, including import tools. For debugging and bulk operations
Switch with --tool-profile lean|standard|full. No recompilation needed.