MIND-Mem is a deterministic AI memory system: on the same workspace, the same query produces the same ranked results every time, with a Q16.16 fixed-point audit chain — byte-identical across runs, machines, and substrates — embedded in every applied decision. (Recall scoring itself is standard floating-point; the byte-identity guarantee is the Q16.16 audit/replay chain.)

Built on the MIND substrate. Governed-write (propose → review → approve_apply). 83 MCP tools as the surface — but the differentiator is the substrate underneath. On the same workspace, recall is deterministic (same query → same ranked results) and every block and audit hash is byte-identical across every architecture mind-mem builds on — the Q16.16 audit chain. (The ranking scores themselves are standard floating-point; the byte-identity guarantee is the audit/replay chain.)

Most memory layers ship tools. That is table-stakes. MIND-Mem ships a substrate: scoring kernels compiled from MIND source with 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 same query on the same workspace produces the same ranked recall, every time; that recall's audit/replay chain is byte-identical whether you replay it on the same machine or a different one that pulls the same workspace. 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: v4.2.2 — fix a Postgres connection-pool thread leak in the MCP server — Full per-release notes (issues closed, CI run ids, job counts) live in CHANGELOG.md.

Substrate Properties

Property What it means
Byte-identical replay Deterministic recall: same workspace + query → same ranked results, every time. The audit/replay chain (Q16.16) is byte-identical across machines. No probabilistic mutations in the core.
Governed-write Nothing reaches the source of truth without propose → review → approve_apply. No silent mutations. Ever.
Auditable Every apply logged with timestamp, receipt, and DIFF. Full traceability from signal to decision.
Deterministic No ML in the retrieval core. Q16.16 fixed-point encoding in the audit-hash preimage. The same preimage produces the same hash.
Local-first All data stays on disk. No cloud calls, no telemetry, no phoning home.
No vendor lock-in Plain Markdown files. Move to any system, any time.
Zero infrastructure Core requires only Python 3.10+ stdlib. Postgres, Redis, Docker, and GPU are opt-in extras.
100% NIAH 250/250 Needle In A Haystack retrieval. Every needle, every depth, every size.

Table of Contents

Deep-dive docs

  • docs/setup.md — install, configure, wire MCP, opt in to MIND native kernels
  • docs/usage.md — every surface (MCP tools by category, mm CLI, mind-mem-verify, Python library) with worked examples
  • docs/client-integrations.md — 18 AI client integrations (Claude Code, Codex, Grok Build, Vibe, Gemini, Cursor, Windsurf, aider, OpenClaw, NanoClaw, NemoClaw, Continue, Cline, Roo, Zed, Copilot, Cody, Qodo) with mm install-all auto-detection
  • docs/mind-mem-4b-setup.md — download + run the star-ga/mind-mem-4b full-FT model locally (transformers, exllamav2, vLLM, llama.cpp, Ollama, MindLLM)
  • docs/companion-tools.md — companion tools that complement (not compete with) mind-mem: MindLLM for deterministic + evidence-chained inference, GitNexus for code knowledge-graph
  • ROADMAP.md — feature roadmap (genuinely-open items at the top; bulk of v3.2.0→v4.0.0 shipped)
  • CHANGELOG.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.

Problem Without MIND-Mem With MIND-Mem
Contradicting decisions Follows whichever seen last Flags, links both, proposes fix
Informal chat decision Lost after session ends Auto-captured, proposed to formalize
Stale decision Zombie confuses future sessions Detected as dead, flagged
Orphan task reference Silent breakage Caught in integrity scan
Scattered recall quality Single-mode search misses context Hybrid BM25+Vector+RRF fusion finds it
Ambiguous query intent One-size-fits-all retrieval 9-type intent router optimizes parameters

Novel Contributions

MIND-Mem introduces several techniques not found in existing memory systems:

Technique What's new Why it matters
Co-retrieval graph PageRank-like score propagation across blocks frequently retrieved together Surfaces structurally relevant blocks with zero lexical overlap (+2.0pp accuracy)
Fact card sub-block indexing Atomic fact extraction → small-to-big retrieval with parent score blending Catches fine-grained facts that full-block BM25 misses (+2.6pp accuracy)
Adaptive knee cutoff Score-drop-based truncation instead of fixed top-K Eliminates noise that hurts LLM judges — returns 3-15 results adaptively
Hard negative mining Logs BM25-high / cross-encoder-low blocks as misleading, penalizes in future queries Self-improving retrieval: precision increases over time without retraining
Deterministic abstention Pre-LLM confidence gate using 5-signal scoring (entity, BM25, speaker, evidence, negation) Prevents hallucinated answers to unanswerable questions — no ML required
Governance pipeline Contradiction detection + drift analysis + safe apply with audit trail Only memory system that detects when stored knowledge is wrong
Agent-agnostic shared memory Single MCP workspace shared across Claude Code, Codex, Gemini, Cursor, Windsurf, Zed Memory compounds across tools instead of fragmenting

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 Kernels (Optional, Native Speed — forward-looking)

26 .mind configuration files at mind/ that tune the scoring pipeline (BM25F, RRF fusion, reranking, negation penalty, date proximity, category boost, importance, entity overlap, confidence, top-k, weighted rank, category affinity, query-category relevance, category assignment, and others). Currently INI-format declarative configuration parsed by mind_ffi.py; the MIND-language port that compiles to native .so via the MIND compiler is the forward-looking story — see docs/MIND_CONFIG_VS_MIND_LANG.md for the disambiguation. The pure-Python scoring logic in src/mind_mem/mind_kernels.py is the authoritative implementation today.

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. 74+ structural validation rules.

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 (26 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 (83 tools, 8 resources)

Full Model Context Protocol server with 83 distinct tools and 8 read-only resources (6 static + 2 templated). The server makes 84 mcp.tool(...) registrations, but the consolidated recall dispatcher intentionally shadows the base recall, so the live surface is 83 distinct tool names. 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).

74+ Structural Checks + 3024 Unit Tests

validate.sh checks schemas, cross-references, ID formats, status values, supersede chains, ConstraintSignatures, and more. Backed by 3024 pytest unit tests covering all core modules.

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.

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

Capability MIND-Mem Mem0 Zep Letta LangMem
BM25 lexical search Y — — — —
Vector semantic search Y Y Y Y Y
Hybrid BM25+Vector+RRF Y — — — —
Cross-encoder reranking Y — — — —
Intent-aware routing (9 types) Y — — — —
RM3 query expansion Y — — — —
Co-retrieval graph (PageRank) Y — — — —
Fact sub-block indexing Y — — — —
Hard negative mining Y — — — —
Adaptive knee cutoff Y — — — —
Contradiction detection Y — — — —
Drift analysis Y — — — —
Governance pipeline (propose/apply) Y — — — —
Multi-agent shared memory (MCP) Y — — Y —
Zero core dependencies Y — — — —
Local-only (no cloud required) Y — — — —
Compiled native kernels (MIND) Y — — — —
Backup/restore with zip-slip protection Y — — — —
Multi-query expansion with RRF Y — — — —
4-layer search deduplication Y — — — —
Semantic-aware smart chunking Y — — — —
Compiled truth pages (per-entity) Y — — — —
Dream cycle (autonomous enrichment) Y — — — —

Integrations are the substrate working

Because the substrate is deterministic, integrating with 17 different CLIs produces the same answers on each. That is not a coincidence — it is the point. MIND-Mem can be the canonical memory layer across heterogeneous agent stacks precisely because recall is deterministic and its audit/replay chain is byte-identical regardless of which client is asking. The 17-CLI surface is a consequence of the substrate, not a feature in itself.

Honest positioning: the integrations below are software-level — the named tool talks to MIND-Mem via the Model Context Protocol. They are not commercial-customer relationships with any vendor. Full positioning policy: docs/integrations.md.

Native MCP integration with 17 AI development tools

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.

Client Vendor Client Vendor
Claude Code Anthropic Cline Cline.bot
Claude Desktop Anthropic Roo Roo Code
Codex CLI OpenAI GitHub Copilot GitHub / Microsoft
Grok Build CLI xAI Cody Sourcegraph
Gemini CLI Google
Vibe (Mistral CLI) Mistral Qodo Qodo
Cursor Anysphere aider aider-chat
Windsurf Codeium OpenClaw OpenAI (Peter Steinberger)
Zed Zed Industries NemoClaw / Nemo NVIDIA
Continue Continue.dev NanoClaw Anthropic

Compatible with major LLM providers

MIND-Mem's recall pipeline is provider-agnostic. Tested against Anthropic Claude (3.5 Sonnet, 4.x), OpenAI GPT (4o, 5.4), Google Gemini (2.0 Flash, 3.1 Pro), Mistral Large, and local endpoints (Ollama, vLLM, llama.cpp). Compatibility is at the API contract level — the same MIND-Mem server returns the same answers regardless of which LLM is asking.

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.

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.

Haystack Size Depths Tested Needles Passed Rate
10 blocks 0/25/50/75/100% 10 50/50 100%
50 blocks 0/25/50/75/100% 10 50/50 100%
100 blocks 0/25/50/75/100% 10 50/50 100%
250 blocks 0/25/50/75/100% 10 50/50 100%
500 blocks 0/25/50/75/100% 10 50/50 100%

Config: Hybrid BM25 + BAAI/bge-large-en-v1.5 + 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.

v1.0.7 — Hybrid + top_k=18 (external LLM answerer + judge, conv-0, 199 questions):

Category N Acc (>=50) Mean Score
Overall 199 92.5% 76.7
Adversarial 47 97.9% 89.8
Multi-hop 37 91.9% 74.3
Open-domain 70 92.9% 72.7
Temporal 13 92.3% 76.2
Single-hop 32 84.4% 68.9

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 (external LLM answerer + judge, 10 conversations, 1986 questions):

Category N Acc (>=50) Mean Score
Overall 1986 73.8% 70.5
Adversarial 446 92.4% 87.2
Single-hop 282 80.9% 68.7
Open-domain 841 71.2% 70.3
Temporal 96 66.7% 65.9
Multi-hop 321 50.5% 51.1

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):

Category N Acc (>=50) Mean Score
Overall 1986 67.3% 61.4
Open-domain 841 86.6% 78.3
Temporal 96 78.1% 65.7
Single-hop 282 68.8% 59.1
Multi-hop 321 55.5% 48.4
Adversarial 446 36.3% 39.5

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

System Score Approach
MIND-Mem 76.7% Hybrid BM25 + Qwen3-8B vector + RRF fusion (local-only)
Memobase 75.8% Specialized extraction
Letta 74.0% Files + agent tool use
MIND-Mem 73.8% BM25-only, full 10-conv (1986 questions, external LLM judge)
Mem0 68.5% Graph + LLM extraction

MIND-Mem now surpasses Mem0 and Letta with local-only retrieval — no cloud calls, no graph DB, no LLM in the retrieval loop. MIND-Mem's unique value is governance (contradiction detection, drift analysis, audit trails) and agent-agnostic shared memory via MCP — areas these benchmarks don't measure.

Competitive Landscape (LoCoMo)

System LoCoMo Acc>=50 Infrastructure Dependencies
MIND-Mem (hybrid) 76.7% Local-only Zero core (optional: llama.cpp, sentence-transformers)
Memobase 75.8% Cloud + GPU embeddings + vector DB
Letta 74.0% Cloud embeddings + vector DB
MIND-Mem (BM25) 73.8% Local-only Zero core
full-context 72.9% N/A LLM context window
Mem0 68.5% Cloud (managed) graph DB + embeddings

MIND-Mem surpasses Mem0 (68.5%), Letta (74.0%), and Memobase (75.8%) with zero cloud infrastructure. Full 10-conversation benchmark (1986 questions) validates this at scale. Note: benchmarks measure retrieval accuracy. The substrate properties (byte-identical replay, governed-write, audit chain) are not captured by any of these benchmarks — they are properties of the architecture, not the recall scores.

LongMemEval (held pending reconciliation)

Provenance hold active. The LongMemEval R@5 numbers below are pending reconciliation against a higher-iteration run. They are not part of the MIND-Mem positioning until the hold is resolved. See benchmarks/STATUS.md for the current status and methodology.

Category N R@1 R@5 R@10 MRR
Overall 470 73.2 (held) 88.1 .784
Multi-session 121 83.5 (held) 95.9 .885
Temporal 127 76.4 (held) 92.9 .826
Knowledge update 72 80.6 (held) 91.7 .844
Single-session 56 82.1 (held) 89.3 .847

Performance (Latency & Throughput)

Measured on a 65-block workspace (typical personal workspace) with SQLite FTS5 backend:

Operation Metric Value
Query (FTS5 + rerank) p50 latency 2.1 ms
Query (FTS5 + rerank) p95 latency 4.9 ms
Query (FTS5 + rerank) mean latency 2.6 ms
Incremental reindex elapsed 32 ms (13 blocks indexed)
Full index build elapsed 48 ms (65 blocks)
MCP tool overhead stdio round-trip < 15 ms
Memory footprint RSS (idle MCP server) ~28 MB

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).

Run Benchmarks Yourself

# Retrieval-only (R@K metrics)

## Install in 3 commands

```bash
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

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 --output results.json

Hybrid retrieval with any model pair (BM25 + vector + cross-encoder)

python3 benchmarks/locomo_judge.py --hybrid --compress --answerer-model --judge-model --output results.json

Selective conversations

python3 benchmarks/locomo_harness.py --conv-ids 4,7,8


---

## Quick Start

### One-line install (recommended)

```bash
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

This auto-detects every AI coding client on your machine and configures MIND-Mem for all of them. Each client launches the same mind-mem-mcp binary, so all agents share one workspace. Supported clients:

Client Config Location Format
Claude Code CLI ~/.claude/mcp.json JSON
Claude Desktop ~/.config/Claude/claude_desktop_config.json JSON
Codex CLI (OpenAI) ~/.codex/config.toml TOML
Gemini CLI (Google) ~/.gemini/settings.json JSON
Cursor ~/.cursor/mcp.json JSON
Windsurf ~/.codeium/windsurf/mcp_config.json JSON
Zed ~/.config/zed/settings.json JSON
OpenClaw ~/.openclaw/hooks/mind-mem/ JS hook

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

python3 .mind-mem/src/mind_mem/init_workspace.py .

Creates 12 directories, 19 template files, and mind-mem.json config. Never overwrites existing files.

3. Validate

bash .mind-mem/src/mind_mem/validate.sh .
# or cross-platform:
python3 .mind-mem/src/mind_mem/validate_py.py .

Expected: 74 checks | 74 passed | 0 issues.

4. First scan

python3 .mind-mem/src/mind_mem/intel_scan.py .

Expected: 0 critical | 0 warnings on a fresh workspace.

5. Verify recall + capture

python3 .mind-mem/src/mind_mem/recall.py --query "test" --workspace .
# → No results found. (empty workspace — correct)

python3 .mind-mem/src/mind_mem/capture.py .
# → 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