release: v3.10.2 — canonical Memory Protocol snippet on install-all

mm install-all now writes the full memory-protocol system-prompt
into every detected CLI's instructions file (AGENTS.md, .cursorrules,
.windsurfrules, .clinerules, .roo/system-prompt.md) instead of the
previous 1-line stub.

Closes the gap audit found 2026-05-08: protocol-level MCP wiring is
necessary but not sufficient. Without an explicit instruction the
LLM in each CLI does not reliably call mcp__mind-mem__recall before
answering, producing hallucinations on memory-grounded questions.

Single source of truth: MEMORY_PROTOCOL_SNIPPET in
hook_installer.py, mirrored at docs/agent-memory-protocol.md.

Author: STARGA Inc

ANATOMY.md

@@ -5,8 +5,8 @@
 > Re-generate with: `anatomy .`
 
 **Project:** `mind-mem`
-**Files:** 738 | **Est. tokens:** ~1,507,695
-**Generated:** 2026-05-08 02:28 UTC
+**Files:** 739 | **Est. tokens:** ~1,508,637
+**Generated:** 2026-05-09 00:39 UTC
 
 ## Token Budget Guide
 
@@ -30,7 +30,7 @@
 | `deploy/docker/` | 1 | ~495 |
 | `deploy/edge/` | 2 | ~1,149 |
 | `deploy/grafana/` | 1 | ~1,145 |
-| `docs/` | 64 | ~104,404 |
+| `docs/` | 65 | ~105,000 |
 | `docs/adr/` | 2 | ~521 |
 | `docs/design/` | 2 | ~2,416 |
 | `docs/security-baselines/` | 1 | ~18,974 |
@@ -56,7 +56,7 @@
 | `skills/integrity-scan/` | 1 | ~376 |
 | `skills/memory-recall/` | 1 | ~549 |
 | `src/` | 1 | ~280 |
-| `src/mind_mem/` | 155 | ~535,862 |
+| `src/mind_mem/` | 155 | ~536,208 |
 | `src/mind_mem/api/` | 5 | ~15,751 |
 | `src/mind_mem/mcp/` | 3 | ~3,960 |
 | `src/mind_mem/mcp/infra/` | 8 | ~6,924 |
@@ -170,6 +170,7 @@
 - `002-bm25f-scoring.md` (~205 tok, medium) — ADR-002: BM25F as Primary Scoring Algorithm
 ### `docs/`
 
+- `agent-memory-protocol.md` (~596 tok, large) — Agent Memory Protocol — canonical system-prompt snippet
 - `api-reference.md` (~1477 tok, large) — API Reference
 - `architecture.md` (~1936 tok, huge) — Architecture
 - `audit_response.md` (~956 tok, large) — MIND-Mem — response to the 2026-05-02 ecosystem audit
@@ -457,7 +458,7 @@
 - `governance_raft.py` (~2208 tok, huge) — Raft-style consensus wrapper for governance writes (v4.0 prep).
 - `graph_recall.py` (~1907 tok, huge) — Multi-hop graph traversal for recall (v3.3.0 Tier 1 #2).
 - `hash_chain_v2.py` (~5512 tok, huge) — # Copyright 2026 STARGA, Inc.
-- `hook_installer.py` (~9883 tok, huge) — # Copyright 2026 STARGA, Inc.
+- `hook_installer.py` (~10229 tok, huge) — # Copyright 2026 STARGA, Inc.
 - `http_transport.py` (~5592 tok, huge) — HTTP transport adapter for mind-mem (v3.9.0 candidate).
 - `hybrid_recall.py` (~8896 tok, huge) — mind-mem Hybrid Recall -- BM25 + Vector + RRF fusion.
 - `inbox.py` (~3595 tok, huge) — Inbox folder ingestion — `mm inbox-watch` (v3.9.0 candidate).

CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to MIND-Mem are documented in this file.
 
+## v3.10.2 — Canonical Memory Protocol injected on `mm install-all`
+
+Released 2026-05-08. Closes a gap discovered during a sibling product
+audit: every CLI that `mm install-all` wires at the protocol level
+(MCP entry, hooks) now also receives the **canonical Memory Protocol
+system-prompt snippet** in its instructions file. Wiring without
+instruction was producing hallucinations because the LLM in each CLI
+wasn't told to actually call `mcp__mind-mem__recall` before answering.
+
+### Added
+- `docs/agent-memory-protocol.md` — canonical text of the snippet,
+  also rendered in this CHANGELOG section for searchability.
+- `MEMORY_PROTOCOL_SNIPPET` constant in `hook_installer.py`. Single
+  source of truth.
+
+### Changed
+- `AGENT_REGISTRY` `content_tmpl` values for **codex / vibe / cursor /
+  windsurf / cline / roo** now point at `MEMORY_PROTOCOL_SNIPPET`
+  (replacing per-agent 1-line stubs). Re-running `mm install-all
+  --force` upgrades the user's existing `AGENTS.md` /
+  `.cursorrules` / `.windsurfrules` / `.clinerules` /
+  `.roo/system-prompt.md` files in place.
+- Aider (yaml `auto-config`) and claude-code (json hooks) keep their
+  format-specific templates — they're not text system prompts.
+
+### Why
+A 9-LLM consensus product based on OpenClaw was hallucinating on
+memory-grounded questions despite mind-mem's Postgres backend
+holding the right answers. Audit traced this to MCP wiring being
+present but the agent system-prompt only saying *"run `mm context`
+before responding"* — a 13-word stub. The new snippet is the full
+recall / propose_update / hybrid_search / hallucination-guardrail
+protocol that has been working for Claude Code via its `CLAUDE.md`.
+Anyone who `pip install mind-mem && mm install-all --force` now
+gets the same protocol on every supported CLI.
+
 ## v3.10.1 — Vibe (Mistral CLI) MCP auto-wire
 
 Released 2026-05-07. Adds the long-standing TODO Vibe MCP adapter so

docs/agent-memory-protocol.md

@@ -0,0 +1,59 @@
+# Agent Memory Protocol — canonical system-prompt snippet
+
+This is the **canonical** memory-protocol text that `mm install-all`
+writes into each detected CLI's system-prompt file (`AGENTS.md`,
+`GEMINI.md`, `.cursorrules`, `.windsurfrules`, `.clinerules`,
+`.roo/system-prompt.md`, `.aider.conf.yml`, etc.).
+
+If you're operating a CLI that already has its own system prompt
+(`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, …), append this section. If
+you're starting fresh, this is the entire prompt.
+
+The hook installer (`src/mind_mem/hook_installer.py`,
+`AGENT_REGISTRY`) reads `MEMORY_PROTOCOL_SNIPPET` from
+`hook_installer/memory_protocol.py` so a single canonical edit
+propagates to every wired agent.
+
+---
+
+## Memory Protocol (mind-mem MCP — USE CONSTANTLY)
+
+The mind-mem MCP server is wired into this CLI. Before answering ANY
+question that touches prior work, decisions, project state, people,
+companies, technical choices, or "remember when..." — call mind-mem
+first. The governed blocks in mind-mem's Postgres backend are the
+source of truth.
+
+### Always recall before answering
+Run `mcp__mind-mem__recall` (or `mm recall "$query"` via bash) with
+relevant keywords FIRST. If recall returns results, cite them. If
+not, say "no record found" — do not guess.
+
+### Always propose_update after learning new facts
+When the user shares a new decision, project status, relationship,
+contact, or technical finding worth preserving — run
+`mcp__mind-mem__propose_update` to store it. Don't wait to be asked.
+
+### Use hybrid_search for complex queries
+For multi-faceted questions, use `mcp__mind-mem__hybrid_search`
+(BM25 + vector + RRF fusion) for best recall.
+
+### Hallucination guardrail
+If you find yourself writing about prior projects, repos, or
+decisions without having called recall in this session, you are
+about to hallucinate. Stop and call recall first.
+
+---
+
+## Why this exists
+
+Audit on 2026-05-08 of a sibling product (a 9-LLM consensus engine
+also based on OpenClaw) showed it had its own internal memory plugin
+and **zero call paths to mind-mem MCP**. The result was repeated
+hallucinations on memory-grounded questions. Adding this prompt block
+into each CLI's system-prompt closes the gap by *instructing* the LLM
+to use the MCP tools that `mm install-all` wires at the protocol
+level.
+
+Wiring without instruction is not enough. This file is the
+instruction half.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mind-mem"
-version = "3.10.1"
+version = "3.10.2"
 description = "Drop-in memory for Claude Code, OpenClaw, and any MCP-compatible agent."
 readme = "README.md"
 license = { text = "Apache-2.0" }

src/mind_mem/__init__.py

@@ -43,7 +43,7 @@
 )
 from .storage import get_block_store
 
-__version__ = "3.10.1"
+__version__ = "3.10.2"
 
 # Best-effort import-time integrity check. Fails open unless
 # MIND_MEM_INTEGRITY=strict, so editable installs and source checkouts

src/mind_mem/hook_installer.py

@@ -172,6 +172,44 @@ def observation_to_block(
 
 _MM_MARKER = "# mind-mem"
 
+# Canonical Memory Protocol snippet — written into every detected CLI's
+# system-prompt file by ``mm install-all``. The companion document is
+# ``docs/agent-memory-protocol.md``; both must be kept in sync.
+#
+# Wiring at the protocol level (MCP entries) is necessary but not
+# sufficient — without an explicit instruction the LLM in each CLI does
+# not reliably call the MCP tools. This snippet is the instruction half.
+MEMORY_PROTOCOL_SNIPPET = (
+    f"{_MM_MARKER}: agent instructions (auto-written by `mm install-all`)\n"
+    "\n"
+    "## Memory Protocol (mind-mem MCP — USE CONSTANTLY)\n"
+    "\n"
+    "The mind-mem MCP server is wired into this CLI. Before answering ANY\n"
+    "question that touches prior work, decisions, project state, people,\n"
+    "companies, technical choices, or \"remember when…\" — call mind-mem\n"
+    "first. The governed blocks in mind-mem's Postgres backend are the\n"
+    "source of truth.\n"
+    "\n"
+    "### Always recall before answering\n"
+    "Run `mcp__mind-mem__recall` (or `mm recall \"$query\"` via bash) with\n"
+    "relevant keywords FIRST. If recall returns results, cite them. If\n"
+    "not, say \"no record found\" — do not guess.\n"
+    "\n"
+    "### Always propose_update after learning new facts\n"
+    "When the user shares a new decision, project status, relationship,\n"
+    "contact, or technical finding worth preserving — run\n"
+    "`mcp__mind-mem__propose_update` to store it. Don't wait to be asked.\n"
+    "\n"
+    "### Use hybrid_search for complex queries\n"
+    "For multi-faceted questions, use `mcp__mind-mem__hybrid_search`\n"
+    "(BM25 + vector + RRF fusion) for best recall.\n"
+    "\n"
+    "### Hallucination guardrail\n"
+    "If you find yourself writing about prior projects, repos, or\n"
+    "decisions without having called recall in this session, you are\n"
+    "about to hallucinate. Stop and call recall first.\n"
+)
+
 
 # ---------------------------------------------------------------------------
 # MCP server command — every client that supports MCP points at this.
@@ -605,9 +643,7 @@ def _merge_mcp_vibe_toml(existing_text: str, ws: str, srv: dict) -> tuple[str, b
         description="OpenAI Codex CLI",
         config_fmt="text-block",
         path_tmpl="{ws}/AGENTS.md",
-        content_tmpl=(
-            f'{_MM_MARKER}: agent instructions (auto-written)\n\nBefore every response, run `mm context "$QUERY"` and prepend the output.\n'
-        ),
+        content_tmpl=MEMORY_PROTOCOL_SNIPPET,
         detect_binaries=("codex",),
         mcp_fmt="mcp-toml-codex",
         mcp_path_tmpl="{home}/.codex/config.toml",
@@ -617,9 +653,7 @@ def _merge_mcp_vibe_toml(existing_text: str, ws: str, srv: dict) -> tuple[str, b
         description="Mistral Vibe CLI",
         config_fmt="text-block",
         path_tmpl="{ws}/AGENTS.md",
-        content_tmpl=(
-            f'{_MM_MARKER}: agent instructions (auto-written)\n\nBefore every response, run `mm context "$QUERY"` and prepend the output.\n'
-        ),
+        content_tmpl=MEMORY_PROTOCOL_SNIPPET,
         detect_paths=("{home}/.vibe",),
         detect_binaries=("vibe",),
         mcp_fmt="mcp-toml-vibe",
@@ -640,7 +674,7 @@ def _merge_mcp_vibe_toml(existing_text: str, ws: str, srv: dict) -> tuple[str, b
         description="Cursor editor",
         config_fmt="text-block",
         path_tmpl="{ws}/.cursorrules",
-        content_tmpl=(f"{_MM_MARKER}\nmind-mem workspace: {{ws}}\nUse `mm inject --agent cursor` before answering.\n"),
+        content_tmpl=MEMORY_PROTOCOL_SNIPPET,
         detect_paths=(
             "{home}/.cursor",
             "{home}/Library/Application Support/Cursor",
@@ -655,7 +689,7 @@ def _merge_mcp_vibe_toml(existing_text: str, ws: str, srv: dict) -> tuple[str, b
         description="Windsurf editor (Codeium)",
         config_fmt="text-block",
         path_tmpl="{ws}/.windsurfrules",
-        content_tmpl=(f"{_MM_MARKER}\nworkspace: {{ws}}\nprefer `mm inject --agent windsurf`.\n"),
+        content_tmpl=MEMORY_PROTOCOL_SNIPPET,
         detect_paths=(
             "{home}/.codeium/windsurf",
             "{home}/.windsurf",
@@ -711,7 +745,7 @@ def _merge_mcp_vibe_toml(existing_text: str, ws: str, srv: dict) -> tuple[str, b
         description="Cline (VS Code extension)",
         config_fmt="text-block",
         path_tmpl="{ws}/.clinerules",
-        content_tmpl=(f"{_MM_MARKER}\nmind-mem workspace: {{ws}}\nRun `mm inject --agent cline` before tool use.\n"),
+        content_tmpl=MEMORY_PROTOCOL_SNIPPET,
         detect_paths=(
             "{home}/.vscode/extensions",
             "{home}/.vscode-server/extensions",
@@ -724,7 +758,7 @@ def _merge_mcp_vibe_toml(existing_text: str, ws: str, srv: dict) -> tuple[str, b
         description="Roo Code (VS Code fork / extension)",
         config_fmt="text-block",
         path_tmpl="{ws}/.roo/system-prompt.md",
-        content_tmpl=(f"{_MM_MARKER}\nmind-mem workspace: {{ws}}\nUse `mm inject --agent roo` before answering.\n"),
+        content_tmpl=MEMORY_PROTOCOL_SNIPPET,
         detect_paths=(
             "{home}/.roo",
             "{home}/.vscode/extensions",