Persistent, auditable, contradiction-safe memory for coding agents. Hybrid BM25 + vector retrieval, 19 MCP tools, co-retrieval graph, MIND-accelerated scoring. Zero external dependencies.
Drop-in memory layer for AI coding agents — Claude Code, Claude Desktop, Codex CLI, Gemini CLI, Cursor, Windsurf, Zed, OpenClaw, or any MCP-compatible client. Upgrades your agent from "chat history + notes" to a governed Memory OS with hybrid search, RRF fusion, intent routing, optional MIND kernels, structured persistence, contradiction detection, drift analysis, safe governance, and full audit trail.
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.
This is the killer feature. When you install mind-mem, all your AI coding agents share the same memory workspace. Claude Code, Codex CLI, Gemini CLI, Cursor, Windsurf, Zed — every MCP-compatible client connects to the same persistent memory through a single workspace.
What this means in practice:
One install script, all agents configured in seconds:
git clone https://github.com/star-ga/mind-mem.git
cd mind-mem
./install.sh --all # Auto-detects and configures every AI coding client on your machineThe installer auto-detects Claude Code, Claude Desktop, Codex CLI, Gemini CLI, Cursor, Windsurf, Zed, and OpenClaw — creates a shared workspace and wires the MCP server into each client's config. SQLite WAL mode ensures safe concurrent access: one writer, many readers, zero corruption.
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 & contradictionsOutput:
[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| Principle | What it means |
|---|---|
| Deterministic | Same input, same output. No ML in the core, no probabilistic mutations. |
| Auditable | Every apply logged with timestamp, receipt, and DIFF. Full traceability. |
| 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 magic | Every check is a grep, every mutation is a file write. Read the source in 30 min. |
| No silent mutation | Nothing writes to source of truth without explicit /apply. Ever. |
| Zero infrastructure | No Redis, no Postgres, no vector DB, no GPU. Python 3.10+ and stdlib only. |
| 100% NIAH | 250/250 Needle In A Haystack retrieval. Every needle, every depth, every size. |
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 |
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 |
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.
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.
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).
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.
Four-signal reranking pipeline: negation awareness (penalizes contradicting results), date proximity (Gaussian decay), 20-category taxonomy matching, and recency boosting. No ML required.
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.
17 compiled MIND scoring kernels (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). Compiles to native .so via the MIND compiler. Pure Python fallback always available — no functionality is lost without compilation.
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.
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.
Pluggable embedding backend — local ONNX (all-MiniLM-L6-v2, no server needed) or cloud (Pinecone). Falls back to BM25 when unavailable.
Structured, validated, append-only decisions / tasks / entities / incidents with provenance and supersede chains. Plain Markdown files — readable by humans, parseable by machines.
Continuous integrity checking: contradictions, drift, dead decisions, orphan tasks, coverage scoring, regression detection. 74+ structural validation rules.
All changes flow through graduated modes: detect_only → propose → enforce. Apply engine with snapshot, receipt, DIFF, and automatic rollback on validation failure.
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.
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.
Cross-platform advisory file locking (fcntl/msvcrt/atomic create) protects all concurrent write paths. Stale lock detection with PID-based cleanup. Zero dependencies.
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.
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.
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.
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.
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.
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.
Full Model Context Protocol server with 32 tools and 8 read-only resources. Works with Claude Code, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client. HTTP and stdio transports with optional bearer token auth.
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.
Every applied proposal logged with timestamp, receipt, and DIFF. Full traceability from signal → proposal → decision.
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.
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.
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.
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.
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.
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.
| 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 | — | — | — | — |
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.
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
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 (Mistral 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 (Mistral Large 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 Mistral Large as both answerer and judge.
v1.0.0 — BM25-only baseline (gpt-4o-mini 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).
| 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, Mistral Large) |
| 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.
| System | LoCoMo Acc>=50 | LongMemEval R@10 | Infrastructure | Dependencies |
|---|---|---|---|---|
| mind-mem (hybrid) | 76.7% | 88.1% | 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% | 88.1% | 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.
| Category | N | R@1 | R@5 | R@10 | MRR |
|---|---|---|---|---|---|
| Overall | 470 | 73.2 | 85.3 | 88.1 | .784 |
| Multi-session | 121 | 83.5 | 95.9 | 95.9 | .885 |
| Temporal | 127 | 76.4 | 91.3 | 92.9 | .826 |
| Knowledge update | 72 | 80.6 | 88.9 | 91.7 | .844 |
| Single-session | 56 | 82.1 | 89.3 | 89.3 | .847 |
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).
# 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 gpt-4o-mini --output results.json
# Hybrid retrieval with any model pair (BM25 + vector + cross-encoder)
python3 benchmarks/locomo_judge.py --hybrid --compress --answerer-model mistral-large-latest --judge-model mistral-large-latest --output results.json
# Selective conversations
python3 benchmarks/locomo_harness.py --conv-ids 4,7,8pip install mind-mem
mind-mem-recall "What decisions were made about the API?"git clone https://github.com/star-ga/mind-mem.git
cd mind-mem
./install.sh --allThis auto-detects every AI coding client on your machine and configures mind-mem for all of them. 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 pathUninstall:
./uninstall.sh # Remove from all clients (keeps workspace data)
./uninstall.sh --purge # Remove everything including workspace dataFor 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-mem2. 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-mem7. Smoke Test (optional)
bash .mind-mem/src/mind_mem/smoke_test.shCreates a temp workspace, runs init → validate → scan → recall → capture → pytest, then cleans up.
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| Command | What it does |
|---|---|
/scan | Run integrity scan — contradictions, drift, dead decisions, impact graph, snapshot, briefing |
/apply | Review and apply proposals from scan results (dry-run first, then apply) |
/recall <query> | Search across all memory files with ranked results (add --graph for cross-reference boosting) |
your-workspace/
├── mcp_server.py # MCP server (FastMCP, 44 tools, 8 resources)
├── mind-mem.json # Config
├── MEMORY.md # Protocol rules
│
├── mind/ # 17 MIND source files (.mind)
│ ├── bm25.mind # BM25F scoring kernel
│ ├── rrf.mind # Reciprocal Rank Fusion kernel
│ ├── reranker.mind # Deterministic reranking
│ ├── abstention.mind # Confidence gating
│ ├── ranking.mind # Evidence ranking
│ ├── importance.mind # A-MEM importance scoring
│ ├── category.mind # Category relevance scoring
│ ├── recall.mind # Combined recall scoring
│ ├── hybrid.mind # BM25 + vector hybrid fusion
│ ├── rm3.mind # RM3 pseudo-relevance feedback
│ ├── rerank.mind # Score combination pipeline
│ ├── adversarial.mind # Adversarial query detection
│ ├── temporal.mind # Time-aware scoring
│ ├── prefetch.mind # Context pre-assembly
│ ├── intent.mind # Intent classification
│ └── cross_encoder.mind # Cross-encoder blending
│
├── lib/ # Compiled MIND kernels (optional)
│ └── libmindmem.so # mindc output — not required for operation
│
├── 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 (26 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 (74+ checks)
└── validate_py.py # Structural validator (Python, cross-platform)| Feature | mind-mem | Mem0 | Letta | Zep/Graphiti |
|---|---|---|---|---|
| Local-only | Yes | No (cloud API) | No (runtime) | No (Neo4j) |
| Zero infrastructure | Yes | No | No | No |
| Hybrid retrieval | BM25F + vector + RRF | Vector only | Hybrid | Graph + vector |
| Governance (propose/review/apply) | Yes | No | No | No |
| Contradiction detection | Yes | No | No | No |
| Tests | 3,193 | - | - | - |
| LoCoMo benchmark | 67.3% | 68.5% | 74.0% | - |
| MCP tools | 33 | - | - | - |
| Core dependencies | 0 | Many | Many | Many |
| Tool | Strength | Trade-off |
|---|---|---|
| Mem0 | Fast managed service, graph memory, multi-user scoping | Cloud-dependent, no integrity checking |
| Supermemory | Fastest retrieval (ms), auto-ingestion from Drive/Notion | Cloud-dependent, auto-writes without review |
| claude-mem | Purpose-built for Claude Code, ChromaDB vectors | Requires ChromaDB + Express worker, no integrity |
| Letta | Self-editing memory blocks, sleep-time compute, 74% LoCoMo | Full agent runtime (heavy), not just memory |
| Zep | Temporal knowledge graph, bi-temporal model, sub-second at scale | Cloud service, complex architecture |
| LangMem | Native LangChain/LangGraph integration | Tied to LangChain ecosystem |
| Cognee | Advanced chunking, web content bridging | Research-oriented, complex setup |
| Graphlit | Multimodal ingestion, semantic search, managed platform | Cloud-only, managed service |
| ClawMem | Full ML pipeline (cross-encoder + QMD + beam search) | 4.5GB VRAM, 3 GPU processes required |
| MemU | Hierarchical 3-layer memory, multimodal ingestion, LLM-based retrieval | Requires LLM for extraction and retrieval, no hybrid search |
| mind-mem | Integrity + governance + zero core deps + hybrid search + MIND kernels + 44 MCP tools + 3-LLM audit per release | Lexical recall by default (vector/CE optional) |
Compared against every major memory solution for AI agents (as of 2026):
| Mem0 | Supermemory | claude-mem | Letta | Zep | LangMem | Cognee | Graphlit | ClawMem | MemU | mind-mem | |
|---|---|---|---|---|---|---|---|---|---|---|---|
| Recall | |||||||||||
| Vector | Cloud | Cloud | Chroma | Yes | Yes | Yes | Yes | Yes | Yes | — | Optional |
| Lexical | Filter | — | — | — | — | — | — | — | BM25 | — | BM25F |
| Graph | Yes | — | — | — | Yes | — | Yes | Yes | Beam | — | 2-hop |
| Hybrid + RRF | Part | — | — | — | Yes | — | Yes | Yes | Yes | — | Yes |
| Cross-encoder | — | — | — | — | — | — | — | — | qwen3 0.6B | — | MiniLM 80MB |
| Intent routing | — | — | — | — | — | — | — | — | Yes | — | 9 types |
| Query expansion | — | — | — | — | — | — | — | — | QMD 1.7B | — | RM3 (zero-dep) |
| Persistence | |||||||||||
| Structured | JSON | JSON | SQL | Blk | Grph | KV | Grph | Grph | SQL | Markdown | Markdown |
| Entities | Yes | Yes | — | Yes | Yes | Yes | Yes | Yes | — | Yes | Yes |
| Temporal | — | — | — | — | Yes | — | — | — | — | — | Yes |
| Supersede | — | — | — | Yes | Yes | — | — | — | — | — | Yes |
| Append-only | — | — | — | — | — | — | — | — | — | — | Yes |
| A-MEM metadata | — | — | — | — | — | — | — | — | Yes | — | Yes |
| Integrity | |||||||||||
| Contradictions | — | — | — | — | — | — | — | — | — | — | Yes |
| Drift detection | — | — | — | — | — | — | — | — | — | — | Yes |
| Validation | — | — | — | — | — | — | — | — | — | — | 74+ rules |
| Impact graph | — | — | — | — | — | — | — | — | — | — | Yes |
| Coverage | — | — | — | — | — | — | — | — | — | — | Yes |
| Multi-agent | — | — | — | Yes | — | — | — | — | — | — | ACL-based |
| Conflict res. | — | — | — | — | — | — | — | — | — | — | Automatic |
| WAL/crash | — | — | — | — | — | — | — | — | — | — | Yes |
| Backup/restore | — | — | — | — | — | — | — | — | — | — | Yes |
| Abstention | — | — | — | — | — | — | — | — | — | — | Yes |
| Governance | |||||||||||
| Auto-capture | Auto | Auto | Auto | Self | Ext | Ext | Ext | Ing | Auto | LLM Ext | Propose |
| Proposal queue | — | — | — | — | — | — | — | — | — | — | Yes |
| Rollback | — | — | — | — | — | — | — | — | — | — | Yes |
| Mode governance | — | — | — | — | — | — | — | — | — | — | 3 modes |
| Audit trail | — | Part | — | — | — | — | — | — | — | — | Full |
| Operations | |||||||||||
| Local-only | — | — | Yes | — | — | — | — | — | Yes | Yes | Yes |
| Zero core deps | — | — | — | — | — | — | — | — | — | — | Yes |
| No daemon | — | — | — | — | — | Yes | — | — | — | Yes | Yes |
| GPU required | — | — | — | — | — | — | — | — | 4.5GB | No | No |
| Git-friendly | — | — | — | Part | — | — | — | — | — | Yes | Yes |
| MCP server | — | — | — | — | — | — | — | — | — | — | 44 tools |
| MIND kernels | — | — | — | — | — | — | — | — | — | — | 16 source |
Every tool above does storage + retrieval. None of them answer:
mind-mem focuses on memory governance and integrity — the critical layer most memory systems ignore entirely.
Letta's August 2025 analysis showed that a plain-file baseline (full conversations stored as files + agent filesystem tools) scored 74.0% on LoCoMo with gpt-4o-mini — beating Mem0's top graph variant at 68.5%. Key reasons:
mind-mem's deterministic retrieval pipeline validates these findings: 67.3% on LoCoMo with zero dependencies, no embeddings, and no vector database — within 1.2pp of Mem0's graph-based approach. The key insight: treating retrieval as a reasoning pipeline (wide candidate pool → deterministic rerank → context packing) closes most of the gap without any ML infrastructure. Unlike plain-file baselines, mind-mem adds integrity checking, governance, and agent-agnostic shared memory via MCP that no other system provides.
python3 -m mind_mem.recall --query "authentication" --workspace .
python3 -m mind_mem.recall --query "auth" --json --limit 5 --workspace .
python3 -m mind_mem.recall --query "deadline" --active-only --workspace .BM25F scoring (k1=1.2, b=0.75) with per-field weighting, bigram phrase matching, overlapping sentence chunking, and query-type-aware parameter tuning. Searches across all structured files.
BM25F field weighting: Terms in Statement fields score 3x higher than terms in Context (0.5x). This naturally prioritizes core content over auxiliary metadata.
RM3 query expansion: Pseudo-relevance feedback from top-k initial results. JM-smoothed language model extracts expansion terms, interpolated with the original query at configurable alpha. Falls back to static synonyms for adversarial queries.
Adversarial abstention: Deterministic pre-LLM confidence gate. Computes confidence from entity overlap, BM25 score, speaker coverage, evidence density, and negation asymmetry. Below threshold → forces abstention.
Stemming: "queries" matches "query", "deployed" matches "deployment". Simplified Porter stemmer with zero dependencies.
{
"recall": {
"backend": "hybrid",
"vector_enabled": true,
"rrf_k": 60,
"bm25_weight": 1.0,
"vector_weight": 1.0
}
}Thread-parallel BM25 and vector retrieval fused via RRF: score(doc) = bm25_w / (k + bm25_rank) + vec_w / (k + vec_rank). Deduplicates by block ID. Falls back to BM25-only when vector backend is unavailable.
python3 -m mind_mem.recall --query "database" --graph --workspace .2-hop graph traversal: 1-hop neighbors get 0.3x score boost, 2-hop get 0.1x (tagged [graph]). Surfaces structurally connected blocks via AlignsWith, Dependencies, Supersedes, Sources, and ConstraintSignature scopes. Auto-enabled for multi-hop queries.
{
"recall": {
"backend": "vector",
"vector_enabled": true,
"vector_model": "all-MiniLM-L6-v2",
"onnx_backend": true
}
}Supports ONNX inference (local, no server) or cloud embeddings. Falls back to BM25 automatically if unavailable.
mind-mem includes 17 .mind kernel source files — numerical hot paths written in the MIND programming language. The MIND kernel is optional. mind-mem works identically without it (pure Python fallback). With it, scoring runs at native speed with compile-time tensor shape verification.
Requires the MIND compiler (mindc). See mindlang.dev for installation.
# Compile all kernels to a single shared library
mindc mind/*.mind --emit=shared -o lib/libmindmem.so
# Or compile individually for testing
mindc mind/bm25.mind --emit=shared -o lib/libbm25.so| File | Functions | Purpose |
|---|---|---|
bm25.mind | bm25f_doc, bm25f_batch, apply_recency, apply_graph_boost | BM25F scoring with field boosts |
rrf.mind | rrf_fuse, rrf_fuse_three | Reciprocal Rank Fusion |
reranker.mind | date_proximity_score, category_boost, negation_penalty, rerank_deterministic | Deterministic reranking |
rerank.mind | rerank_scores | Score combination pipeline |
abstention.mind | entity_overlap, confidence_score | Confidence gating |
ranking.mind | weighted_rank, top_k_mask | Evidence ranking |
importance.mind | importance_score | A-MEM importance scoring |
category.mind | category_affinity, query_category_relevance, category_assign | Category distillation scoring |
prefetch.mind | prefetch_score, prefetch_select | Signal-based context pre-assembly |
recall.mind | recall_score | Combined recall scoring |
hybrid.mind | hybrid_fuse | BM25 + vector hybrid fusion |
rm3.mind | rm3_weight | RM3 pseudo-relevance feedback |
adversarial.mind | adversarial_gate | Adversarial query detection |
temporal.mind | temporal_decay | Time-aware scoring |
intent.mind | intent_params | Intent classification parameters |
cross_encoder.mind | ce_blend | Cross-encoder blending configuration |
| Function | N=100 | N=1,000 | N=5,000 |
|---|---|---|---|
rrf_fuse | 10.8x | 69.0x | 72.5x |
bm25f_batch | 13.2x | 113.8x | 193.1x |
negation_penalty | 3.3x | 7.0x | 18.4x |
date_proximity | 10.7x | 15.3x | 26.9x |
category_boost | 3.3x | 19.8x | 17.7x |
importance_batch | 22.3x | 46.2x | 48.6x |
confidence_score | 0.9x | 0.8x | 0.9x |
top_k_mask | 3.1x | 8.1x | 11.8x |
weighted_rank | 5.1x | 26.6x | 121.8x |
| Overall | 49.0x |
</details>49x faster end-to-end at production scale (N=5,000). Individual kernels reach up to 193x speedup. The compiled library includes 14 runtime protection layers with near-zero overhead.
The compiled .so exposes a C99-compatible ABI. Python calls via ctypes through src/mind_mem/mind_ffi.py:
from mind_ffi import get_kernel, is_available, is_protected
if is_available():
kernel = get_kernel()
scores = kernel.rrf_fuse_py(bm25_ranks, vec_ranks, k=60.0)
print(f"Protected: {is_protected()}") # True with FORTRESS buildIf lib/libmindmem.so is not present, mind-mem uses pure Python implementations. The Python fallback produces identical results (within f32 epsilon). No functionality is lost — MIND is a performance optimization, not a requirement.
Session end
↓
capture.py scans daily log (or --scan-all for batch)
↓
Detects decision/task language (26 patterns, 3 confidence levels)
↓
Extracts structured metadata (subject, object, tags)
↓
Classifies confidence (high/medium/low → P1/P2/P3)
↓
Writes to intelligence/SIGNALS.md ONLY
↓
User reviews signals
↓
/apply promotes to DECISIONS.md or TASKS.mdBatch scanning: python3 -m mind_mem.capture . --scan-all scans the last 7 days of daily logs.
Safety guarantee: capture.py never writes to decisions/ or tasks/ directly. All signals must go through the apply engine.
python3 -m mind_mem.namespaces workspace/ --init coder-1 reviewer-1Creates shared/ (visible to all) and agents/coder-1/, agents/reviewer-1/ (private) directories with ACL config.
{
"default_policy": "read",
"agents": {
"coder-1": {"namespaces": ["shared", "agents/coder-1"], "write": ["agents/coder-1"], "read": ["shared"]},
"reviewer-*": {"namespaces": ["shared"], "write": [], "read": ["shared"]},
"*": {"namespaces": ["shared"], "write": [], "read": ["shared"]}
}
}High-confidence facts proposed to shared/intelligence/LEDGER.md become visible to all agents after review. Append-only with dedup and file locking.
python3 -m mind_mem.conflict_resolver workspace/ --analyze
python3 -m mind_mem.conflict_resolver workspace/ --proposeGraduated resolution: confidence priority > scope specificity > timestamp priority > manual fallback.
python3 -m mind_mem.transcript_capture workspace/ --transcript path/to/session.jsonl
python3 -m mind_mem.transcript_capture workspace/ --scan-recent --days 3Scans Claude Code JSONL transcripts for user corrections, convention discoveries, and architectural decisions. 16 patterns with confidence classification.
python3 -m mind_mem.backup_restore backup workspace/ --output backup.tar.gz
python3 -m mind_mem.backup_restore export workspace/ --output export.jsonl
python3 -m mind_mem.backup_restore restore workspace/ --input backup.tar.gz
python3 -m mind_mem.backup_restore wal-replay workspace/| Mode | What it does | When to use |
|---|---|---|
detect_only | Scan + validate + report only | Start here. First week after install. |
propose | Report + generate fix proposals in proposed/ | After a clean observation week with zero critical issues. |
enforce | Bounded auto-supersede + self-healing within constraints | Production mode. Requires explicit opt-in. |
Recommended rollout:
detect_only for 7 daysproposeenforceAll structured data uses a simple, parseable markdown format:
[D-20260213-001]
Date: 2026-02-13
Status: active
Statement: Use PostgreSQL for the user database
Tags: database, infrastructure
Rationale: Better JSON support than MySQL for our use case
ConstraintSignatures:
- id: CS-db-engine
domain: infrastructure
subject: database
predicate: engine
object: postgresql
modality: must
priority: 9
scope: {projects: [PRJ-myapp]}
evidence: Benchmarked JSON performance
axis:
key: database.engine
relation: standalone
enforcement: structuralBlocks are parsed by block_parser.py — a zero-dependency markdown parser that extracts [ID] headers and Key: Value fields into structured dicts.
All settings in mind-mem.json (created by init_workspace.py):
{
"version": "2.0.0",
"workspace_path": ".",
"auto_capture": true,
"auto_recall": true,
"governance_mode": "detect_only",
"recall": {
"backend": "bm25",
"rrf_k": 60,
"bm25_weight": 1.0,
"vector_weight": 1.0,
"vector_model": "all-MiniLM-L6-v2",
"vector_enabled": false,
"onnx_backend": false
},
"proposal_budget": {
"per_run": 3,
"per_day": 6,
"backlog_limit": 30
},
"compaction": {
"archive_days": 90,
"snapshot_days": 30,
"log_days": 180,
"signal_days": 60
},
"scan_schedule": "daily"
}| Key | Default | Description |
|---|---|---|
version | "2.0.0" | Config file version |
auto_capture | true | Run capture engine on session end |
auto_recall | true | Show recall context on session start |
governance_mode | "detect_only" | Governance mode (detect_only, propose, enforce) |
recall.backend | "scan" | "scan" (BM25), "hybrid" (BM25+Vector+RRF), or "vector" |
recall.rrf_k | 60 | RRF fusion parameter k |
recall.bm25_weight | 1.0 | BM25 weight in RRF fusion |
recall.vector_weight | 1.0 | Vector weight in RRF fusion |
recall.vector_model | "all-MiniLM-L6-v2" | Embedding model for vector search |
recall.vector_enabled | false | Enable vector search backend |
recall.onnx_backend | false | Use ONNX for local embeddings (no server needed) |
proposal_budget.per_run | 3 | Max proposals generated per scan |
proposal_budget.per_day | 6 | Max proposals per day |
proposal_budget.backlog_limit | 30 | Max pending proposals before pausing |
compaction.archive_days | 90 | Archive completed blocks older than N days |
compaction.snapshot_days | 30 | Remove apply snapshots older than N days |
compaction.log_days | 180 | Archive daily logs older than N days |
compaction.signal_days | 60 | Remove resolved/rejected signals older than N days |
scan_schedule | "daily" | "daily" or "manual" |
mind-mem ships with a Model Context Protocol server that exposes memory as resources and tools to any MCP-compatible client.
pip install fastmcp./install.sh --allConfigures all detected clients automatically. See Quick Start.
For Claude Code, Claude Desktop, Cursor, Windsurf, and Gemini CLI, add to the respective JSON config under mcpServers:
{
"mcpServers": {
"mind-mem": {
"command": "python3",
"args": ["/path/to/mind-mem/mcp_server.py"],
"env": {"MIND_MEM_WORKSPACE": "/path/to/your/workspace"}
}
}
}| Client | Config File |
|---|---|
| Claude Code CLI | ~/.claude/mcp.json |
| Claude Desktop | ~/.config/Claude/claude_desktop_config.json |
| Gemini CLI | ~/.gemini/settings.json |
| Cursor | ~/.cursor/mcp.json |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
For Codex CLI (TOML format), add to ~/.codex/config.toml:
[mcp_servers.mind-mem]
command = "python3"
args = ["/path/to/mind-mem/mcp_server.py"]
[mcp_servers.mind-mem.env]
MIND_MEM_WORKSPACE = "/path/to/your/workspace"For Zed, add to ~/.config/zed/settings.json under context_servers:
{
"context_servers": {
"mind-mem": {
"command": {
"path": "python3",
"args": ["/path/to/mind-mem/mcp_server.py"],
"env": {"MIND_MEM_WORKSPACE": "/path/to/your/workspace"}
}
}
}
}# stdio transport (default)
MIND_MEM_WORKSPACE=/path/to/workspace python3 mcp_server.py
# HTTP transport (multi-client / remote)
MIND_MEM_WORKSPACE=/path/to/workspace python3 mcp_server.py --transport http --port 8765| URI | Description |
|---|---|
mind-mem://decisions | Active decisions |
mind-mem://tasks | All tasks |
mind-mem://entities/{type} | Entities (projects, people, tools, incidents) |
mind-mem://signals | Auto-captured signals pending review |
mind-mem://contradictions | Detected contradictions |
mind-mem://health | Workspace health summary |
mind-mem://recall/{query} | BM25 recall search results |
mind-mem://ledger | Shared fact ledger (multi-agent) |
| Tool | Description |
|---|---|
recall | Search memory with BM25 (query, limit, active_only) |
propose_update | Propose a decision/task — writes to SIGNALS.md only |
approve_apply | Apply a staged proposal (dry_run=True by default) |
rollback_proposal | Rollback an applied proposal by receipt timestamp |
scan | Run integrity scan (contradictions, drift, signals) |
list_contradictions | List contradictions with auto-resolution analysis |
hybrid_search | Hybrid BM25+Vector search with RRF fusion |
find_similar | Find blocks similar to a given block |
intent_classify | Classify query intent (9 types with parameter recommendations) |
index_stats | Index statistics, MIND kernel availability, block counts |
retrieval_diagnostics | Pipeline rejection rates, intent histogram, hard negatives |
reindex | Rebuild FTS5 index (optionally including vectors) |
memory_evolution | View/trigger A-MEM metadata evolution for a block |
list_mind_kernels | List available MIND kernel configurations |
get_mind_kernel | Read a specific MIND kernel configuration as JSON |
category_summary | Category summaries relevant to a given topic |
prefetch | Pre-assemble context from recent conversation signals |
delete_memory_item | Delete a memory block by ID (admin-scope) |
export_memory | Export workspace as JSONL (user-scope) |
calibration_feedback | Submit quality feedback for a retrieved block (thumbs up/down) |
calibration_stats | View per-block and global calibration statistics |
MIND_MEM_TOKEN=your-secret python3 mcp_server.py --transport http --port 8765propose_update never writes to DECISIONS.md or TASKS.md. All proposals go to SIGNALS.md.approve_apply defaults to dry_run=True. Creates a snapshot before applying for rollback.| What we protect | How |
|---|---|
| Memory integrity | 74+ structural checks, ConstraintSignature validation |
| Accidental overwrites | Proposal-based mutations only (never direct writes) |
| Rollback safety | Snapshot before every apply, atomic os.replace() |
| Symlink attacks | Symlink detection in restore paths |
| Path traversal | All paths resolved via os.path.realpath(), workspace-relative only |
| What we do NOT protect against | Why |
|---|---|
| Malicious local user | Single-user CLI tool — filesystem access = data access |
| Network attacks | No network calls, no listening ports, no telemetry |
| Encrypted storage | Files are plaintext Markdown — use disk encryption if needed |
mind-mem makes zero network calls from its core. No telemetry, no phoning home, no cloud dependencies. Optional features (vector embeddings, cross-encoder) may download models on first use.
| Package | Purpose | Install |
|---|---|---|
fastmcp | MCP server | pip install mind-mem[mcp] |
onnxruntime + tokenizers | Local vector embeddings | pip install mind-mem[embeddings] |
sentence-transformers | Cross-encoder reranking | pip install mind-mem[cross-encoder] |
ollama | LLM extraction (local) | pip install ollama |
For best LLM extraction quality, use Mind-Mem:7B — a purpose-trained model fine-tuned on mind-mem's 8 extraction tasks (entity extraction, fact extraction, observation compression, contradiction detection, governance analysis, intent classification, axis-aware retrieval, LLM reranking).
Ollama (recommended):
# Download the GGUF from HuggingFace
wget https://huggingface.co/star-ga/mind-mem-7b/resolve/main/mind-mem-7b-Q4_K_M.gguf
# Create Ollama model
cat > Modelfile << 'EOF'
FROM ./mind-mem-7b-Q4_K_M.gguf
SYSTEM "You are Mind7B, a specialized memory extraction model for mind-mem."
PARAMETER temperature 0.1
PARAMETER num_predict 512
EOF
ollama create mind-mem:7b -f ModelfileThen set in mind-mem.json:
{
"extraction": {
"enabled": true,
"model": "mind-mem:7b",
"backend": "ollama"
}
}LoRA adapter (transformers + PEFT):
from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftModel
base = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3.5-9B", device_map="auto")
model = PeftModel.from_pretrained(base, "star-ga/mind-mem-7b")
tokenizer = AutoTokenizer.from_pretrained("star-ga/mind-mem-7b")| Resource | Link |
|---|---|
| Model (LoRA + GGUF) | star-ga/mind-mem-7b |
| Training data | star-ga/mind7b-training |
| Base model | Qwen/Qwen3.5-9B |
| Training | QLoRA via Unsloth, 2600 examples, RTX 4090 |
| Platform | Status | Notes |
|---|---|---|
| Linux | Full | Primary target |
| macOS | Full | POSIX-compliant shell scripts |
| Windows (WSL/Git Bash) | Full | Use WSL2 or Git Bash for shell hooks |
| Windows (native) | Python only | Use validate_py.py; hooks require WSL |
| Problem | Solution |
|---|---|
validate.sh says "No mind-mem.json found" | Run in a workspace, not the repo root. Run init_workspace.py first. |
recall returns no results | Workspace is empty. Add decisions/tasks first. |
capture says "no daily log" | No memory/YYYY-MM-DD.md for today. Write something first. |
intel_scan finds 0 contradictions | Good — no conflicting decisions. |
| Tests fail on Windows | Use validate_py.py instead of validate.sh. Hooks require WSL. |
| MIND kernel not loading | Compile with mindc mind/*.mind --emit=shared -o lib/libmindmem.so. Or ignore — pure Python works identically. |
No results from recall?
Check that the workspace path is correct and points to an initialized workspace
containing decisions, tasks, or entities. If the FTS5 index is stale or missing,
run the reindex MCP tool to rebuild it.
MCP connection failed?
Verify that fastmcp is installed (pip install fastmcp). Check the transport
configuration in your client's MCP config (stdio vs HTTP). Ensure theMIND_MEM_WORKSPACE environment variable points to a valid workspace directory.
MIND kernels not loading?
Run bash src/mind_mem/build.sh to compile the MIND source files (requires mindc).
If the MIND compiler is not available, mind-mem automatically uses the pure Python
fallback with identical results.
Index corrupt?
Run the reindex MCP tool, or from the command line:python3 -m mind_mem.sqlite_index --rebuild --workspace /path/to/workspace.
This drops and recreates the FTS5 index from all workspace files.
For the formal grammar, invariant rules, state machine, and atomicity guarantees, see SPEC.md.
Contributions welcome. Please open an issue first to discuss what you'd like to change.
See CONTRIBUTING.md for guidelines.
Apache 2.0 — Copyright 2026 STARGA Inc and contributors.
star-ga/mind-mem
February 18, 2026
April 13, 2026
Python