{"id":45446474,"url":"https://github.com/star-ga/mind-mem","last_synced_at":"2026-05-15T07:13:43.673Z","repository":{"id":339148053,"uuid":"1160652179","full_name":"star-ga/mind-mem","owner":"star-ga","description":"v3.7.0 — Persistent, auditable, contradiction-safe memory for coding agents. HTTP/REST auth fail-closed by default. Cross-platform atomic rollback (Linux/macOS/Windows). 71 MCP tools, 17 AI clients, hybrid BM25+vector+RRF, mind-mem:4b (Ollama). LoCoMo 86.33 conv-0 (Mistral, +8.4 vs published).","archived":false,"fork":false,"pushed_at":"2026-05-02T09:25:26.000Z","size":9714,"stargazers_count":2,"open_issues_count":7,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-02T10:30:53.354Z","etag":null,"topics":["agent-memory","ai-agents","ai-memory","bm25","claude-code","claude-desktop","cursor","fine-tuning","governance","hybrid-search","local-first","mcp","mcp-server","memory","model-context-protocol","python","rrf","sqlite","tool-use","vector-search"],"latest_commit_sha":null,"homepage":"https://mindlang.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/star-ga.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"AUDIT_FINDINGS_FOR_CLAUDE.md","citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY_CONTACTS.md","support":null,"governance":"docs/governance.md","roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"star-ga"}},"created_at":"2026-02-18T07:52:21.000Z","updated_at":"2026-05-02T08:57:44.000Z","dependencies_parsed_at":"2026-03-29T03:04:22.334Z","dependency_job_id":"98868b9b-037a-4489-8b6d-c9d28283bff2","html_url":"https://github.com/star-ga/mind-mem","commit_stats":null,"previous_names":["star-ga/mind-mem"],"tags_count":97,"template":false,"template_full_name":null,"purl":"pkg:github/star-ga/mind-mem","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/star-ga%2Fmind-mem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/star-ga%2Fmind-mem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/star-ga%2Fmind-mem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/star-ga%2Fmind-mem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/star-ga","download_url":"https://codeload.github.com/star-ga/mind-mem/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/star-ga%2Fmind-mem/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32805514,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"online","status_checked_at":"2026-05-09T02:00:06.633Z","response_time":123,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","ai-agents","ai-memory","bm25","claude-code","claude-desktop","cursor","fine-tuning","governance","hybrid-search","local-first","mcp","mcp-server","memory","model-context-protocol","python","rrf","sqlite","tool-use","vector-search"],"created_at":"2026-02-22T04:02:45.211Z","updated_at":"2026-05-09T03:01:10.972Z","avatar_url":"https://github.com/star-ga.png","language":"Python","funding_links":["https://github.com/sponsors/star-ga"],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n \u003cimg src=\"assets/logo.png\" alt=\"MIND-Mem logo\" width=\"140\"\u003e\u003cbr\u003e\n MIND-Mem\n\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n \u003cstrong\u003eDrop-in memory for Claude Code, OpenClaw, and any MCP-compatible agent.\u003c/strong\u003e\u003cbr\u003e\n \u003csub\u003eOpenClaw is an \u003ca href=\"https://github.com/openclaw/openclaw\"\u003eopen-source AI assistant platform\u003c/a\u003e with multi-channel support.\u003c/sub\u003e\n\u003c/p\u003e\n \u003cp align=\"center\"\u003e\n Local-first \u0026bull; Zero-infrastructure \u0026bull; Governance-aware \u0026bull; MIND-accelerated\n \u003c/p\u003e\n \u003cp align=\"center\"\u003e\n \u003ca href=\"https://pypi.org/project/mind-mem/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/mind-mem?include_prereleases\u0026style=flat-square\u0026color=blue\u0026label=PyPI\" alt=\"PyPI\"\u003e\u003c/a\u003e\n \u003ca href=\"https://pypi.org/project/mind-mem/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/pyversions/mind-mem?style=flat-square\" alt=\"Python Versions\"\u003e\u003c/a\u003e\n \u003ca href=\"https://github.com/star-ga/mind-mem/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/pypi/l/mind-mem?style=flat-square\" alt=\"License\"\u003e\u003c/a\u003e\n \u003ca href=\"https://github.com/star-ga/mind-mem/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/star-ga/mind-mem?include_prereleases\u0026style=flat-square\u0026color=green\u0026label=Release\" alt=\"Release\"\u003e\u003c/a\u003e\n \u003cimg src=\"https://img.shields.io/badge/core_deps-zero-brightgreen?style=flat-square\" alt=\"Zero Core Dependencies\"\u003e\n \u003cimg src=\"https://img.shields.io/badge/MCP-compatible-purple?style=flat-square\" alt=\"MCP Compatible\"\u003e\n \u003cimg src=\"https://img.shields.io/badge/MIND-accelerated-orange?style=flat-square\" alt=\"MIND Accelerated\"\u003e\n \u003ca href=\"https://github.com/star-ga/mind-mem/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/star-ga/mind-mem/ci.yml?branch=main\u0026style=flat-square\u0026label=CI\" alt=\"CI\"\u003e\u003c/a\u003e\n \u003ca href=\"https://github.com/star-ga/mind-mem/actions/workflows/release.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/star-ga/mind-mem/release.yml?style=flat-square\u0026label=Release\" alt=\"Release\"\u003e\u003c/a\u003e\n \u003cimg src=\"https://img.shields.io/badge/tests-4000%2B-brightgreen?style=flat-square\" alt=\"Tests: 4000+\"\u003e\n \u003cimg src=\"https://img.shields.io/badge/MCP_tools-58%2B7-blue?style=flat-square\" alt=\"MCP Tools: 58 legacy + 7 consolidated dispatchers\"\u003e\n \u003cimg src=\"https://img.shields.io/badge/clients-17-blueviolet?style=flat-square\" alt=\"AI Clients: 17\"\u003e\n \u003cimg src=\"https://img.shields.io/badge/backends-markdown_%7C_postgres-teal?style=flat-square\" alt=\"Storage: Markdown + Postgres\"\u003e\n \u003cimg src=\"https://img.shields.io/badge/audit-3--LLM_%2B_SAST_%2B_SoW-darkgreen?style=flat-square\" alt=\"3-LLM joint audit + SAST (CodeQL/bandit/trivy) + external-audit SoW published\"\u003e\n\u003c/p\u003e\n\n---\n\nDrop-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.\n\n\u003e **If your agent runs for weeks, it will drift. MIND-Mem prevents silent drift.**\n\u003e\n\u003e MIND-Mem powers the Memory Plane of the [MIND Cognitive Kernel](https://mindlang.dev/docs/cognitive-kernel) — the deterministic AI runtime architecture.\n\n### Shared Memory Across All Your AI Agents\n\n**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.\n\nWhat this means in practice:\n\n- A decision made in **Claude Code** is instantly recalled by **Codex CLI** and **Gemini CLI**\n- Entity knowledge (projects, tools, people) accumulates from **all sessions across all agents**\n- Contradictions detected by one agent are flagged to all others\n- Your memory doesn't fragment across tools — it compounds\n\n**One install script, all agents configured in seconds:**\n\n```bash\ngit clone https://github.com/star-ga/mind-mem.git\ncd mind-mem\n./install.sh --all # Auto-detects and configures every AI coding client on your machine\n```\n\nThe 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.\n\n### 30-Second Demo\n\n```bash\npip install mind-mem\nmind-mem-init ~/my-workspace # Create workspace\nmind-mem-recall -q \"API decisions\" --workspace ~/my-workspace # Hybrid BM25F search\nmind-mem-scan ~/my-workspace # Detect drift \u0026 contradictions\n```\n\nOutput:\n```\n[1.204] D-20260215-001 (decision) — Use async/await for all API endpoints\n decisions/DECISIONS.md:11\n[1.094] D-20260210-003 (decision) — REST over GraphQL for public API\n decisions/DECISIONS.md:20\n```\n\n\u003csub\u003eA fresh v3.x walkthrough (native MCP for 17 clients, 81 tools incl. MIC/MAP + walkthrough/persona/pipeline-hash, `mind-mem:4b` local model, governance alerting, optional Cython hot-path accelerator) is on the way — the earlier `demo.gif` predated v3.x and was removed to avoid misrepresenting the current surface.\u003c/sub\u003e\n\n### Trust Signals\n\n| Principle | What it means |\n| ----------------------- | --------------------------------------------------------------------------------- |\n| **Deterministic** | Same input, same output. No ML in the core, no probabilistic mutations. |\n| **Auditable** | Every apply logged with timestamp, receipt, and DIFF. Full traceability. |\n| **Local-first** | All data stays on disk. No cloud calls, no telemetry, no phoning home. |\n| **No vendor lock-in** | Plain Markdown files. Move to any system, any time. |\n| **Zero magic** | Every check is a grep, every mutation is a file write. Read the source in 30 min. |\n| **No silent mutation** | Nothing writes to source of truth without explicit `/apply`. Ever. |\n| **Zero infrastructure** | Core requires only Python 3.10+ stdlib. Postgres, Redis, Docker, and GPU are opt-in extras — nothing is required to start. |\n| **100% NIAH** | 250/250 Needle In A Haystack retrieval. Every needle, every depth, every size. |\n\n---\n\n## Table of Contents\n\n- [Why MIND-Mem](#why-mind-mem)\n- [Features](#features)\n- [Integrations](#integrations)\n- [Benchmark Results](#benchmark-results)\n- [Quick Start](#quick-start)\n- [Health Summary](#health-summary)\n- [Commands](#commands)\n- [Architecture](#architecture)\n- [How It Compares](#how-it-compares)\n- [Recall](#recall)\n- [MIND Kernels](#mind-kernels)\n- [Auto-Capture](#auto-capture)\n- [Multi-Agent Memory](#multi-agent-memory)\n- [Governance Modes](#governance-modes)\n- [Block Format](#block-format)\n- [Configuration](#configuration)\n- [MCP Server](#mcp-server)\n- [Security](#security)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [License](#license)\n\n### Deep-dive docs\n\n- [`docs/setup.md`](docs/setup.md) — install, configure, wire MCP, opt in to MIND native kernels\n- [`docs/usage.md`](docs/usage.md) — every surface (MCP tools by category, `mm` CLI, `mind-mem-verify`, Python library) with worked examples\n- [`docs/client-integrations.md`](docs/client-integrations.md) — **17 AI client integrations** (Claude Code, Codex, Vibe, Gemini, Cursor, Windsurf, aider, OpenClaw, NanoClaw, NemoClaw, Continue, Cline, Roo, Zed, Copilot, Cody, Qodo) with `mm install-all` auto-detection\n- [`docs/mind-mem-4b-setup.md`](docs/mind-mem-4b-setup.md) — download + run the `star-ga/mind-mem-4b` full-FT model locally (transformers, exllamav2, vLLM, llama.cpp, Ollama)\n- [`ROADMAP.md`](ROADMAP.md) — feature roadmap (all 282 v2.x checkboxes closed in v2.8.0)\n- [`CHANGELOG.md`](CHANGELOG.md) — release notes for every published version\n\n---\n\n## Why MIND-Mem\n\nMost memory plugins **store and retrieve**. That's table stakes.\n\nMIND-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.\n\n| Problem | Without MIND-Mem | With MIND-Mem |\n| ------------------------ | --------------------------------- | ----------------------------------------- |\n| Contradicting decisions | Follows whichever seen last | Flags, links both, proposes fix |\n| Informal chat decision | Lost after session ends | Auto-captured, proposed to formalize |\n| Stale decision | Zombie confuses future sessions | Detected as dead, flagged |\n| Orphan task reference | Silent breakage | Caught in integrity scan |\n| Scattered recall quality | Single-mode search misses context | Hybrid BM25+Vector+RRF fusion finds it |\n| Ambiguous query intent | One-size-fits-all retrieval | 9-type intent router optimizes parameters |\n\n### Novel Contributions\n\nMIND-Mem introduces several techniques not found in existing memory systems:\n\n| Technique | What's new | Why it matters |\n|-----------|-----------|----------------|\n| **Co-retrieval graph** | PageRank-like score propagation across blocks frequently retrieved together | Surfaces structurally relevant blocks with zero lexical overlap (+2.0pp accuracy) |\n| **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) |\n| **Adaptive knee cutoff** | Score-drop-based truncation instead of fixed top-K | Eliminates noise that hurts LLM judges — returns 3-15 results adaptively |\n| **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 |\n| **Deterministic abstention** | Pre-LLM confidence gate using 5-signal scoring (entity, BM25, speaker, evidence, negation) | Prevents hallucinated answers to unanswerable questions — no ML required |\n| **Governance pipeline** | Contradiction detection + drift analysis + safe apply with audit trail | Only memory system that detects when stored knowledge is wrong |\n| **Agent-agnostic shared memory** | Single MCP workspace shared across Claude Code, Codex, Gemini, Cursor, Windsurf, Zed | Memory compounds across tools instead of fragmenting |\n\n---\n\n## Features\n\n### Hybrid BM25+Vector Search with RRF Fusion\nThread-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.\n\n### RM3 Dynamic Query Expansion\nPseudo-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.\n\n### 9-Type Intent Router\nClassifies 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).\n\n### A-MEM Metadata Evolution\nAuto-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.\n\n### Deterministic Reranking\nFour-signal reranking pipeline: negation awareness (penalizes contradicting results), date proximity (Gaussian decay), 20-category taxonomy matching, and recency boosting. No ML required.\n\n### Optional Cross-Encoder\nDrop-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.\n\n### MIND Kernels (Optional, Native Speed)\n17 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](https://mindlang.dev). Pure Python fallback always available — no functionality is lost without compilation.\n\n### MIC/MAP — MIND IR graph serialization\nPure-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`](docs/mic-map.md).\n\n### BM25F Hybrid Recall\nBM25F 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.\n\n### Graph-Based Recall\n2-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.\n\n### Vector Recall (optional)\nPluggable embedding backend — local ONNX (all-MiniLM-L6-v2, no server needed) or cloud (Pinecone). Falls back to BM25 when unavailable.\n\n### Persistent Memory\nStructured, validated, append-only decisions / tasks / entities / incidents with provenance and supersede chains. Plain Markdown files — readable by humans, parseable by machines.\n\n### Immune System\nContinuous integrity checking: contradictions, drift, dead decisions, orphan tasks, coverage scoring, regression detection. 74+ structural validation rules.\n\n### Safe Governance\nAll changes flow through graduated modes: `detect_only` → `propose` → `enforce`. Apply engine with snapshot, receipt, DIFF, and automatic rollback on validation failure.\n\n### Adversarial Abstention Classifier\nDeterministic 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.\n\n### Auto-Capture with Structured Extraction\nSession-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`.\n\n### Concurrency Safety\nCross-platform advisory file locking (`fcntl`/`msvcrt`/atomic create) protects all concurrent write paths. Stale lock detection with PID-based cleanup. Zero dependencies.\n\n### Compaction \u0026 GC\nAutomated workspace maintenance: archive completed blocks, clean up old snapshots, compact resolved signals, archive daily logs into yearly files. Configurable thresholds with dry-run mode.\n\n### Observability\nStructured 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.\n\n### Multi-Agent Namespaces \u0026 ACL\nWorkspace-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.\n\n### Automated Conflict Resolution\nGraduated resolution pipeline: timestamp priority, confidence priority, scope specificity, manual fallback. Generates supersede proposals with integrity hashes. Human veto loop — never auto-applies without review.\n\n### Write-Ahead Log (WAL) + Backup/Restore\nCrash-safe writes via journal-based WAL. Full workspace backup (tar.gz), git-friendly JSONL export, selective restore with conflict detection and path traversal protection.\n\n### Transcript JSONL Capture\nScans 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.\n\n### MCP Server (81 tools, 8 resources)\nFull [Model Context Protocol](https://modelcontextprotocol.io/) server with 81 tools and 8 read-only resources. 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)](#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`.\n\n### 74+ Structural Checks + 3024 Unit Tests\n`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.\n\n### Audit Trail\nEvery applied proposal logged with timestamp, receipt, and DIFF. Full traceability from signal → proposal → decision.\n\n### Calibration Feedback Loop\nPer-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.\n\n### LLM-Guided Multi-Query Expansion\nGenerates 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.\n\n### 4-Layer Search Deduplication\nPost-retrieval dedup pipeline: best-chunk-per-source (keeps highest-scoring chunk from each file), cosine similarity dedup (\u003e0.85 threshold), type diversity capping (max 3 results per block type), and per-source chunk limiting. Eliminates redundant results that waste LLM context.\n\n### LLM-Guided Smart Chunking\nContent-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.\n\n### Compiled Truth Pages\nPer-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.\n\n### Dream Cycle (Autonomous Memory Enrichment)\nScheduled 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.\n\n### Feature Completeness Matrix\n\n| Capability | MIND-Mem | Mem0 | Zep | Letta | LangMem |\n|---|:---:|:---:|:---:|:---:|:---:|\n| BM25 lexical search | Y | — | — | — | — |\n| Vector semantic search | Y | Y | Y | Y | Y |\n| Hybrid BM25+Vector+RRF | Y | — | — | — | — |\n| Cross-encoder reranking | Y | — | — | — | — |\n| Intent-aware routing (9 types) | Y | — | — | — | — |\n| RM3 query expansion | Y | — | — | — | — |\n| Co-retrieval graph (PageRank) | Y | — | — | — | — |\n| Fact sub-block indexing | Y | — | — | — | — |\n| Hard negative mining | Y | — | — | — | — |\n| Adaptive knee cutoff | Y | — | — | — | — |\n| Contradiction detection | Y | — | — | — | — |\n| Drift analysis | Y | — | — | — | — |\n| Governance pipeline (propose/apply) | Y | — | — | — | — |\n| Multi-agent shared memory (MCP) | Y | — | — | Y | — |\n| Zero core dependencies | Y | — | — | — | — |\n| Local-only (no cloud required) | Y | — | — | — | — |\n| Compiled native kernels (MIND) | Y | — | — | — | — |\n| Backup/restore with zip-slip protection | Y | — | — | — | — |\n| Multi-query expansion with RRF | Y | — | — | — | — |\n| 4-layer search deduplication | Y | — | — | — | — |\n| Semantic-aware smart chunking | Y | — | — | — | — |\n| Compiled truth pages (per-entity) | Y | — | — | — | — |\n| Dream cycle (autonomous enrichment) | Y | — | — | — | — |\n\n---\n\n## Integrations\n\n\u003e Honest positioning. The integrations below are *software-level* —\n\u003e the named tool talks to MIND-Mem via the Model Context Protocol.\n\u003e They are **not** commercial-customer relationships with any vendor.\n\u003e Full positioning policy: [`docs/integrations.md`](docs/integrations.md).\n\n### Native MCP integration with 17 AI development tools\n\n```bash\npip install mind-mem\nmm install-all\n```\n\n`mm install-all` auto-detects every supported client on your machine\nand writes the appropriate config file for each. MIND-Mem speaks the\n[Model Context Protocol](https://modelcontextprotocol.io/) — any\nMCP-compatible client connects with one command.\n\n| Client | Vendor | Client | Vendor |\n|--------|--------|--------|--------|\n| Claude Code | Anthropic | Cline | Cline.bot |\n| Claude Desktop | Anthropic | Roo | Roo Code |\n| Codex CLI | OpenAI | GitHub Copilot | GitHub / Microsoft |\n| Gemini CLI | Google | Cody | Sourcegraph |\n| Vibe (Mistral CLI) | Mistral | Qodo | Qodo |\n| Cursor | Anysphere | aider | aider-chat |\n| Windsurf | Codeium | OpenClaw | OpenAI (Peter Steinberger) |\n| Zed | Zed Industries | NemoClaw / Nemo | NVIDIA |\n| Continue | Continue.dev | NanoClaw | Anthropic |\n\n### Compatible with major LLM providers\n\nMIND-Mem's recall pipeline is provider-agnostic. Tested against\nAnthropic Claude (3.5 Sonnet, 4.x), OpenAI GPT (4o, 5.4), Google\nGemini (2.0 Flash, 3.1 Pro), Mistral Large, and local endpoints\n(Ollama, vLLM, llama.cpp). Compatibility is at the API contract\nlevel — the same MIND-Mem server returns the same answers\nregardless of which LLM is asking.\n\n### Production usage at STARGA\n\nMIND-Mem is the daily-driver memory layer for STARGA's six active\nprojects: `mind`, `mind-runtime`, `mindlang.dev`, `mind-inference`,\n`mind-fleet`, `arch-mind`. First-party, verifiable in our own\ncommit history.\n\n### What we do not claim\n\n- ❌ \"OpenAI / Microsoft / Anthropic / Google is a customer\" — false.\n These are software-level MCP integrations, not commercial\n relationships.\n- ❌ \"Used by N production teams outside STARGA\" — we have no\n telemetry. PyPI download counts measure installs, not active use.\n\nIf a future integration becomes a real commercial relationship\n(signed contract, paid pilot, named reference), it will appear in\nthe press release first — not in the README.\n\n---\n\n## Benchmark Results\n\nMIND-Mem's recall engine evaluated on standard long-term memory benchmarks using multiple configurations — from pure BM25 to full hybrid retrieval with neural reranking.\n\n### Needle In A Haystack (NIAH)\n\n**250/250 — 100% retrieval** across all haystack sizes, burial depths, and needle types.\n\nA 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.\n\n| Haystack Size | Depths Tested | Needles | Passed | Rate |\n|---------------|---------------|---------|--------|------|\n| 10 blocks | 0/25/50/75/100% | 10 | 50/50 | 100% |\n| 50 blocks | 0/25/50/75/100% | 10 | 50/50 | 100% |\n| 100 blocks | 0/25/50/75/100% | 10 | 50/50 | 100% |\n| 250 blocks | 0/25/50/75/100% | 10 | 50/50 | 100% |\n| 500 blocks | 0/25/50/75/100% | 10 | 50/50 | 100% |\n\n**Config:** Hybrid BM25 + BAAI/bge-large-en-v1.5 + RRF (k=60) + sqlite-vec. Full details: [benchmarks/NIAH.md](benchmarks/NIAH.md)\n\n### LoCoMo LLM-as-Judge\n\nSame pipeline as Mem0 and Letta evaluations: retrieve context, generate answer with LLM, score against gold reference with judge LLM. Directly comparable methodology.\n\n**v1.0.7 — Hybrid + top_k=18** (Mistral answerer + judge, conv-0, 199 questions):\n\n| Category | N | Acc (\u003e=50) | Mean Score |\n| --------------- | -----: | ---------: | ---------: |\n| **Overall** | **199**| **92.5%** | **76.7** |\n| Adversarial | 47 | 97.9% | 89.8 |\n| Multi-hop | 37 | 91.9% | 74.3 |\n| Open-domain | 70 | 92.9% | 72.7 |\n| Temporal | 13 | 92.3% | 76.2 |\n| Single-hop | 32 | 84.4% | 68.9 |\n\n\u003e **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.\n\n**v1.1.1 — BM25 + top_k=18** (Mistral Large answerer + judge, 10 conversations, 1986 questions):\n\n| Category | N | Acc (\u003e=50) | Mean Score |\n| --------------- | -------: | ---------: | ---------: |\n| **Overall** | **1986** | **73.8%** | **70.5** |\n| Adversarial | 446 | 92.4% | 87.2 |\n| Single-hop | 282 | 80.9% | 68.7 |\n| Open-domain | 841 | 71.2% | 70.3 |\n| Temporal | 96 | 66.7% | 65.9 |\n| Multi-hop | 321 | 50.5% | 51.1 |\n\n\u003e **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.\n\n**v1.0.0 — BM25-only baseline** (gpt-4o-mini answerer + judge, 10 conversations):\n\n| Category | N | Acc (\u003e=50) | Mean Score |\n| ----------- | -------: | ---------: | ---------: |\n| **Overall** | **1986** | **67.3%** | **61.4** |\n| Open-domain | 841 | 86.6% | 78.3 |\n| Temporal | 96 | 78.1% | 65.7 |\n| Single-hop | 282 | 68.8% | 59.1 |\n| Multi-hop | 321 | 55.5% | 48.4 |\n| Adversarial | 446 | 36.3% | 39.5 |\n\n\u003e **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).\n\n### Competitive Landscape\n\n| System | Score | Approach |\n| ------------ | --------: | ------------------------------------------------------------ |\n| **MIND-Mem** | **76.7%** | Hybrid BM25 + Qwen3-8B vector + RRF fusion (local-only) |\n| Memobase | 75.8% | Specialized extraction |\n| **Letta** | 74.0% | Files + agent tool use |\n| **MIND-Mem** | 73.8% | BM25-only, full 10-conv (1986 questions, Mistral Large) |\n| **Mem0** | 68.5% | Graph + LLM extraction |\n\n\u003e 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.\n\n### Benchmark Comparison (2026-02-22)\n\n| System | LoCoMo Acc\u003e=50 | LongMemEval R@10 | Infrastructure | Dependencies |\n| --- | ---: | ---: | --- | --- |\n| **MIND-Mem** (hybrid) | **76.7%** | **88.1%** | **Local-only** | **Zero core (optional: llama.cpp, sentence-transformers)** |\n| Memobase | 75.8% | -- | Cloud + GPU | embeddings + vector DB |\n| Letta | 74.0% | -- | Cloud | embeddings + vector DB |\n| **MIND-Mem** (BM25) | **73.8%** | **88.1%** | **Local-only** | **Zero core** |\n| full-context | 72.9% | -- | N/A | LLM context window |\n| Mem0 | 68.5% | -- | Cloud (managed) | graph DB + embeddings |\n\n\u003e 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.\n\n### LongMemEval (ICLR 2025, 470 questions)\n\n| Category | N | R@1 | R@5 | R@10 | MRR |\n| ---------------- | ------: | -------: | -------: | -------: | -------: |\n| **Overall** | **470** | **73.2** | **85.3** | **88.1** | **.784** |\n| Multi-session | 121 | 83.5 | 95.9 | 95.9 | .885 |\n| Temporal | 127 | 76.4 | 91.3 | 92.9 | .826 |\n| Knowledge update | 72 | 80.6 | 88.9 | 91.7 | .844 |\n| Single-session | 56 | 82.1 | 89.3 | 89.3 | .847 |\n\n### Performance (Latency \u0026 Throughput)\n\nMeasured on a 65-block workspace (typical personal workspace) with SQLite FTS5 backend:\n\n| Operation | Metric | Value |\n|-----------|--------|-------|\n| **Query** (FTS5 + rerank) | p50 latency | **2.1 ms** |\n| **Query** (FTS5 + rerank) | p95 latency | **4.9 ms** |\n| **Query** (FTS5 + rerank) | mean latency | **2.6 ms** |\n| **Incremental reindex** | elapsed | **32 ms** (13 blocks indexed) |\n| **Full index build** | elapsed | **48 ms** (65 blocks) |\n| **MCP tool overhead** | stdio round-trip | **\u003c 15 ms** |\n| **Memory footprint** | RSS (idle MCP server) | **~28 MB** |\n\nQuery latency scales as O(log N) with SQLite FTS5 (vs O(corpus) for scan backend). The co-retrieval graph adds \u003c 1ms per query. Knee cutoff and fact aggregation add negligible overhead (\u003c 0.5ms).\n\n### Run Benchmarks Yourself\n\n```bash\n# Retrieval-only (R@K metrics)\n\n## Install in 3 commands\n\n```bash\npip install mind-mem\nmm install-all --force # auto-wires every detected AI CLI\nmm install-model # downloads mind-mem-4b GGUF + imports to Ollama\n```\n\nFull options + Postgres setup + troubleshooting:\n[**docs/install-guide.md**](docs/install-guide.md)\n\npython3 benchmarks/locomo_harness.py\npython3 benchmarks/longmemeval_harness.py\n\n# LLM-as-judge (accuracy metrics, requires API key)\npython3 benchmarks/locomo_judge.py --dry-run\npython3 benchmarks/locomo_judge.py --answerer-model gpt-4o-mini --output results.json\n\n# Hybrid retrieval with any model pair (BM25 + vector + cross-encoder)\npython3 benchmarks/locomo_judge.py --hybrid --compress --answerer-model mistral-large-latest --judge-model mistral-large-latest --output results.json\n\n# Selective conversations\npython3 benchmarks/locomo_harness.py --conv-ids 4,7,8\n```\n\n---\n\n## Quick Start\n\n### One-line install (recommended)\n\n```bash\npipx install \"mind-mem[mcp]\"\nmind-mem-mcp --help # smoke-test\n```\n\n`pipx` keeps MIND-Mem in its own venv, exposes the `mind-mem-mcp` console\nscript on `PATH`, and avoids polluting your system Python. If you don't have\npipx, `pip install --user \"mind-mem[mcp]\"` works too.\n\nThen wire it into every AI coding client on your machine:\n\n```bash\ngit clone https://github.com/star-ga/mind-mem.git\ncd mind-mem\n./install.sh --all --no-install # Already installed via pipx, just wire clients\n```\n\nOr do both in one shot (the installer will auto-pick pipx if available, else\nfall back to pip):\n\n```bash\ngit clone https://github.com/star-ga/mind-mem.git\ncd mind-mem\n./install.sh --all\n```\n\nThis auto-detects every AI coding client on your machine and configures MIND-Mem\nfor all of them. Each client launches the same `mind-mem-mcp` binary, so all\nagents share one workspace. Supported clients:\n\n| Client | Config Location | Format |\n| ----------------------- | --------------------------------------------- | ------- |\n| **Claude Code CLI** | `~/.claude/mcp.json` | JSON |\n| **Claude Desktop** | `~/.config/Claude/claude_desktop_config.json` | JSON |\n| **Codex CLI** (OpenAI) | `~/.codex/config.toml` | TOML |\n| **Gemini CLI** (Google) | `~/.gemini/settings.json` | JSON |\n| **Cursor** | `~/.cursor/mcp.json` | JSON |\n| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | JSON |\n| **Zed** | `~/.config/zed/settings.json` | JSON |\n| **OpenClaw** | `~/.openclaw/hooks/mind-mem/` | JS hook |\n\nSelective install:\n\n```bash\n./install.sh --claude-code --codex --gemini # Only specific clients\n./install.sh --all --workspace ~/my-project/memory # Custom workspace path\n```\n\nUninstall:\n\n```bash\n./uninstall.sh # Remove from all clients (keeps workspace data)\n./uninstall.sh --purge # Remove everything including workspace data\n```\n\n### Manual Setup\n\nFor manual or per-project setup:\n\n**1. Clone into your project**\n\n```bash\ncd /path/to/your/project\ngit clone https://github.com/star-ga/mind-mem.git .mind-mem\n```\n\n**2. Initialize workspace**\n\n```bash\npython3 .mind-mem/src/mind_mem/init_workspace.py .\n```\n\nCreates 12 directories, 19 template files, and `mind-mem.json` config. **Never overwrites existing files.**\n\n**3. Validate**\n\n```bash\nbash .mind-mem/src/mind_mem/validate.sh .\n# or cross-platform:\npython3 .mind-mem/src/mind_mem/validate_py.py .\n```\n\nExpected: `74 checks | 74 passed | 0 issues`.\n\n**4. First scan**\n\n```bash\npython3 .mind-mem/src/mind_mem/intel_scan.py .\n```\n\nExpected: `0 critical | 0 warnings` on a fresh workspace.\n\n**5. Verify recall + capture**\n\n```bash\npython3 .mind-mem/src/mind_mem/recall.py --query \"test\" --workspace .\n# → No results found. (empty workspace — correct)\n\npython3 .mind-mem/src/mind_mem/capture.py .\n# → capture: no daily log for YYYY-MM-DD, nothing to scan (correct)\n```\n\n**6. Add hooks (optional)**\n\n**Option A: Claude Code hooks** (recommended)\n\nMerge into your `.claude/hooks.json`:\n\n```json\n{\n \"hooks\": [\n {\n \"event\": \"SessionStart\",\n \"command\": \"bash .mind-mem/hooks/session-start.sh\"\n },\n {\n \"event\": \"Stop\",\n \"command\": \"bash .mind-mem/hooks/session-end.sh\"\n }\n ]\n}\n```\n\n**Option B: OpenClaw hooks** (for OpenClaw 2026.2+)\n\n```bash\ncp -r .mind-mem/hooks/openclaw/mind-mem ~/.openclaw/hooks/mind-mem\nopenclaw hooks enable mind-mem\n```\n\n**7. Smoke Test (optional)**\n\n```bash\nbash .mind-mem/src/mind_mem/smoke_test.sh\n```\n\nCreates a temp workspace, runs init → validate → scan → recall → capture → pytest, then cleans up.\n\n---\n\n## Health Summary\n\nAfter setup, this is what a healthy workspace looks like:\n\n```\n$ python3 -m mind_mem.intel_scan .\n\nmind-mem Intelligence Scan Report v2.0\nMode: detect_only\n\n=== 1. CONTRADICTION DETECTION ===\n OK: No contradictions found among 25 signatures.\n\n=== 2. DRIFT ANALYSIS ===\n OK: All active decisions referenced or exempt.\n INFO: Metrics: active_decisions=17, active_tasks=7, blocked=0,\n dead_decisions=0, incidents=3, decision_coverage=100%\n\n=== 3. DECISION IMPACT GRAPH ===\n OK: Built impact graph: 11 decision(s) with edges.\n\n=== 4. STATE SNAPSHOT ===\n OK: Snapshot saved.\n\n=== 5. WEEKLY BRIEFING ===\n OK: Briefing generated.\n\nTOTAL: 0 critical | 0 warnings | 16 info\n```\n\n---\n\n## Commands\n\n| Command | What it does |\n| ----------------- | ----------------------------------------------------------------------------------------------- |\n| `/scan` | Run integrity scan — contradictions, drift, dead decisions, impact graph, snapshot, briefing |\n| `/apply` | Review and apply proposals from scan results (dry-run first, then apply) |\n| `/recall \u003cquery\u003e` | Search across all memory files with ranked results (add `--graph` for cross-reference boosting) |\n\n---\n\n## Architecture\n\n```\nyour-workspace/\n├── mcp_server.py # MCP server (FastMCP, 81 tools, 8 resources)\n├── mind-mem.json # Config\n├── MEMORY.md # Protocol rules\n│\n├── mind/ # 17 MIND source files (.mind)\n│ ├── bm25.mind # BM25F scoring kernel\n│ ├── rrf.mind # Reciprocal Rank Fusion kernel\n│ ├── reranker.mind # Deterministic reranking\n│ ├── abstention.mind # Confidence gating\n│ ├── ranking.mind # Evidence ranking\n│ ├── importance.mind # A-MEM importance scoring\n│ ├── category.mind # Category relevance scoring\n│ ├── recall.mind # Combined recall scoring\n│ ├── hybrid.mind # BM25 + vector hybrid fusion\n│ ├── rm3.mind # RM3 pseudo-relevance feedback\n│ ├── rerank.mind # Score combination pipeline\n│ ├── adversarial.mind # Adversarial query detection\n│ ├── temporal.mind # Time-aware scoring\n│ ├── prefetch.mind # Context pre-assembly\n│ ├── intent.mind # Intent classification\n│ └── cross_encoder.mind # Cross-encoder blending\n│\n├── lib/ # Compiled MIND kernels (optional)\n│ └── libmindmem.so # mindc output — not required for operation\n│\n├── decisions/\n│ └── DECISIONS.md # Formal decisions [D-YYYYMMDD-###]\n├── tasks/\n│ └── TASKS.md # Tasks [T-YYYYMMDD-###]\n├── entities/\n│ ├── projects.md # [PRJ-###]\n│ ├── people.md # [PER-###]\n│ ├── tools.md # [TOOL-###]\n│ └── incidents.md # [INC-###]\n│\n├── memory/\n│ ├── YYYY-MM-DD.md # Daily logs (append-only)\n│ ├── intel-state.json # Scanner state + metrics\n│ └── maint-state.json # Maintenance state\n│\n├── summaries/\n│ ├── weekly/ # Weekly summaries\n│ └── daily/ # Daily summaries\n│\n├── intelligence/\n│ ├── CONTRADICTIONS.md # Detected contradictions\n│ ├── DRIFT.md # Drift detections\n│ ├── SIGNALS.md # Auto-captured signals\n│ ├── IMPACT.md # Decision impact graph\n│ ├── BRIEFINGS.md # Weekly briefings\n│ ├── AUDIT.md # Applied proposal audit trail\n│ ├── SCAN_LOG.md # Scan history\n│ ├── proposed/ # Staged proposals + resolution proposals\n│ │ ├── DECISIONS_PROPOSED.md\n│ │ ├── TASKS_PROPOSED.md\n│ │ ├── EDITS_PROPOSED.md\n│ │ └── RESOLUTIONS_PROPOSED.md\n│ ├── applied/ # Snapshot archives (rollback)\n│ └── state/snapshots/ # State snapshots\n│\n├── shared/ # Multi-agent shared namespace\n│ ├── decisions/\n│ ├── tasks/\n│ ├── entities/\n│ └── intelligence/\n│ └── LEDGER.md # Cross-agent fact ledger\n│\n├── agents/ # Per-agent private namespaces\n│ └── \u003cagent-id\u003e/\n│ ├── decisions/\n│ ├── tasks/\n│ └── memory/\n│\n├── mind-mem-acl.json # Multi-agent access control\n├── .mind-mem-wal/ # Write-ahead log (crash recovery)\n│\n└── src/mind_mem/\n ├── mind_ffi.py # MIND FFI bridge (ctypes)\n ├── hybrid_recall.py # Hybrid BM25+Vector+RRF orchestrator\n ├── block_metadata.py # A-MEM metadata evolution\n ├── cross_encoder_reranker.py # Optional cross-encoder\n ├── intent_router.py # 9-type intent classification (adaptive)\n ├── recall.py # BM25F + RM3 + graph scoring engine\n ├── recall_vector.py # Vector/embedding backends\n ├── sqlite_index.py # FTS5 + vector + metadata index\n ├── connection_manager.py # SQLite connection pool (WAL read/write separation)\n ├── block_store.py # BlockStore protocol + MarkdownBlockStore\n ├── corpus_registry.py # Central corpus path registry\n ├── abstention_classifier.py # Adversarial abstention\n ├── evidence_packer.py # Evidence assembly and ranking\n ├── intel_scan.py # Integrity scanner\n ├── apply_engine.py # Proposal apply engine (delta-based snapshots)\n ├── block_parser.py # Markdown block parser (typed)\n ├── capture.py # Auto-capture (26 patterns)\n ├── compaction.py # Compaction/GC/archival\n ├── mind_filelock.py # Cross-platform advisory file locking\n ├── observability.py # Structured JSON logging + metrics\n ├── namespaces.py # Multi-agent namespace \u0026 ACL\n ├── conflict_resolver.py # Automated conflict resolution\n ├── backup_restore.py # WAL + backup/restore + JSONL export\n ├── transcript_capture.py # Transcript JSONL signal extraction\n ├── validate.sh # Structural validator (74+ checks)\n └── validate_py.py # Structural validator (Python, cross-platform)\n```\n\n---\n\n## How It Compares\n\n### Quick Comparison\n\n| Feature | MIND-Mem | Mem0 | Letta | Zep/Graphiti |\n|---------|----------|------|-------|--------------|\n| Local-only | Yes | No (cloud API) | No (runtime) | No (Neo4j) |\n| Zero infrastructure | Yes | No | No | No |\n| Hybrid retrieval | BM25F + vector + RRF | Vector only | Hybrid | Graph + vector |\n| Governance (propose/review/apply) | Yes | No | No | No |\n| Contradiction detection | Yes | No | No | No |\n| Tests | 3,600+ | - | - | - |\n| LoCoMo benchmark | 86.33 conv-0 (v3.6, Mistral-Large) | 66.88 | 74.0% | - |\n| MCP tools | 81 (58 legacy + 7 dispatchers + 16 v3.7→v3.9 additions) | - | - | - |\n| Core dependencies | 0 | Many | Many | Many |\n\n### At a Glance\n\n| Tool | Strength | Trade-off |\n| ---- | -------- | --------- |\n| [**Mem0**](https://github.com/mem0ai/mem0) | Fast managed service, graph memory, multi-user scoping | Cloud-dependent, no integrity checking |\n| [**Supermemory**](https://supermemory.ai) | Fastest retrieval (ms), auto-ingestion from Drive/Notion | Cloud-dependent, auto-writes without review |\n| [**claude-mem**](https://github.com/thedotmack/claude-mem) | Purpose-built for Claude Code, ChromaDB vectors | Requires ChromaDB + Express worker, no integrity |\n| [**Letta**](https://www.letta.com) | Self-editing memory blocks, sleep-time compute, 74% LoCoMo | Full agent runtime (heavy), not just memory |\n| [**Zep**](https://www.getzep.com) | Temporal knowledge graph, bi-temporal model, sub-second at scale | Cloud service, complex architecture |\n| [**LangMem**](https://github.com/langchain-ai) | Native LangChain/LangGraph integration | Tied to LangChain ecosystem |\n| [**Cognee**](https://www.cognee.ai) | Advanced chunking, web content bridging | Research-oriented, complex setup |\n| [**Graphlit**](https://www.graphlit.com) | Multimodal ingestion, semantic search, managed platform | Cloud-only, managed service |\n| [**ClawMem**](https://github.com/yoloshii/ClawMem) | Full ML pipeline (cross-encoder + QMD + beam search) | 4.5GB VRAM, 3 GPU processes required |\n| [**MemU**](https://github.com/supermemory/memu) | Hierarchical 3-layer memory, multimodal ingestion, LLM-based retrieval | Requires LLM for extraction and retrieval, no hybrid search |\n| **MIND-Mem** | Integrity + governance + zero core deps + hybrid search + MIND kernels + 81 MCP tools (incl. MIC/MAP, walkthrough, persona, pipeline-hash) + 3-LLM audit per release | Lexical recall by default (vector/CE optional) |\n\n### Full Feature Matrix\n\nCompared against every major memory solution for AI agents (as of 2026):\n\n| | [Mem0](https://github.com/mem0ai/mem0) | [Supermemory](https://supermemory.ai) | [claude-mem](https://github.com/thedotmack/claude-mem) | [Letta](https://www.letta.com) | [Zep](https://www.getzep.com) | [LangMem](https://github.com/langchain-ai) | [Cognee](https://www.cognee.ai) | [Graphlit](https://www.graphlit.com) | [ClawMem](https://github.com/yoloshii/ClawMem) | [MemU](https://github.com/supermemory/memu) | **MIND-Mem** |\n| --------------- | :------------------------------------: | :-----------------------------------: | :-----------------------------------------------------: | :----------------------------: | :---------------------------: | :-----------------------------------------: | :-----------------------------: | :----------------------------------: | :---------------------------------------------: | :------------------------------------------: | :----------: |\n| **Recall** | | | | | | | | | | | |\n| Vector | Cloud | Cloud | Chroma | Yes | Yes | Yes | Yes | Yes | Yes | — | **Optional** |\n| Lexical | Filter | — | — | — | — | — | — | — | BM25 | — | **BM25F** |\n| Graph | Yes | — | — | — | Yes | — | Yes | Yes | Beam | — | **2-hop** |\n| Hybrid + RRF | Part | — | — | — | Yes | — | Yes | Yes | **Yes** | — | **Yes** |\n| Cross-encoder | — | — | — | — | — | — | — | — | qwen3 0.6B | — | **MiniLM 80MB** |\n| Intent routing | — | — | — | — | — | — | — | — | Yes | — | **9 types** |\n| Query expansion | — | — | — | — | — | — | — | — | QMD 1.7B | — | **RM3 (zero-dep)** |\n| **Persistence** | | | | | | | | | | | |\n| Structured | JSON | JSON | SQL | Blk | Grph | KV | Grph | Grph | SQL | Markdown | **Markdown** |\n| Entities | Yes | Yes | — | Yes | Yes | Yes | Yes | Yes | — | Yes | **Yes** |\n| Temporal | — | — | — | — | Yes | — | — | — | — | — | **Yes** |\n| Supersede | — | — | — | Yes | Yes | — | — | — | — | — | **Yes** |\n| Append-only | — | — | — | — | — | — | — | — | — | — | **Yes** |\n| A-MEM metadata | — | — | — | — | — | — | — | — | Yes | — | **Yes** |\n| **Integrity** | | | | | | | | | | | |\n| Contradictions | — | — | — | — | — | — | — | — | — | — | **Yes** |\n| Drift detection | — | — | — | — | — | — | — | — | — | — | **Yes** |\n| Validation | — | — | — | — | — | — | — | — | — | — | **74+ rules** |\n| Impact graph | — | — | — | — | — | — | — | — | — | — | **Yes** |\n| Coverage | — | — | — | — | — | — | — | — | — | — | **Yes** |\n| Multi-agent | — | — | — | Yes | — | — | — | — | — | — | **ACL-based** |\n| Conflict res. | — | — | — | — | — | — | — | — | — | — | **Automatic** |\n| WAL/crash | — | — | — | — | — | — | — | — | — | — | **Yes** |\n| Backup/restore | — | — | — | — | — | — | — | — | — | — | **Yes** |\n| Abstention | — | — | — | — | — | — | — | — | — | — | **Yes** |\n| **Governance** | | | | | | | | | | | |\n| Auto-capture | Auto | Auto | Auto | Self | Ext | Ext | Ext | Ing | Auto | LLM Ext | **Propose** |\n| Proposal queue | — | — | — | — | — | — | — | — | — | — | **Yes** |\n| Rollback | — | — | — | — | — | — | — | — | — | — | **Yes** |\n| Mode governance | — | — | — | — | — | — | — | — | — | — | **3 modes** |\n| Audit trail | — | Part | — | — | — | — | — | — | — | — | **Full** |\n| **Operations** | | | | | | | | | | | |\n| Local-only | — | — | Yes | — | — | — | — | — | Yes | Yes | **Yes** |\n| Zero core deps | — | — | — | — | — | — | — | — | — | — | **Yes** |\n| No daemon | — | — | — | — | — | Yes | — | — | — | Yes | **Yes** |\n| GPU required | — | — | — | — | — | — | — | — | **4.5GB** | No | **No** |\n| Git-friendly | — | — | — | Part | — | — | — | — | — | Yes | **Yes** |\n| MCP server | — | — | — | — | — | — | — | — | — | — | **81 tools** |\n| MIND kernels | — | — | — | — | — | — | — | — | — | — | **16 source** |\n\n### The Gap MIND-Mem Fills\n\nEvery tool above does **storage + retrieval**. None of them answer:\n\n- \"Do any of my decisions contradict each other?\"\n- \"Which decisions are active but nobody references anymore?\"\n- \"Did I make a decision in chat that was never formalized?\"\n- \"What's the downstream impact if I change this decision?\"\n- \"Is my memory state structurally valid right now?\"\n\n**MIND-Mem focuses on memory governance and integrity — the critical layer most memory systems ignore entirely.**\n\n### Why Plain Files Outperform Fancy Retrieval\n\nLetta'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:\n\n- **LLMs excel at tool-based retrieval.** Agents can iteratively query/refine file searches better than single-shot vector retrieval that might miss subtle connections.\n- **Benchmarks reward recall + reasoning over storage sophistication.** Strong judge LLMs handle the rest once relevant chunks are loaded.\n- **Overhead hurts.** Specialized pipelines introduce failure modes (bad embeddings, chunking errors, stale indexes) that simple file access avoids.\n- **For text-heavy agentic use cases, \"how well the agent manages context\" \u003e \"how smart the retrieval index is.\"**\n\nMIND-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.\n\n---\n\n## Recall\n\n### Default: BM25 Hybrid\n\n```bash\npython3 -m mind_mem.recall --query \"authentication\" --workspace .\npython3 -m mind_mem.recall --query \"auth\" --json --limit 5 --workspace .\npython3 -m mind_mem.recall --query \"deadline\" --active-only --workspace .\n```\n\nBM25F 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.\n\n**BM25F field weighting:** Terms in `Statement` fields score 3x higher than terms in `Context` (0.5x). This naturally prioritizes core content over auxiliary metadata.\n\n**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.\n\n**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.\n\n**Stemming:** \"queries\" matches \"query\", \"deployed\" matches \"deployment\". Simplified Porter stemmer with zero dependencies.\n\n### Hybrid Search (BM25 + Vector + RRF)\n\n```json\n{\n \"recall\": {\n \"backend\": \"hybrid\",\n \"vector_enabled\": true,\n \"rrf_k\": 60,\n \"bm25_weight\": 1.0,\n \"vector_weight\": 1.0\n }\n}\n```\n\nThread-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.\n\n### Graph-Based (2-hop cross-reference boost)\n\n```bash\npython3 -m mind_mem.recall --query \"database\" --graph --workspace .\n```\n\n2-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.\n\n### Vector (pluggable)\n\n```json\n{\n \"recall\": {\n \"backend\": \"vector\",\n \"vector_enabled\": true,\n \"vector_model\": \"all-MiniLM-L6-v2\",\n \"onnx_backend\": true\n }\n}\n```\n\nSupports ONNX inference (local, no server) or cloud embeddings. Falls back to BM25 automatically if unavailable.\n\n---\n\n## MIND Kernels\n\nMIND-Mem includes 17 `.mind` kernel source files — numerical hot paths written in the [MIND programming language](https://mindlang.dev). 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.\n\n### Compilation\n\nRequires the MIND compiler (`mindc`). See [mindlang.dev](https://mindlang.dev) for installation.\n\n```bash\n# Compile all kernels to a single shared library\nmindc mind/*.mind --emit=shared -o lib/libmindmem.so\n\n# Or compile individually for testing\nmindc mind/bm25.mind --emit=shared -o lib/libbm25.so\n```\n\n### Kernel Index\n\n| File | Functions | Purpose |\n| ------------------ | ------------------------------------------------------------------------------------ | ------------------------------------ |\n| `bm25.mind` | `bm25f_doc`, `bm25f_batch`, `apply_recency`, `apply_graph_boost` | BM25F scoring with field boosts |\n| `rrf.mind` | `rrf_fuse`, `rrf_fuse_three` | Reciprocal Rank Fusion |\n| `reranker.mind` | `date_proximity_score`, `category_boost`, `negation_penalty`, `rerank_deterministic` | Deterministic reranking |\n| `rerank.mind` | `rerank_scores` | Score combination pipeline |\n| `abstention.mind` | `entity_overlap`, `confidence_score` | Confidence gating |\n| `ranking.mind` | `weighted_rank`, `top_k_mask` | Evidence ranking |\n| `importance.mind` | `importance_score` | A-MEM importance scoring |\n| `category.mind` | `category_affinity`, `query_category_relevance`, `category_assign` | Category distillation scoring |\n| `prefetch.mind` | `prefetch_score`, `prefetch_select` | Signal-based context pre-assembly |\n| `recall.mind` | `recall_score` | Combined recall scoring |\n| `hybrid.mind` | `hybrid_fuse` | BM25 + vector hybrid fusion |\n| `rm3.mind` | `rm3_weight` | RM3 pseudo-relevance feedback |\n| `adversarial.mind` | `adversarial_gate` | Adversarial query detection |\n| `temporal.mind` | `temporal_decay` | Time-aware scoring |\n| `intent.mind` | `intent_params` | Intent classification parameters |\n| `cross_encoder.mind` | `ce_blend` | Cross-encoder blending configuration |\n\n### Performance\n\n\u003cdetails\u003e\n\u003csummary\u003eCompiled MIND kernels vs pure Python — 9 core scoring functions (200 iterations, \u003ccode\u003eperf_counter\u003c/code\u003e)\u003c/summary\u003e\n\n\u0026nbsp;\n\n| Function | N=100 | N=1,000 | N=5,000 |\n| ------------------ | --------: | --------: | --------: |\n| `rrf_fuse` | **10.8x** | **69.0x** | **72.5x** |\n| `bm25f_batch` | **13.2x** | **113.8x** | **193.1x** |\n| `negation_penalty` | **3.3x** | **7.0x** | **18.4x** |\n| `date_proximity` | **10.7x** | **15.3x** | **26.9x** |\n| `category_boost` | **3.3x** | **19.8x** | **17.7x** |\n| `importance_batch` | **22.3x** | **46.2x** | **48.6x** |\n| `confidence_score` | **0.9x** | **0.8x** | **0.9x** |\n| `top_k_mask` | **3.1x** | **8.1x** | **11.8x** |\n| `weighted_rank` | **5.1x** | **26.6x** | **121.8x** |\n| **Overall** | | | **49.0x** |\n\n\u003e **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.\n\n\u003c/details\u003e\n\n### FFI Bridge\n\nThe compiled `.so` exposes a C99-compatible ABI. Python calls via `ctypes` through `src/mind_mem/mind_ffi.py`:\n\n```python\nfrom mind_ffi import get_kernel, is_available, is_protected\n\nif is_available():\n kernel = get_kernel()\n scores = kernel.rrf_fuse_py(bm25_ranks, vec_ranks, k=60.0)\n print(f\"Protected: {is_protected()}\") # True with FORTRESS build\n```\n\n### Without MIND\n\nIf `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.\n\n---\n\n## Auto-Capture\n\n```\nSession end\n ↓\ncapture.py scans daily log (or --scan-all for batch)\n ↓\nDetects decision/task language (26 patterns, 3 confidence levels)\n ↓\nExtracts structured metadata (subject, object, tags)\n ↓\nClassifies confidence (high/medium/low → P1/P2/P3)\n ↓\nWrites to intelligence/SIGNALS.md ONLY\n ↓\nUser reviews signals\n ↓\n/apply promotes to DECISIONS.md or TASKS.md\n```\n\n**Batch scanning:** `python3 -m mind_mem.capture . --scan-all` scans the last 7 days of daily logs.\n\n**Safety guarantee:** `capture.py` never writes to `decisions/` or `tasks/` directly. All signals must go through the apply engine.\n\n---\n\n## Multi-Agent Memory\n\n### Namespace Setup\n\n```bash\npython3 -m mind_mem.namespaces workspace/ --init coder-1 reviewer-1\n```\n\nCreates `shared/` (visible to all) and `agents/coder-1/`, `agents/reviewer-1/` (private) directories with ACL config.\n\n### Access Control\n\n```json\n{\n \"default_policy\": \"read\",\n \"agents\": {\n \"coder-1\": {\"namespaces\": [\"shared\", \"agents/coder-1\"], \"write\": [\"agents/coder-1\"], \"read\": [\"shared\"]},\n \"reviewer-*\": {\"namespaces\": [\"shared\"], \"write\": [], \"read\": [\"shared\"]},\n \"*\": {\"namespaces\": [\"shared\"], \"write\": [], \"read\": [\"shared\"]}\n }\n}\n```\n\n### Shared Fact Ledger\n\nHigh-confidence facts proposed to `shared/intelligence/LEDGER.md` become visible to all agents after review. Append-only with dedup and file locking.\n\n### Conflict Resolution\n\n```bash\npython3 -m mind_mem.conflict_resolver workspace/ --analyze\npython3 -m mind_mem.conflict_resolver workspace/ --propose\n```\n\nGraduated resolution: confidence priority \u003e scope specificity \u003e timestamp priority \u003e manual fallback.\n\n### Transcript Capture\n\n```bash\npython3 -m mind_mem.transcript_capture workspace/ --transcript path/to/session.jsonl\npython3 -m mind_mem.transcript_capture workspace/ --scan-recent --days 3\n```\n\nScans Claude Code JSONL transcripts for user corrections, convention discoveries, and architectural decisions. 16 patterns with confidence classification.\n\n### Backup \u0026 Restore\n\n```bash\npython3 -m mind_mem.backup_restore backup workspace/ --output backup.tar.gz\npython3 -m mind_mem.backup_restore export workspace/ --output export.jsonl\npython3 -m mind_mem.backup_restore restore workspace/ --input backup.tar.gz\npython3 -m mind_mem.backup_restore wal-replay workspace/\n```\n\n---\n\n## Governance Modes\n\n| Mode | What it does | When to use |\n| ------------- | -------------------------------------------------------- | --------------------------------------------------------- |\n| `detect_only` | Scan + validate + report only | **Start here.** First week after install. |\n| `propose` | Report + generate fix proposals in `proposed/` | After a clean observation week with zero critical issues. |\n| `enforce` | Bounded auto-supersede + self-healing within constraints | Production mode. Requires explicit opt-in. |\n\n**Recommended rollout:**\n1. Install → run in `detect_only` for 7 days\n2. Review scan logs → if clean, switch to `propose`\n3. Triage proposals for 2-3 weeks → if confident, enable `enforce`\n\n---\n\n## Block Format\n\nAll structured data uses a simple, parseable markdown format:\n\n```markdown\n[D-20260213-001]\nDate: 2026-02-13\nStatus: active\nStatement: Use PostgreSQL for the user database\nTags: database, infrastructure\nRationale: Better JSON support than MySQL for our use case\nConstraintSignatures:\n- id: CS-db-engine\n domain: infrastructure\n subject: database\n predicate: engine\n object: postgresql\n modality: must\n priority: 9\n scope: {projects: [PRJ-myapp]}\n evidence: Benchmarked JSON performance\n axis:\n key: database.engine\n relation: standalone\n enforcement: structural\n```\n\nBlocks are parsed by `block_parser.py` — a zero-dependency markdown parser that extracts `[ID]` headers and `Key: Value` fields into structured dicts.\n\n---\n\n## Configuration\n\nAll settings in `mind-mem.json` (created by `init_workspace.py`):\n\n```json\n{\n \"version\": \"2.8.0\",\n \"workspace_path\": \".\",\n \"auto_capture\": true,\n \"auto_recall\": true,\n \"governance_mode\": \"detect_only\",\n \"recall\": {\n \"backend\": \"bm25\",\n \"rrf_k\": 60,\n \"bm25_weight\": 1.0,\n \"vector_weight\": 1.0,\n \"vector_model\": \"all-MiniLM-L6-v2\",\n \"vector_enabled\": false,\n \"onnx_backend\": false\n },\n \"proposal_budget\": {\n \"per_run\": 3,\n \"per_day\": 6,\n \"backlog_limit\": 30\n },\n \"compaction\": {\n \"archive_days\": 90,\n \"snapshot_days\": 30,\n \"log_days\": 180,\n \"signal_days\": 60\n },\n \"scan_schedule\": \"daily\"\n}\n```\n\n| Key | Default | Description |\n| ------------------------------- | -------------------- | ------------------------------------------------------------ |\n| `version` | `\"2.8.0\"` | Config file version |\n| `auto_capture` | `true` | Run capture engine on session end |\n| `auto_recall` | `true` | Show recall context on session start |\n| `governance_mode` | `\"detect_only\"` | Governance mode (`detect_only`, `propose`, `enforce`) |\n| `recall.backend` | `\"scan\"` | `\"scan\"` (BM25), `\"hybrid\"` (BM25+Vector+RRF), or `\"vector\"` |\n| `recall.rrf_k` | `60` | RRF fusion parameter k |\n| `recall.bm25_weight` | `1.0` | BM25 weight in RRF fusion |\n| `recall.vector_weight` | `1.0` | Vector weight in RRF fusion |\n| `recall.vector_model` | `\"all-MiniLM-L6-v2\"` | Embedding model for vector search |\n| `recall.vector_enabled` | `false` | Enable vector search backend |\n| `recall.onnx_backend` | `false` | Use ONNX for local embeddings (no server needed) |\n| `proposal_budget.per_run` | `3` | Max proposals generated per scan |\n| `proposal_budget.per_day` | `6` | Max proposals per day |\n| `proposal_budget.backlog_limit` | `30` | Max pending proposals before pausing |\n| `compaction.archive_days` | `90` | Archive completed blocks older than N days |\n| `compaction.snapshot_days` | `30` | Remove apply snapshots older than N days |\n| `compaction.log_days` | `180` | Archive daily logs older than N days |\n| `compaction.signal_days` | `60` | Remove resolved/rejected signals older than N days |\n| `scan_schedule` | `\"daily\"` | `\"daily\"` or `\"manual\"` |\n\n---\n\n## MCP Server\n\nMIND-Mem ships with a [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes memory as resources and tools to any MCP-compatible client.\n\n### Install\n\n```bash\npipx install \"mind-mem[mcp]\" # preferred — isolated venv with mind-mem-mcp on PATH\n# or\npip install --user \"mind-mem[mcp]\"\n```\n\nThe `[mcp]` extra pulls `fastmcp\u003e=3.2.0` (the version line declared in\npyproject.toml) and registers the `mind-mem-mcp` console script.\n\n### Automatic Setup (Recommended)\n\n```bash\n./install.sh --all\n```\n\nConfigures all detected clients automatically. See [Quick Start](#quick-start).\n\n### Manual Setup\n\nFor Claude Code, Claude Desktop, Cursor, Windsurf, and Gemini CLI, add to the respective JSON config under `mcpServers`:\n\n```json\n{\n \"mcpServers\": {\n \"mind-mem\": {\n \"command\": \"mind-mem-mcp\",\n \"args\": [],\n \"env\": {\"MIND_MEM_WORKSPACE\": \"/path/to/your/workspace\"}\n }\n }\n}\n```\n\n`mind-mem-mcp` is the console script registered by `pipx install\n\"MIND-Mem[mcp]\"` (or `pip install --user \"MIND-Mem[mcp]\"`). If you're running\nout of a source checkout instead, replace `\"command\": \"mind-mem-mcp\"` with\n`\"command\": \"python3\", \"args\": [\"/path/to/mind-mem/mcp_server.py\"]`.\n\n| Client | Config File |\n| ------------------- | --------------------------------------------- |\n| **Claude Code CLI** | `~/.claude/mcp.json` |\n| **Claude Desktop** | `~/.config/Claude/claude_desktop_config.json` |\n| **Gemini CLI** | `~/.gemini/settings.json` |\n| **Cursor** | `~/.cursor/mcp.json` |\n| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |\n\nFor **Codex CLI** (TOML format), add to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.mind-mem]\ncommand = \"mind-mem-mcp\"\nargs = []\n\n[mcp_servers.mind-mem.env]\nMIND_MEM_WORKSPACE = \"/path/to/your/workspace\"\n```\n\nFor **Zed**, add to `~/.config/zed/settings.json` under `context_servers`:\n\n```json\n{\n \"context_servers\": {\n \"mind-mem\": {\n \"command\": {\n \"path\": \"mind-mem-mcp\",\n \"args\": [],\n \"env\": {\"MIND_MEM_WORKSPACE\": \"/path/to/your/workspace\"}\n }\n }\n }\n}\n```\n\n### Direct (stdio / HTTP)\n\n```bash\n# stdio transport (default)\nMIND_MEM_WORKSPACE=/path/to/workspace mind-mem-mcp\n\n# HTTP transport (multi-client / remote) — requires MIND_MEM_TOKEN per v3.7.0 fail-closed contract\nMIND_MEM_WORKSPACE=/path/to/workspace MIND_MEM_TOKEN=$(openssl rand -hex 32) \\\n mind-mem-mcp --transport http --host 127.0.0.1 --port 8765\n```\n\n### Resources (read-only)\n\n| URI | Description |\n| ---------------------------- | --------------------------------------------- |\n| `mind-mem://decisions` | Active decisions |\n| `mind-mem://tasks` | All tasks |\n| `mind-mem://entities/{type}` | Entities (projects, people, tools, incidents) |\n| `mind-mem://signals` | Auto-captured signals pending review |\n| `mind-mem://contradictions` | Detected contradictions |\n| `mind-mem://health` | Workspace health summary |\n| `mind-mem://recall/{query}` | BM25 recall search results |\n| `mind-mem://ledger` | Shared fact ledger (multi-agent) |\n\n### Tools (21)\n\n| Tool | Description |\n| --------------------- | -------------------------------------------------------------- |\n| `recall` | Search memory with BM25 (query, limit, active_only) |\n| `propose_update` | Propose a decision/task — writes to SIGNALS.md only |\n| `approve_apply` | Apply a staged proposal (dry_run=True by default) |\n| `rollback_proposal` | Rollback an applied proposal by receipt timestamp |\n| `scan` | Run integrity scan (contradictions, drift, signals) |\n| `list_contradictions` | List contradictions with auto-resolution analysis |\n| `hybrid_search` | Hybrid BM25+Vector search with RRF fusion |\n| `find_similar` | Find blocks similar to a given block |\n| `intent_classify` | Classify query intent (9 types with parameter recommendations) |\n| `index_stats` | Index statistics, MIND kernel availability, block counts |\n| `retrieval_diagnostics` | Pipeline rejection rates, intent histogram, hard negatives |\n| `reindex` | Rebuild FTS5 index (optionally including vectors) |\n| `memory_evolution` | View/trigger A-MEM metadata evolution for a block |\n| `list_mind_kernels` | List available MIND kernel configurations |\n| `get_mind_kernel` | Read a specific MIND kernel configuration as JSON |\n| `category_summary` | Category summaries relevant to a given topic |\n| `prefetch` | Pre-assemble context from recent conversation signals |\n| `delete_memory_item` | Delete a memory block by ID (admin-scope) |\n| `export_memory` | Export workspace as JSONL (user-scope) |\n| `calibration_feedback` | Submit quality feedback for a retrieved block (thumbs up/down) |\n| `calibration_stats` | View per-block and global calibration statistics |\n\n### Token Auth (HTTP)\n\n```bash\nMIND_MEM_TOKEN=your-secret mind-mem-mcp --transport http --port 8765\n```\n\n**As of v3.7.0, HTTP authentication fails CLOSED.** If neither\n`MIND_MEM_TOKEN` nor `MIND_MEM_ADMIN_TOKEN` is set, the server refuses\nto start. For local development you can opt back into the legacy\nbehaviour, but only on a loopback bind:\n\n```bash\nMIND_MEM_ALLOW_UNAUTHENTICATED_LOCALHOST=1 \\\n mind-mem-mcp --transport http --host 127.0.0.1 --port 8765 \\\n --allow-unauthenticated-localhost\n```\n\nThe flag is a no-op if the bind host isn't `127.0.0.1` / `::1` /\n`localhost` — the server still refuses to start. Production\ndeployments should always set a token.\n\n### Safety Guarantees\n\n- **`propose_update` never writes to DECISIONS.md or TASKS.md.** All proposals go to SIGNALS.md.\n- **`approve_apply` defaults to dry_run=True.** Creates a snapshot before applying for rollback.\n- **All resources are read-only.** No MCP client can mutate source of truth through resources.\n- **Namespace-aware.** Multi-agent workspaces scope resources by agent ACL.\n\n---\n\n## Security\n\n### Threat Model\n\n| What we protect | How |\n| --------------------- | -------------------------------------------------------------------- |\n| Memory integrity | 74+ structural checks, ConstraintSignature validation |\n| Accidental overwrites | Proposal-based mutations only (never direct writes) |\n| Rollback safety | Snapshot before every apply, atomic `os.replace()` |\n| Symlink attacks | Symlink detection in restore paths |\n| Path traversal | All paths resolved via `os.path.realpath()`, workspace-relative only |\n\n| What we do NOT protect against | Why |\n| ------------------------------ | -------------------------------------------------------------- |\n| Malicious local user | Single-user CLI tool — filesystem access = data access |\n| Network attacks | No network calls, no listening ports, no telemetry |\n| Encrypted storage | Files are plaintext Markdown — use disk encryption if needed |\n\n### No Network Calls\n\nMIND-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.\n\n---\n\n## Requirements\n\n- **Python 3.10+**\n- **No external packages** — stdlib only for core functionality\n\n### Optional Dependencies\n\n| Package | Purpose | Install |\n| ---------------------------- | ----------------------- | ------------------------------------- |\n| `fastmcp` | MCP server | `pip install mind-mem[mcp]` |\n| `onnxruntime` + `tokenizers` | Local vector embeddings | `pip install mind-mem[embeddings]` |\n| `sentence-transformers` | Cross-encoder reranking | `pip install mind-mem[cross-encoder]` |\n| `ollama` | LLM extraction (local) | `pip install ollama` |\n\n### mind-mem:4b — Purpose-Trained LLM\n\nFor best LLM extraction quality, use **[mind-mem:4b](https://huggingface.co/star-ga/mind-mem-4b)** — a full fine-tune of Qwen3.5-4B on MIND-Mem's 8 extraction tasks (entity extraction, fact extraction, observation compression, contradiction detection, governance analysis, intent classification, axis-aware retrieval, LLM reranking). Empirical on RTX 3080 (Q4_K_M, 2.6GB VRAM): **104 tok/s generation, 1585 tok/s prefill**.\n\n**Ollama (recommended):**\n```bash\n# Download the GGUF from HuggingFace\nwget https://huggingface.co/star-ga/mind-mem-4b/resolve/main/mind-mem-4b-Q4_K_M.gguf\n\n# Create Ollama model\ncat \u003e Modelfile \u003c\u003c 'EOF'\nFROM ./mind-mem-4b-Q4_K_M.gguf\nSYSTEM \"You are mind-mem, a governance-aware memory extraction assistant.\"\nPARAMETER temperature 0.1\nPARAMETER num_ctx 8192\nPARAMETER num_predict 1024\nPARAMETER stop \"\u003c|im_end|\u003e\"\nPARAMETER stop \"\u003c|endoftext|\u003e\"\nEOF\nollama create mind-mem:4b -f Modelfile\n```\n\nThen set in `mind-mem.json`:\n```json\n{\n \"extraction\": {\n \"enabled\": true,\n \"model\": \"mind-mem:4b\",\n \"backend\": \"ollama\"\n }\n}\n```\n\nEmpirical on RTX 3080 (Q4_K_M, 2.6GB VRAM): **104 tok/s generation, 1585 tok/s prefill**.\n\n**Full fine-tune (transformers, no adapter):**\n```python\nfrom transformers import AutoModelForCausalLM, AutoTokenizer\n\nmodel = AutoModelForCausalLM.from_pretrained(\"star-ga/mind-mem-4b\", device_map=\"auto\", torch_dtype=\"bfloat16\")\ntokenizer = AutoTokenizer.from_pretrained(\"star-ga/mind-mem-4b\")\n```\n\n| Resource | Link |\n|----------|------|\n| Model (GGUF + bf16 safetensors) | [star-ga/mind-mem-4b](https://huggingface.co/star-ga/mind-mem-4b) |\n| Base model | Qwen/Qwen3.5-4B |\n| Training | Full fine-tune on Runpod H200 SECURE (141 GB HBM3e), audit-clean v3.10.0 corpus (3,975 examples), bf16, paged-AdamW-8bit, batch 2 × accum 16, max_length 2048, 3 epochs / 375 steps, LR 1.5e-5 cosine + 3% warmup |\n| Eval (v3.10.2-fullft) | **6/6 PASS** — 100% across tool_call (20/20), block_schema (10/10), workflow (5/5), v39_new_tools (13/13), v39_transform_hash (3/3), v39_transport_guard (4/4) |\n\n### Platform Support\n\n| Platform | Status | Notes |\n| ---------------------- | ----------- | --------------------------------------- |\n| Linux | Full | Primary target |\n| macOS | Full | POSIX-compliant shell scripts |\n| Windows (WSL/Git Bash) | Full | Use WSL2 or Git Bash for shell hooks |\n| Windows (native) | Python only | Use `validate_py.py`; hooks require WSL |\n\n---\n\n## Troubleshooting\n\n| Problem | Solution |\n| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| `validate.sh` says \"No mind-mem.json found\" | Run in a workspace, not the repo root. Run `init_workspace.py` first. |\n| `recall` returns no results | Workspace is empty. Add decisions/tasks first. |\n| `capture` says \"no daily log\" | No `memory/YYYY-MM-DD.md` for today. Write something first. |\n| `intel_scan` finds 0 contradictions | Good — no conflicting decisions. |\n| Tests fail on Windows | Use `validate_py.py` instead of `validate.sh`. Hooks require WSL. |\n| MIND kernel not loading | Compile with `mindc mind/*.mind --emit=shared -o lib/libmindmem.so`. Or ignore — pure Python works identically. |\n\n### FAQ\n\n**No results from recall?**\nCheck that the workspace path is correct and points to an initialized workspace\ncontaining decisions, tasks, or entities. If the FTS5 index is stale or missing,\nrun the `reindex` MCP tool to rebuild it.\n\n**MCP connection failed?**\nVerify that `fastmcp` is installed (`pip install fastmcp`). Check the transport\nconfiguration in your client's MCP config (stdio vs HTTP). Ensure the\n`MIND_MEM_WORKSPACE` environment variable points to a valid workspace directory.\n\n**MIND kernels not loading?**\nRun `bash src/mind_mem/build.sh` to compile the MIND source files (requires `mindc`).\nIf the MIND compiler is not available, MIND-Mem automatically uses the pure Python\nfallback with identical results.\n\n**Index corrupt?**\nRun the `reindex` MCP tool, or from the command line:\n`python3 -m mind_mem.sqlite_index --rebuild --workspace /path/to/workspace`.\nThis drops and recreates the FTS5 index from all workspace files.\n\n---\n\n## Specification\n\nFor the formal grammar, invariant rules, state machine, and atomicity guarantees, see **[SPEC.md](SPEC.md)**.\n\n---\n\n## Contributing\n\nContributions welcome. Please open an issue first to discuss what you'd like to change.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n---\n\n## License\n\n[Apache 2.0](LICENSE) — Copyright 2026 STARGA Inc and contributors.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstar-ga%2Fmind-mem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstar-ga%2Fmind-mem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstar-ga%2Fmind-mem/lists"}