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

Compiled Truth Pages

Per-entity knowledge compilation: current-best-understanding on top, timestamped evidence trail below. Contradiction detection across evidence entries with automatic flagging. Entities accumulate knowledge from all sessions — each new evidence entry is checked against existing facts.

Install in 3 commands

pip install mind-mem
mm install-all --force      # auto-wires every detected AI CLI
mm install-model            # downloads mind-mem-4b GGUF + imports to Ollama

Full options + Postgres setup + troubleshooting: docs/install-guide.md

python3 benchmarks/locomo_harness.py python3 benchmarks/longmemeval_harness.py

One-line install (recommended)

pipx install "mind-mem[mcp]"
mind-mem-mcp --help          # smoke-test

pipx keeps MIND-Mem in its own venv, exposes the mind-mem-mcp console script on PATH, and avoids polluting your system Python. If you don't have pipx, pip install --user "mind-mem[mcp]" works too.

Then wire it into every AI coding client on your machine:

git clone https://github.com/star-ga/mind-mem.git
cd mind-mem
./install.sh --all --no-install   # Already installed via pipx, just wire clients

Or do both in one shot (the installer will auto-pick pipx if available, else fall back to pip):

git clone https://github.com/star-ga/mind-mem.git
cd mind-mem
./install.sh --all

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

Selective install:

./install.sh --claude-code --codex --gemini         # Only specific clients
./install.sh --all --workspace ~/my-project/memory  # Custom workspace path

Uninstall:

./uninstall.sh          # Remove from all clients (keeps workspace data)
./uninstall.sh --purge  # Remove everything including workspace data

Manual Setup

For manual or per-project setup:

1. Clone into your project

cd /path/to/your/project
git clone https://github.com/star-ga/mind-mem.git .mind-mem

2. Initialize workspace

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

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

3. Validate

```bash bash .mind-mem/src/mind_mem/validate.sh .

LLM-Guided Multi-Query Expansion

Generates semantically diverse query reformulations before search — synonym expansion, specificity shifts, temporal rephrasing, and negation variants. Combines all reformulated queries with Reciprocal Rank Fusion for broader recall without sacrificing precision. Runs locally with zero API calls.

LLM-Guided Smart Chunking

Content-aware chunking that splits at semantic boundaries (headers, paragraph breaks, list items, code blocks) instead of fixed character counts. Produces variable-size chunks with overlap for continuity. Supports markdown, code, and prose with format-specific splitting rules.

Production usage at STARGA

MIND-Mem is the daily-driver memory layer for STARGA's six active projects: mind, mind-runtime, mindlang.dev, mind-inference, mind-fleet, arch-mind. First-party, verifiable in our own commit history.

Quick Start

30-Second Demo

pip install mind-mem
mind-mem-init ~/my-workspace        # Create workspace
mind-mem-recall -q "API decisions" --workspace ~/my-workspace  # Hybrid BM25F search
mind-mem-scan ~/my-workspace        # Detect drift & contradictions

Output:

[1.204] D-20260215-001 (decision) — Use async/await for all API endpoints
        decisions/DECISIONS.md:11
[1.094] D-20260210-003 (decision) — REST over GraphQL for public API
        decisions/DECISIONS.md:20

<sub>Current release: v4.0.15 — Full per-release notes (issues closed, CI run ids, job counts) live in <a href="./CHANGELOG.md">CHANGELOG.md</a>.</sub>

Optional Cross-Encoder

Drop-in ms-marco-MiniLM-L-6-v2 cross-encoder (80MB). Blends 0.6 CE + 0.4 original score. Falls back gracefully when unavailable. Enabled via config.

MIND Kernels (Optional, Native Speed — forward-looking)

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

Vector Recall (optional)

Pluggable embedding backend — local ONNX (all-MiniLM-L6-v2, no server needed) or cloud (Pinecone). Falls back to BM25 when unavailable.

Integrations are the substrate working

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

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

Native MCP integration with 17 AI development tools

pip install mind-mem
mm install-all

mm install-all auto-detects every supported client on your machine and writes the appropriate config file for each. MIND-Mem speaks the Model Context Protocol — any MCP-compatible client connects with one command.

How It Compares

Quick Comparison