MIND-Mem is a deterministic AI memory system: recall is defined by the query, admitted corpus, configuration, scoring instant, and execution providers. With those inputs held constant, its canonical audit/evidence encoding is byte-identical across replay; ranking scores themselves remain standard floating-point. The Q16.16 fixed-point audit chain is embedded in every applied decision.
scoring_instant is a UTC date and is the honest part of that claim: recency ranking is load-bearing for a coding agent, so it is not deleted, it is named. Omit it and it resolves to today in UTC — the one clock read on the whole path, taken once at the boundary, never inside the scoring loop. Its resolved value is bound into the recall attestation, so any attested run replays exactly by passing that date back.
Built on the MIND substrate. Governed-write (propose → review → approve_apply). 107 MCP tools as the surface — but the differentiator is the substrate underneath. On the same workspace, recall uses the query, admitted corpus, configuration, scoring_instant, and execution providers. With those inputs held constant, the canonical audit/evidence encoding is byte-identical across replay; ranking scores remain standard floating-point, so this does not promise universal cross-provider result identity.
Most memory layers ship tools. That is table-stakes. MIND-Mem ships a substrate: Q16.16 fixed-point encoding in the audit-hash preimage, a governance pipeline that rejects every unreviewed write, and an audit chain where every applied proposal is hash-anchored. The scoring path itself is pure Python (mind_kernels.py): the wheel ships MIND-language kernel sources under mind/ and no compiled kernel, and the optional native libmindmem.so is built from lib/kernels.c (C99). The substrate claim is the encoding, the gate and the chain — not the kernels, which are not compiled yet. The same query on the same workspace with the same admitted corpus, configuration, scoring instant and execution providers produces repeatable ranked recall; that recall's canonical audit/replay encoding is byte-identical under those held-constant conditions. That property is what makes MIND-Mem suitable as a canonical memory layer across heterogeneous agent stacks.
If your agent runs for weeks, it will drift. MIND-Mem prevents silent drift.
MIND-Mem powers the Memory Plane of the MIND Cognitive Kernel — the deterministic AI runtime architecture.
30-Second Demo
pip install mind-mem
mind-mem-init ~/my-workspace # Create workspace
mind-mem-recall -q "API decisions" --workspace ~/my-workspace # Hybrid BM25F search
mind-mem-scan ~/my-workspace # Detect drift & contradictions
Output:
[1.204] D-20260215-001 (decision) — Use async/await for all API endpoints
decisions/DECISIONS.md:11
[1.094] D-20260210-003 (decision) — REST over GraphQL for public API
decisions/DECISIONS.md:20
Current release: v5.0.4 (candidate; publication pending) — corrects lifecycle ranking and graph admission, strengthens release validation, and adds source-only training preparation. See CHANGELOG.md for candidate changes and published release history.
Substrate Properties
Table of Contents
- Why MIND-Mem
- Features
- Integrations are the substrate working
- Benchmark Results
- Quick Start
- Health Summary
- Commands
- Architecture
- How It Compares
- Companion Tools
- Recall
- MIND Kernels
- Auto-Capture
- Multi-Agent Memory
- Governance Modes
- Block Format
- Configuration
- MCP Server
- Security
- Troubleshooting
- MIND language sources
- Contributing
- License
Deep-dive docs
docs/setup.md— install, configure, wire MCP, opt in to MIND native kernelsdocs/usage.md— every surface (MCP tools by category,mmCLI,mind-mem-verify, Python library) with worked examplesdocs/client-integrations.md— 69 AI client integrations (Claude Code, Claude Desktop, Codex, Grok Build, Vibe, OpenCode, Gemini, Cursor, Windsurf, VS Code, Zed, Copilot CLI, Qwen Code, Kimi Code, Amp, goose, Kiro, Junie, Cline, Roo, Continue, Antigravity and more; manual steps for UI-only apps) withmm install-allauto-detection and a per-client source tabledocs/task-frames.md— task frames + the dead-end registry:[TF-...]multi-session continuity (resume_brief,mm resume) and[DE-...]negative action-space memory, matched by a deterministic declarative overlap that warns and never blocksdocs/review.md—mm review: batch approval for the HITL queue — pending proposals with their pre-apply diff, provenance, chain status and staleness inline, approved or rejected many at once through the governedapprove_applypath, with no auto-approve at any risk leveldocs/mind-mem-4b-setup.md— download + run thestar-ga/mind-mem-4bfull-FT model locally (transformers, exllamav2, vLLM, llama.cpp, Ollama, MindLLM)docs/companion-tools.md— companion tools that complement (not compete with) mind-mem: MindLLM (STARGA, commercial) for deterministic + evidence-chained inference, GitNexus for code knowledge-graphROADMAP.md— feature roadmap (genuinely-open items at the top; bulk of v3.2.0→v4.0.0 shipped)docs/specs/retrieval-receipt-contract.md— draft portable retrieval-evidence contract and acceptance gates; optional billing and settlement remain demand-gatedCHANGELOG.md— release notes for every published version
Why MIND-Mem
Most memory plugins store and retrieve. That's table stakes.
MIND-Mem also detects when your memory is wrong — contradictions between decisions, drift from informal choices never formalized, dead decisions nobody references, orphan tasks pointing at nothing — and offers a safe path to fix it.
Novel Contributions
MIND-Mem introduces several techniques not found in existing memory systems:
Features
Hybrid BM25+Vector Search with RRF Fusion
Thread-parallel BM25 and vector search with Reciprocal Rank Fusion (k=60). Configurable weights per signal. Vector is optional — works with just BM25 out of the box.
RM3 Dynamic Query Expansion
Pseudo-relevance feedback using JM-smoothed language models. Expands queries with top terms from initial result set. Falls back to static synonyms for adversarial queries. Zero dependencies.
9-Type Intent Router
Classifies queries into WHY, WHEN, ENTITY, WHAT, HOW, LIST, VERIFY, COMPARE, or TRACE. Each intent type maps to optimized retrieval parameters (limits, expansion settings, graph traversal depth).
A-MEM Metadata Evolution
Auto-maintained per-block metadata: access counts, importance scores (clamped to [0.8, 1.5] reranking boost), keyword evolution, and co-occurrence tracking. Importance decays with exponential recency.
Deterministic Reranking
Four-signal reranking pipeline: negation awareness (penalizes contradicting results), date proximity (Gaussian decay), 20-category taxonomy matching, and recency boosting. No ML required.
Optional Cross-Encoder
Drop-in ms-marco-MiniLM-L-6-v2 cross-encoder (80MB). Blends 0.6 * CE + 0.4 * original score. Falls back gracefully when unavailable. Enabled via config.
MIND Kernel Sources and Configuration
The mind/ directory contains 26 .mind files: 18 INI-style pipeline
configurations and eight MIND-language tensor-source prototypes. The
configuration files are parsed by mind_ffi.py; the source prototypes are
migration work and are not a native serving backend. See
docs/MIND_CONFIG_VS_MIND_LANG.md for the
verified split. The pure-Python scoring logic in
src/mind_mem/mind_kernels.py remains authoritative. An optional C library
implements the existing native scoring ABI when a compatible library is
provided.
MIC/MAP — MIND IR graph serialization
Pure-Python codec for the STARGA wire formats: mic@2 (line-oriented
text, LLM-readable, git-friendly) and MIC-B (varint binary, ~4×
smaller). Both encode typed dataflow graphs (symbols + types + values +
output) with byte-identical round-trip. Streaming parser for bounded peak
memory; optional Cython accelerator via mind-mem[accelerated]
(+16/+20/+36 % on parse). Two MCP tools (mic_convert, mic_inspect) and
a mm mic CLI surface it for agents and operators. See
docs/mic-map.md. Note that the canonical IR per
RFC 0021 is mic@1 text + mic@3 binary (see
mindlang.dev/docs/mic); the mic@2/MIC-B
codec mind-mem ships is the back-compat lineage.
BM25F Hybrid Recall
BM25F field-weighted scoring (k1=1.2, b=0.75) with per-field weighting (Statement: 3x, Title: 2.5x, Name: 2x, Summary: 1.5x), Porter stemming, bigram phrase matching (25% boost per hit), overlapping sentence chunking (3-sentence windows with 1-sentence overlap), domain-aware query expansion, and optional 2-hop graph-based cross-reference neighbor boosting. Zero dependencies. Fast and deterministic.
Graph-Based Recall
2-hop cross-reference neighbor boosting — when a keyword match is found, blocks that reference or are referenced by the match get boosted (1-hop: 0.3x decay, 2-hop: 0.1x decay). Surfaces related decisions, tasks, and entities that share no keywords but are structurally connected. Auto-enabled for multi-hop queries.
Vector Recall (optional)
Pluggable embedding backend — local ONNX (all-MiniLM-L6-v2, no server needed) or cloud (Pinecone). Falls back to BM25 when unavailable.
Persistent Memory
Structured, validated, append-only decisions / tasks / entities / incidents with provenance and supersede chains. Plain Markdown files — readable by humans, parseable by machines.
Immune System
Continuous integrity checking: contradictions, drift, dead decisions, orphan tasks, coverage scoring, regression detection. Structural validation via validate.sh / validate_py (17 checks on a fresh workspace; the count grows with the blocks present).
Safe Governance
All changes flow through graduated modes: detect_only → propose → enforce. Apply engine with snapshot, receipt, DIFF, and automatic rollback on validation failure.
Adversarial Abstention Classifier
Deterministic pre-LLM confidence gate for adversarial/verification queries. Computes confidence from entity overlap, BM25 score, speaker coverage, evidence density, and negation asymmetry. Below threshold → forces abstention without calling the LLM, preventing hallucinated answers to unanswerable questions.
Auto-Capture with Structured Extraction
Session-end hook detects decision/task language (27 patterns with confidence classification), extracts structured metadata (subject, object, tags), and writes to SIGNALS.md only. Never touches source of truth directly. All signals go through /apply.
Tool-Output Offload (v4.2.0)
A single cargo test / pytest / build run dumps 10k–50k lines into an agent's context — the biggest single token sink for coding agents. mm tool-run -- <cmd> stores the full output out-of-context (a tool_outputs sibling table; SQLite by default, reuses the Postgres connection with no new DB) and returns only a compact {handle, summary}; mm tool-recall <handle> returns the full text on demand. The summary is bounded regardless of input (a 10 MB line or 100k error lines can't blow it up), fail-safe (the full text is always stored and every truncation is explicit and counted — a failure line is never silently dropped), and deterministic (pure pattern extraction, no LLM; versioned config). See docs/tool-output-architecture.md.
Concurrency Safety
Cross-platform advisory file locking (fcntl/msvcrt/atomic create) protects all concurrent write paths. Stale lock detection with PID-based cleanup. Zero dependencies.
Compaction & GC
Automated workspace maintenance: archive completed blocks, clean up old snapshots, compact resolved signals, archive daily logs into yearly files. Configurable thresholds with dry-run mode.
Observability
Structured JSON logging (via stdlib), in-process metrics counters, and timing context managers. All scripts emit machine-parseable events. Controlled via MIND_MEM_LOG_LEVEL env var.
Multi-Agent Namespaces & ACL
Workspace-level + per-agent private namespaces with JSON-based ACL. fnmatch pattern matching for agent policies. Shared fact ledger for cross-agent propagation with dedup and review gate.
Automated Conflict Resolution
Graduated resolution pipeline: timestamp priority, confidence priority, scope specificity, manual fallback. Generates supersede proposals with integrity hashes. Human veto loop — never auto-applies without review.
Write-Ahead Log (WAL) + Backup/Restore
Crash-safe writes via journal-based WAL. Full workspace backup (tar.gz), git-friendly JSONL export, selective restore with conflict detection and path traversal protection.
Transcript JSONL Capture
Scans Claude Code transcript files for user corrections, convention discoveries, bug fix insights, and architectural decisions. 16 transcript-specific patterns with role filtering and confidence classification.
MCP Server (107 tools, 8 resources)
Full Model Context Protocol server with 107 distinct tools and 8 read-only resources (6 static + 2 templated). Works with Claude Code, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client. HTTP and stdio transports; HTTP requires bearer-token auth (fail-closed) — see Token Auth (HTTP). v3.8.11 added mic_convert_tool / mic_inspect_tool (MIC/MAP wire format); v3.9.0 added compile_truth_walkthrough, recall_with_persona, pipeline_status, and reindex_dirty; v3.11.0 added validate_block, block_lineage, and add_block_edge (deterministic quality gates + typed lineage edges).
Structural Validation + 13,258 Test Functions
validate.sh checks schemas, cross-references, ID formats, status values, supersede chains, ConstraintSignatures, and more. The repository contains 13,258 test functions across the core and optional surfaces; collected case counts also depend on parametrization, optional dependencies and test selectors.
Audit Trail
Every applied proposal logged with timestamp, receipt, and DIFF. Full traceability from signal → proposal → decision.
Calibration Feedback Loop
Per-block quality tracking with Bayesian weight computation. When users provide feedback (thumbs up/down) via calibration_feedback, the system maintains a rolling quality score per block over a 30-day window. Bayesian smoothing constrains calibration weights to the 0.5-1.5 range, preventing any single block from dominating or being silenced. Calibration weights integrate directly into the BM25 + FTS5 retrieval pipeline — high-quality blocks rank higher, low-quality blocks are naturally demoted. Use calibration_stats to inspect per-block quality distributions and global calibration health. With v4.llm_noise_profile enabled (default off), it also carries an llm_reliability section: a per-provider, per-domain reliability EMA fed by report_outcome and persisted to intelligence/llm_profiles.json. Reliability is evidence for an operator reading the record — nothing on the retrieval scoring path reads it.
LLM-Guided Multi-Query Expansion
Generates semantically diverse query reformulations before search — synonym expansion, specificity shifts, temporal rephrasing, and negation variants. Combines all reformulated queries with Reciprocal Rank Fusion for broader recall without sacrificing precision. Runs locally with zero API calls.
4-Layer Search Deduplication
Post-retrieval dedup pipeline: best-chunk-per-source (keeps highest-scoring chunk from each file), cosine similarity dedup (>0.85 threshold), type diversity capping (max 3 results per block type), and per-source chunk limiting. Eliminates redundant results that waste LLM context.
LLM-Guided Smart Chunking
Content-aware chunking that splits at semantic boundaries (headers, paragraph breaks, list items, code blocks) instead of fixed character counts. Produces variable-size chunks with overlap for continuity. Supports markdown, code, and prose with format-specific splitting rules.
Compiled Truth Pages
Per-entity knowledge compilation: current-best-understanding on top, timestamped evidence trail below. Contradiction detection across evidence entries with automatic flagging. Entities accumulate knowledge from all sessions — each new evidence entry is checked against existing facts.
Dream Cycle (Autonomous Memory Enrichment)
Scheduled background enrichment: scans recent memory for missing cross-references, broken citations, orphan entities, and consolidation opportunities. Generates repair proposals for stale links, detects implicit entities not yet formalized, and compacts redundant entries. Runs during idle periods with configurable depth.
Feature Completeness Matrix
Cells were checked against each project's public source or, where the engine is closed (Supermemory's engine, Graphlit), its official docs, in October 2026. Several retrieval legs exist in other projects only behind an optional backend; see the Full Feature Matrix below.
Columns: MM MIND-Mem · M0 Mem0 · SM Supermemory · CM claude-mem · Le Letta · Zep Zep · LM LangMem · Co Cognee · GL Graphlit · CW ClawMem · MU MemU · En Engram · BM Basic Memory · OV OpenViking
Cells: ✓ present · ◐ partial or a different mechanism · opt present but off by default · — looked for and not found · n/v not verified (closed engine or undocumented) · N/A not applicable · ↓n see note n under the table. Small notes under each table carry the qualifiers.
Recall
1 MIND-Mem: BM25+vector+RRF2 MIND-Mem: 9 types3 MIND-Mem: RM34 MIND-Mem: co-retrieval PageRank5 MIND-Mem: 4 layers
Persistence
1 compiled, per entity2 MIND-Mem: dream cycle3 with zip-slip protection
Integrity
Governance
1 governance pipeline2 several agents can read and write one store, via MCP or API. The Full Feature Matrix row "Multi-agent" is stricter: per-agent identity and isolation (◐ = shared store without per-agent isolation)
Operations
1 no cloud required2 optional backend
Integrations are the substrate working
MIND-Mem provides integrations for 69 supported clients, including 41 MCP-aware clients (22 more get printed manual MCP steps). They can share a governed memory workspace. Reproducing a recall result requires the same request, corpus, configuration, scoring instant and execution dependencies; the client count alone does not establish cross-client output identity.
Honest positioning: the integrations below are software-level — clients use their configured MCP connection or local integration. They are not commercial-customer relationships with any vendor. Full positioning policy:
docs/integrations.md.
Native integration with 69 clients (41 MCP-aware clients)
pip install mind-mem
mm install-all
mm install-all auto-detects every supported client on your machine
and writes the appropriate config file for each. MIND-Mem speaks the
Model Context Protocol — any
MCP-compatible client connects with one command.
auto MCP: the mind-mem server entry is merged into the client's own config
file. manual MCP: the client has MCP but no per-user file to merge into (UI,
per-deployment or HTTP-only); mm install-all --agent <id> prints the exact
steps and snippet. none: no native MCP; an instruction or hook file routes
memory access through the mm CLI. Each entry was checked against the client's
current documentation; the source per client is in
docs/client-integrations.md.
Compatible with major LLM providers
MIND-Mem's recall pipeline is provider-agnostic: any MCP-capable client or
OpenAI-compatible endpoint can use the same server interface. The provider
adapters (Anthropic; OpenAI-compatible, which Mistral and other OpenAI-style
APIs route through; Ollama; vLLM; llama.cpp) are covered by mocked contract
tests, which make no live call. The
only model-in-the-loop benchmark run so far is LoCoMo, with
mistral-large-latest as answerer and judge. We do not claim live testing
against specific versions of other vendors' models. Replay also requires the
same query, admitted corpus, configuration, scoring instant, execution
providers and dependencies; different client models can generate different
queries.
Production usage at STARGA
MIND-Mem is the daily-driver memory layer across STARGA's active
projects, including mind, mindlang.dev, mind-inference, and
arch-mind. First-party, verifiable in our own commit history.
What we do not claim
- ❌ "OpenAI / Microsoft / Anthropic / Google is a customer" — false. These are software-level MCP integrations, not commercial relationships.
- ❌ "Used by N production teams outside STARGA" — we have no telemetry. PyPI download counts measure installs, not active use.
If a future integration becomes a real commercial relationship (signed contract, paid pilot, named reference), it will appear in the press release first — not in the README.
Benchmark Results
MIND-Mem's recall engine evaluated on standard long-term memory benchmarks using multiple configurations — from pure BM25 to full hybrid retrieval with neural reranking.
Needle In A Haystack (NIAH)
250/250 — 100% retrieval across all haystack sizes, burial depths, and needle types.
Provenance. The full-matrix repro package is committed at
benchmarks/repro/niah/(raw per-case rows, recomputed metrics, and a manifest pinning the commit, config, seeds and hardware — produced on a clean tree,repo_tracked_files_dirty_at_run: false).make repro-verifyrecomputes the 250/250 headline from those raw rows rather than trusting the manifest's summary. This is first-party evidence: nobody outside STARGA has re-run it yet and reported the samemetrics.determinism.decision_fingerprint— see EVIDENCE.md row 1 for exactly what "verified" does and does not mean here.
A single fact is planted at a controlled depth within a haystack of semantically diverse filler blocks. The system must retrieve the needle in its top-5 results using only a natural-language query.
Config: Hybrid BM25 + all-MiniLM-L6-v2 + RRF (k=60) + sqlite-vec. Full details: benchmarks/NIAH.md
LoCoMo LLM-as-Judge
Same pipeline as Mem0 and Letta evaluations: retrieve context, generate answer with LLM, score against gold reference with judge LLM. Directly comparable methodology.
Canonical flagship number: the full 10-conversation (1986-question) BM25 run directly below (Overall Acc>=50 73.8%, Mean 70.5) — see
docs/benchmarks.mdfor scope, evidence, and reproduction. All other LoCoMo tables on this page are smaller historical subsamples, kept for their per-category detail — do not treat any of them as the headline number.
v1.0.7 — Hybrid + top_k=18 (external LLM answerer + judge, conv-0 subsample, 199 of 1986 questions — 10% of the full set; no raw per-question artifact is checked into this repo for this run):
Pipeline: BM25 + Qwen3-Embedding-8B (4096d) vector search → RRF fusion (k=60) → top-18 evidence blocks → observation compression → answer → judge. A/B validated: +2.8 mean vs top_k=10 baseline.
v1.1.1 — BM25 + top_k=18 (canonical — full dataset) (external LLM answerer + judge, 10 conversations, 1986 questions):
Pipeline: BM25 + RM3 query expansion → top-18 evidence blocks → observation compression → answer → judge. Full 10-conversation benchmark with the same external LLM as both answerer and judge.
v1.0.0 — BM25-only baseline (external LLM answerer + judge, 10 conversations):
Key improvements since v1.0.0: Adversarial accuracy tripled from 36.3% to 92.4% via abstention classifier + hybrid retrieval. Overall Acc≥50 improved from 67.3% to 73.8% (+6.5pp).
Competitive Landscape (LoCoMo)
Full 10-conversation (1986-question) LoCoMo, Acc>=50 — apples-to-apples scope
and metric. Canonical MIND-Mem table + evidence:
docs/benchmarks.md.
On this metric MIND-Mem is not the top score — Memobase and Letta report
slightly higher, both on cloud infrastructure with embedding + vector-DB
dependencies. MIND-Mem's differentiator is not "wins every cell"; it's being
the only local-only, zero-core-dependency, governed system in the table —
governance (contradiction detection, drift analysis, proposal/review/apply
audit trail, byte-identical replay) is a property no other row has, and it
is not measured by this benchmark at all.
¹ Third-party self-reported numbers (Letta's August 2025 analysis — see "Why Plain Files Outperform Fancy Retrieval" below). Not re-run by MIND-Mem, and not measured under a shared contract: different hardware, different judge configuration, and each system's own harness. Rows in this table are therefore indicative of scope, not a head-to-head result, and none of them — including ours — has been reproduced by the others. A genuine comparison requires every system run under one adapter contract on one box with a pinned judge and >=2 reps; that run does not exist yet, and until it does no ordering in this table should be read as a ranking.
² 66.88 is Mem0's own published LoCoMo-paper number. Mem0's separate 2026
managed platform self-reports 91.6 on LoCoMo — a different setup/judge
(hosted product, not the open-paper config), not apples-to-apples with this
table. Surfaced rather than omitted, per policy: never publish a comparison
a skeptic could catch as cherry-picked.
³ OpenViking (0.3.22) self-reports 80.3–82.9% LoCoMo accuracy for three agent integrations. It is not a row here because the scope and metric differ: its scripts drop the 446 adversarial (category 5) questions and score the other 1,540, use a binary LLM judge told to accept any answer that "touches on the same topic" as the gold answer, and measure the whole agent (harness, memory and hosted Doubao models), not the memory layer alone. Not re-run by MIND-Mem.
LongMemEval-S
The previous headline (
R@5 = 85.3) is retracted, not held — it had no committed artifact, was not reproducible after two attempts, and its own per-category rows summed to 376 under a stated N=470. It is replaced by the measurement below, which ships with per-question NDJSON so anyone can recompute it. Seebenchmarks/STATUS.mdandbenchmarks/REPORT.md.
Full eligible set (470 of 500; 30 abstention questions excluded), two reps identical per
question, artifacts under docs/benchmarks/2026-09-03-longmemeval-s-full-*.
Configuration: BM25F/SQLite with the vector leg OFF — one leg of the product, not the
shipped hybrid. The hybrid number does not exist yet and nothing here may be read as one.
Paired over the same 470 question ids: on the official strict protocol
(recall_all@5) the two are statistically indistinguishable (McNemar exact, p=0.4799);
the zero-dependency baseline is better on the lenient protocol (recall_any@5, p=0.0043)
and on MRR (p=0.0013). An independent audit refuted every artefact explanation — the
recall caps are genuinely off in the pinned config, there is no ingest truncation, and
index fragment ids never reach recall — so the deficit is ordering quality, not
candidate recall. That is the work in flight; we publish the number that exists rather
than the one we want.
Performance (Latency & Throughput)
Measured on a single developer workstation (commodity x86-64, warm cache, single process) against a 65-block workspace (typical personal workspace) with the SQLite FTS5 backend. Absolute latencies are hardware-dependent — the portable claim is the O(log N) scaling noted below, not the millisecond figures. These figures come from a single-workstation run; no committed artifact backs them yet and make repro-verify does not cover them:
Query latency scales as O(log N) with SQLite FTS5 (vs O(corpus) for scan backend). The co-retrieval graph adds < 1ms per query. Knee cutoff and fact aggregation add negligible overhead (< 0.5ms).
Feedback-Quality -> Downstream-Success (synthetic, deterministic)
Downstream-success prediction (synthetic, deterministic): starved 0.00 -> sufficient 1.00 at matched budget. 48-episode regression gate over the v4.7.0 per-hit feedback-quality credit + v4.8.0 recall-sufficiency score; see benchmarks/REPORT.md and benchmarks/feedback_success_bench.py.
Run Benchmarks Yourself
# Retrieval-only (R@K metrics)
python3 benchmarks/locomo_harness.py
python3 benchmarks/longmemeval_harness.py
# LLM-as-judge (accuracy metrics, requires API key)
python3 benchmarks/locomo_judge.py --dry-run
python3 benchmarks/locomo_judge.py --answerer-model <your-answerer-model> --output results.json
# Hybrid retrieval with any model pair (BM25 + vector + cross-encoder)
python3 benchmarks/locomo_judge.py --hybrid --compress --answerer-model <your-answerer-model> --judge-model <your-judge-model> --output results.json
# Selective conversations
python3 benchmarks/locomo_harness.py --conv-ids 4,7,8
Install in 3 commands
pip install mind-mem
mm install-all --force # auto-wires every detected AI CLI
mm install-model # downloads mind-mem-4b GGUF + imports to Ollama
Full options + Postgres setup + troubleshooting: docs/install-guide.md
Quick Start
One-line install (recommended)
pipx install "mind-mem[mcp]"
mind-mem-mcp --help # smoke-test
pipx keeps MIND-Mem in its own venv, exposes the mind-mem-mcp console
script on PATH, and avoids polluting your system Python. If you don't have
pipx, pip install --user "mind-mem[mcp]" works too.
Then wire it into every AI coding client on your machine:
git clone https://github.com/star-ga/mind-mem.git
cd mind-mem
./install.sh --all --no-install # Already installed via pipx, just wire clients
Or do both in one shot (the installer will auto-pick pipx if available, else fall back to pip):
git clone https://github.com/star-ga/mind-mem.git
cd mind-mem
./install.sh --all
./install.sh has dedicated flags for eight clients (Claude Code, Claude
Desktop, Codex CLI, Gemini CLI, Cursor, Windsurf, Zed and OpenClaw); every
other registry client is wired with ./install.sh --client <id>, and --all
covers every detected one. Each client launches the same MCP server, so all
agents share one workspace.
For the full set of 69 clients (41 of them get an automatic MCP entry), use
mm install-all after installing the package; it auto-detects what is on
your machine and writes these files (Linux paths shown; macOS and Windows
locations are resolved per platform):
Cline and Roo Code: the installer writes desktop VS Code's settings tree (
~/.config/Code/User/on Linux) and, when present, the VS Code Server (remote / WSL) copy under~/.vscode-server/data/User/.
Selective install:
./install.sh --claude-code --codex --gemini # Only specific clients
./install.sh --all --workspace ~/my-project/memory # Custom workspace path
Uninstall:
./uninstall.sh # Remove from all clients (keeps workspace data)
./uninstall.sh --purge # Remove everything including workspace data
Manual Setup
For manual or per-project setup:
1. Clone into your project
cd /path/to/your/project
git clone https://github.com/star-ga/mind-mem.git .mind-mem
2. Initialize workspace
PYTHONPATH=.mind-mem/src python3 -m mind_mem.init_workspace .
# or, after `pip install -e .mind-mem`: mind-mem-init .
Creates the directory tree, the template files and the mind-mem.json config. Never overwrites existing files.
3. Validate
bash .mind-mem/src/mind_mem/validate.sh .
# or cross-platform:
PYTHONPATH=.mind-mem/src python3 -m mind_mem.validate_py .
Expected: 0 issues (17 checks on a fresh workspace; warnings for empty sections are normal).
4. First scan
PYTHONPATH=.mind-mem/src python3 -m mind_mem.intel_scan .
Expected: 0 critical | 0 warnings on a fresh workspace.
5. Verify recall + capture
PYTHONPATH=.mind-mem/src python3 -m mind_mem.recall --query "test" --workspace .
# → No results found. (empty workspace — correct)
PYTHONPATH=.mind-mem/src python3 -m mind_mem.capture .
# → capture: no daily log for YYYY-MM-DD, nothing to scan (correct)
6. Add hooks (optional)
Option A: Claude Code hooks (recommended)
Merge into your .claude/hooks.json:
{
"hooks": [
{
"event": "SessionStart",
"command": "bash .mind-mem/hooks/session-start.sh"
},
{
"event": "Stop",
"command": "bash .mind-mem/hooks/session-end.sh"
}
]
}
Option B: OpenClaw hooks (for OpenClaw 2026.2+)
cp -r .mind-mem/hooks/openclaw/mind-mem ~/.openclaw/hooks/mind-mem
openclaw hooks enable mind-mem
7. Smoke Test (optional)
bash .mind-mem/src/mind_mem/smoke_test.sh
Creates a temp workspace, runs init → validate → scan → recall → capture → pytest, then cleans up.
Health Summary
After setup, this is what a healthy workspace looks like:
$ python3 -m mind_mem.intel_scan .
mind-mem Intelligence Scan Report v2.0
Mode: detect_only
=== 1. CONTRADICTION DETECTION ===
OK: No contradictions found among 25 signatures.
=== 2. DRIFT ANALYSIS ===
OK: All active decisions referenced or exempt.
INFO: Metrics: active_decisions=17, active_tasks=7, blocked=0,
dead_decisions=0, incidents=3, decision_coverage=100%
=== 3. DECISION IMPACT GRAPH ===
OK: Built impact graph: 11 decision(s) with edges.
=== 4. STATE SNAPSHOT ===
OK: Snapshot saved.
=== 5. WEEKLY BRIEFING ===
OK: Briefing generated.
TOTAL: 0 critical | 0 warnings | 16 info
Commands
The three skills above live in skills/.
Agent skill: CLI user manual
Agents that prefer the shell over MCP can install a mind-mem skill that works
as a user manual for the mm CLI. Its SKILL.md
is a table of contents — what mind-mem is, which command to run for which job,
and how governed writes work — and it points to reference files the agent opens
only when it needs them:
mm skill install # -> ~/.claude/skills/mind-mem
mm skill install --target ~/.codex/skills # any agent that reads SKILL.md folders
The skill ships inside the package. tests/test_skill_manual.py fails the build
if a documented command, flag, environment variable or config key stops
existing, and python3 scripts/gen_skill_cli_reference.py regenerates the CLI
reference after the parser changes.
Architecture
your-workspace/
├── mcp_server.py # MCP server (FastMCP, 107 tools, 8 resources)
├── mind-mem.json # Config
├── MEMORY.md # Protocol rules
│
├── mind/ # 26 .mind files: 18 INI config + 8 MIND sources
│ ├── README.md # Source/config inventory and migration status
│ ├── bm25.mind # MIND-language source prototype
│ ├── rrf.mind # MIND-language source prototype
│ ├── ranking.mind # MIND-language source prototype
│ └── recall.mind # INI pipeline configuration example
│
├── lib/ # Optional native C scoring backend
│ └── libmindmem.so # Locally built from lib/kernels.c; not bundled
│
├── decisions/
│ └── DECISIONS.md # Formal decisions [D-YYYYMMDD-###]
├── tasks/
│ └── TASKS.md # Tasks [T-YYYYMMDD-###]
├── entities/
│ ├── projects.md # [PRJ-###]
│ ├── people.md # [PER-###]
│ ├── tools.md # [TOOL-###]
│ └── incidents.md # [INC-###]
│
├── memory/
│ ├── YYYY-MM-DD.md # Daily logs (append-only)
│ ├── intel-state.json # Scanner state + metrics
│ └── maint-state.json # Maintenance state
│
├── summaries/
│ ├── weekly/ # Weekly summaries
│ └── daily/ # Daily summaries
│
├── intelligence/
│ ├── CONTRADICTIONS.md # Detected contradictions
│ ├── DRIFT.md # Drift detections
│ ├── SIGNALS.md # Auto-captured signals
│ ├── IMPACT.md # Decision impact graph
│ ├── BRIEFINGS.md # Weekly briefings
│ ├── AUDIT.md # Applied proposal audit trail
│ ├── SCAN_LOG.md # Scan history
│ ├── proposed/ # Staged proposals + resolution proposals
│ │ ├── DECISIONS_PROPOSED.md
│ │ ├── TASKS_PROPOSED.md
│ │ ├── EDITS_PROPOSED.md
│ │ └── RESOLUTIONS_PROPOSED.md
│ ├── applied/ # Snapshot archives (rollback)
│ └── state/snapshots/ # State snapshots
│
├── shared/ # Multi-agent shared namespace
│ ├── decisions/
│ ├── tasks/
│ ├── entities/
│ └── intelligence/
│ └── LEDGER.md # Cross-agent fact ledger
│
├── agents/ # Per-agent private namespaces
│ └── <agent-id>/
│ ├── decisions/
│ ├── tasks/
│ └── memory/
│
├── mind-mem-acl.json # Multi-agent access control
├── .mind-mem-wal/ # Write-ahead log (crash recovery)
│
└── src/mind_mem/
├── mind_ffi.py # MIND FFI bridge (ctypes)
├── hybrid_recall.py # Hybrid BM25+Vector+RRF orchestrator
├── block_metadata.py # A-MEM metadata evolution
├── cross_encoder_reranker.py # Optional cross-encoder
├── intent_router.py # 9-type intent classification (adaptive)
├── recall.py # BM25F + RM3 + graph scoring engine
├── recall_vector.py # Vector/embedding backends
├── sqlite_index.py # FTS5 + vector + metadata index
├── connection_manager.py # SQLite connection pool (WAL read/write separation)
├── block_store.py # BlockStore protocol + MarkdownBlockStore
├── corpus_registry.py # Central corpus path registry
├── abstention_classifier.py # Adversarial abstention
├── evidence_packer.py # Evidence assembly and ranking
├── intel_scan.py # Integrity scanner
├── apply_engine.py # Proposal apply engine (delta-based snapshots)
├── block_parser.py # Markdown block parser (typed)
├── capture.py # Auto-capture (27 patterns)
├── compaction.py # Compaction/GC/archival
├── mind_filelock.py # Cross-platform advisory file locking
├── observability.py # Structured JSON logging + metrics
├── namespaces.py # Multi-agent namespace & ACL
├── conflict_resolver.py # Automated conflict resolution
├── backup_restore.py # WAL + backup/restore + JSONL export
├── transcript_capture.py # Transcript JSONL signal extraction
├── validate.sh # Structural validator (shell)
└── validate_py.py # Structural validator (Python, cross-platform)
How It Compares
Quick Comparison
a Mem0, Local-only: OSS can run locally; defaults to a cloud LLMb Letta, Local-only: heavy runtimec Zep/Graphiti, Local-only: graph DB + LLMd Engram, Local-only: cloud optionale Basic Memory, Local-only: cloud optionalf Mem0, Zero infrastructure: library mode; needs LLM + embedderg Engram, Zero infrastructure: single Go binaryh Mem0, Hybrid retrieval: no RRFi Letta, Hybrid retrieval: BM25 + RRF only with Turbopufferj Mem0, Contradiction detection: Dreamk Zep/Graphiti, Contradiction detection: LLM-basedl MIND-Mem, MCP tools: mcp.tool registrations; recall dispatcher shadows base recallm Mem0, MCP tools: Platformn Engram, Core dependencies: single binary
¹ Canonical MIND-Mem LoCoMo number — see
docs/benchmarks.md
for scope/evidence. On this apples-to-apples metric MIND-Mem is not the top
score of every system evaluated (see the Competitive Landscape table above);
its differentiator is being the only local-only, zero-dependency, governed
option.
² Mem0's own published LoCoMo-paper number. Mem0's separate 2026 managed platform self-reports 91.6 on a different setup/judge — not apples-to-apples with this row.
³ OpenViking self-reports 80.3–82.9% on a narrower scope (1,540 questions, no adversarial category) with a more lenient judge; see note ³ under the Competitive Landscape table.
At a Glance
Full Feature Matrix
Compared against every major memory solution for AI agents, checked against each project's public source or official docs in October 2026. Column codes and cell symbols are the same as in the Feature Completeness Matrix.
Recall
1 Basic Memory, Vector: FastEmbed2 ClawMem, Graph: Beam + MPFP3 Mem0, Hybrid + RRF: no RRF4 Basic Memory, Hybrid + RRF: score fusion5 MIND-Mem, Cross-encoder: MiniLM 80MB6 Graphlit, Cross-encoder: Reranker7 ClawMem, Cross-encoder: qwen3 0.6B8 MIND-Mem, Query expansion: RM3 (zero-dep)9 Supermemory, Query expansion: LLM rewrite10 ClawMem, Query expansion: QMD 1.7B
Persistence
1 MemU, Structured: SQL + Markdown2 Basic Memory, Structured: Markdown3 OpenViking, Structured: Markdown + vector index
Integrity
1 Engram, Contradictions: Agent-judged2 Engram, Drift detection: Staleness3 Basic Memory, Drift detection: Schema drift4 Engram, Conflict res.: Agent-judged5 Basic Memory, WAL/crash: Index only
Governance
1 Engram, Auto-capture: Agent + passive2 Basic Memory, Auto-capture: Plugin hooks
Operations
1 ClawMem, GPU required: optional2 18 config + 8 source
The Gap MIND-Mem Fills
Most tools above focus on **storage + retrieva