mind-mem

---

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

• Why MIND-Mem
• Features
• Integrations are the substrate working
• Benchmark Results
• Quick Start
• Health Summary
• Commands
• Architecture
• How It Compares
• Recall
• MIND Kernels
• Auto-Capture
• Multi-Agent Memory
• Governance Modes
• Block Format
• Configuration
• MCP Server
• Security
• Troubleshooting
• Built in MIND lang
• Contributing
• License

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=