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

01Why It's Better Than Everything Else

Every other memory system is missing at least 5 of these 10 features. semantic-memory has all of them.

Featuresemantic-memoryZep / GraphitiLetta / MemGPTMem0ChatGPT Memory
Typed graph edges (semantic / temporal / causal / entity)YesTemporal onlyNoNoNo
Provenance on every fact (source, confidence, receipt)YesNoNoNoNo
Bitemporal search (what did I know on date X?)YesNoNoNoNo
Contradiction detection (decoder syndrome analysis)YesNoNoNoNo
Factor graph belief propagation over edgesYesNoNoNoNo
RL-trained adaptive retrieval routingYesNoNoNoNo
Self-correcting (supersede facts when evidence changes)YesNoSelf-editNoNo
Local-first (no cloud, no API keys, no telemetry)YesCloudOptionalCloudCloud
MCP server (48 tools, works with Claude Desktop, Cursor)YesNoNoNoNo
Auto-management (integrity checks, vacuum, re-embed, reconcile)YesNoNoNoNo

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

# Install the MCP server (includes the library) cargo install semantic-memory-mcp # The binary is now at ~/.cargo/bin/semantic-memory-mcp # It uses the candle embedder by default (runs on CPU, no GPU needed)

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.

04What Happens When You Close the Loop

AiDENs is the autonomous loop built on top of semantic-memory. It's in development — not published yet. This shows what the memory system enables when you add autonomous gap detection, LLM execution, and fact quality evaluation on top of it.

01
Detect
KB gaps via
8 missions
02
Generate
Prioritized
JobV1 tasks
03
Execute
LLM via
Ollama
04
Capture
Facts with
provenance
05
Evaluate
Promote /
quarantine / reject
06
Feedback
RL routing
outcome
14
Iterations
12
Tasks Completed
0
Tasks Failed
29
Facts Captured
iter=1 gaps=1 tasks_gen=1 tasks_done=0 tasks_fail=0 facts_cap=0 err=None
iter=3 gaps=1 tasks_gen=1 tasks_done=1 tasks_fail=0 facts_cap=3 DONE
iter=9 gaps=25 tasks_gen=25 tasks_done=5 tasks_fail=4 facts_cap=12 err=None
iter=14 gaps=25 tasks_gen=25 tasks_done=12 tasks_fail=0 facts_cap=29 DONE
After bug fixes: 12/12 completed, 0 failures, 29 facts captured

05Facts the Loop Captured

Real facts captured by the autonomous loop in the "autonomous" namespace. Each fact was generated by the model analyzing a detected gap, then quality-scored by the evaluation gate.

fact:c31cd2e0...missing-context
The fact identifies the crates/aidens-autonomous/Cargo.toml file as a package manifest. Based on the file content and the project structure, this represents the "Brain" of the Loop — the autonomous loop executor that ties together gap detection, task generation, LLM execution, fact capture, and evaluation.
fact:fa3c3f1e...stale-fact
The file /Cargo.toml exists and is accessible, which contradicts the semantic memory integrity report. The discrepancy likely stems from a stale or incorrect reference rather than a missing file.
fact:a29ab206...stale-fact
To verify and fix this, audit all occurrences of the version string in the knowledge base and standardize them to the semantic version "v0.2.0".
fact:3f4829c6...contradiction-gap
In the context of AiDENs, this represents the "domain truth" owned by the semantic-memory and semantic-memory-forge crates, which AiDENs is tasked to wire and coordinate without duplicating.
fact:86fa287b...stale-fact
The staleness of this fact is likely caused by a version or description mismatch between the semantic memory and the current Cargo.toml of the llm-tool-runtime crate.

06Related Crates

The system is built from independent, reusable crates published on crates.io.