musememory 2.3.0 → 3.0.1

package/README.md

@@ -1,7 +1,14 @@
-# <h1> 🧠 Muse Memory</h1>
-
 <div align="center">
 
+<a href="#what-muse-memory-does">
+  <img src="./apps/website/public/brand/readme-banner.png" alt="Muse Memory — persistent memory for AI coding agents that verifies itself" width="100%" />
+</a>
+
+<br />
+<br />
+
+# 🧠 Muse Memory
+
 ![GitHub Release](https://img.shields.io/github/v/release/harshsinghmp/musememory?style=for-the-badge&logo=github&color=2563EB)
 ![NPM Version](https://img.shields.io/npm/v/musememory?style=for-the-badge&logo=npm&color=CB3837)
 ![Bun](https://img.shields.io/badge/Bun-v1.4.0_(Latest)-black?style=for-the-badge&logo=bun)
@@ -13,70 +20,125 @@
 ![AST Graph](https://img.shields.io/badge/AST-CodeGraph_%26_Graphify-orange?style=for-the-badge&logo=diagram-project&logoColor=white)
 ![Architecture](https://img.shields.io/badge/Storage-Zero--Daemon_%2F_Local--First-0D9488?style=for-the-badge)
 
-![CI Tests](https://img.shields.io/badge/Tests-502%20Passed-brightgreen?style=for-the-badge&logo=checkmarx)
+![CI Tests](https://img.shields.io/badge/Tests-1335%20Passed-brightgreen?style=for-the-badge&logo=checkmarx)
 ![Security](https://img.shields.io/badge/Security-Vibeguard_Zero--Leak-DC2626?style=for-the-badge&logo=shield)
-![Agent Coverage](https://img.shields.io/badge/Agents-80+_Supported-4F46E5?style=for-the-badge&logo=openai)
+![Agent Coverage](https://img.shields.io/badge/Agents-52_Verified-4F46E5?style=for-the-badge&logo=openai)
 ![License](https://img.shields.io/badge/License-MIT-9333EA?style=for-the-badge)
 
-**Autonomous, Self-Organizing Cognitive Memory System for AI Agents & Agency Networks**
+**Persistent, local-first memory for AI agents and the projects they work on.**
+
+[Visit the live site](https://harshsinghmp.github.io/musememory/) · [Docs](https://harshsinghmp.github.io/musememory/docs) · [Comparison](https://harshsinghmp.github.io/musememory/compare) · [Agent reference](https://github.com/harshsinghmp/musememory/blob/main/docs/agent-reference.md)
 
 </div>
 
 ---
 
-## 🚀 What's New
-
-### v2.3.0
-- **Autonomous Memory Optimizer (`memory optimize`)**: High-precision noise and junk pruning engine with zero-daemon auto-cadence (every 7 days or after 48h idle) and SQLite WAL defragmentation (`VACUUM;` + `PRAGMA optimize;`).
-- **Dashboard "⚡ Optimize" Trigger**: Live visual optimization controls directly inside the Web Observability Studio (`memory ui` / `memory studio`) with real-time feedback on items pruned and bytes reclaimed.
-- **Concurrent Multi-Agent Workstream Tracking**: Live coordination table in `CURRENT.md` enabling multiple agents across parallel chats to monitor active tasks and target scopes without collisions.
-- **Clean Operational Guidelines**: Curated single-pane executive summary for humans and strict grounding/concurrency rules for AI agents.
-
-### v2.2.0
-- **Unified Code & Memory Impact Analysis**: Pre-flight blast radius analysis evaluating AST callers, test suites, governing ADRs, negative warnings, and risk levels (`memory code-impact` / `muse_code_impact`).
-- **PR & Change Context Generator**: Automatically turns git diffs into rich, memory-grounded GitHub PR descriptions linking touched anchors and active constraints (`memory pr-context` / `muse_pr_context`).
-- **Interactive Code Anchor Reconciler**: Audits and repairs code anchors across memories, pruning dead references and updating structural hashes (`memory reconcile` / `muse_reconcile_anchors`).
-- **Latency & Quality Telemetry Suite**: Benchmarks microsecond hot caches, FTS5 BM25 search, knapsack token packing, and ROI in a clean ASCII scoreboard (`memory benchmark`).
-- **Expanded Agent Skills**: Shipped turnkey skills for `muse-health`, `muse-drift`, `muse-why`, `muse-sync`, and `muse-mesh`.
-
-### v2.1.0
-- **Cross-Agent Knowledge Sync & P2P Gossip Protocol**: Sealed portable `SyncPacket` engine with SHA-256 integrity and zero-daemon shared filesystem gossip pool (`memory sync` / `muse_sync_*`).
-- **Web Observability Studio**: Embedded visual dashboard (`memory studio` / `memory ui`) with interactive 5-pillar health, ADR registry, code drift inspector, and sync controls.
-- **Monorepo & Multi-Repo Mesh**: Automatic workspace discovery (pnpm, npm, bun, lerna) with cross-project memory queries and shared constraint propagation (`memory mesh` / `muse_mesh_*`).
-
-### v2.0.0
-- **5-Pillar Project Health Gate**: Architectural health gate evaluating store integrity, code anchors, doc-code alignment, negative sentry, and technical debt (`memory health` / `muse_health`).
-- **Cognitive "Why" Reasoner**: Reconstructs historical code evolution, bug workarounds, and trade-offs before refactoring (`muse_why`).
-- **Living Architecture Decision Records (ADRs)**: Queryable ADRs with options, consequences, native code anchors, and supersession lineage (`memory adr` / `memory_adr_record`).
-- **Doc ⟷ Code Drift Engine**: Continuously audits documentation against AST code implementations across 6 drift states (`memory drift` / `memory_drift_audit`).
-- **Unified Context Orchestrator & MCP Profiles**: Single-call fused context injection with knapsack token packing (`muse_context`) and task-specific tool profiles.
-- **Native Structural Code Anchors**: Line-independent structural SHA-256 hashing for files, symbols, and routes.
-- **Scoped Promotion & Archival Lifecycle**: 3-tier promotion ladder (`local` → `project` → `global`) and cold/dormant/archived storage tiers.
+## Start here (60 seconds)
+
+```bash
+npx musememory connect     # detect your coding agents and wire the memory server into each
+npx musememory doctor      # confirm the store, schemas and agent wiring are healthy
+```
+
+That is the whole setup. No account, no API key, no config file, no background
+daemon — the store is two plain directories (`.memory/` in your project,
+`~/.memory/` globally) that you can read, diff and commit.
+
+Then, in any session with a connected agent:
+
+```bash
+memory context --query "how does auth work" --budget 2000
+```
+
+**What you get:** a memory that survives the session, is checked against your
+real code before it is stored, and is withheld at recall if the code it cites
+has since changed.
+
+| | |
+| :--- | :--- |
+| **Install** | `npx musememory connect` |
+| **Requires** | Node.js ≥ 18 or Bun ≥ 1.2 — nothing else |
+| **Storage** | `.memory/` (project) + `~/.memory/` (global) |
+| **Data leaves your machine** | Never |
+| **Cost** | Free, MIT, no telemetry |
+
+---
+
+## What's new
+
+### v3.0.1 — correctness release
+
+Five defects found by a cross-file invariant audit, and a guarantee that the
+numbers on this page are the numbers the code produces.
+
+- **Prompt-injection channel closed**: `CURRENT.md` was written with the raw,
+  un-stripped constraint text while the stored memory was sanitised. Because
+  `CURRENT.md` is replayed into every later prompt, one captured constraint
+  could reach every future session. Sanitisation now happens at the sink.
+- **Bi-temporal queries answered from the wrong snapshot**: the context cache
+  key omitted `as_of`, so "what did we believe in Q1?" could return today's
+  answer from a 30-second-old cache entry.
+- **Access counter never accumulated**: every read reset it to its baseline,
+  which silently disarmed the access-frequency ranking axis.
+- **Store could fail its own schema validator**: entries that failed embedding
+  were permanently reported as corrupt.
+- **Tier token budget was declared but never enforced**: 327 tokens against a
+  200-token budget.
+- **Every published number is now generated from the source** and checked by a
+  test, so the site can no longer advertise a figure the code does not produce.
+
+### v3.0.0 — feature release
+
+Closed-loop failure attribution, trajectory fix-pair mining, HOT.md compounding, and LangMem logarithmic frequency ranking.
+
+#### New capabilities
+- Scoped failure attribution matching code anchors with decaying strike counters ([#313](https://github.com/harshsinghmp/musememory/pull/313))
+- Trajectory fix-pair mining discovering negative lessons from agent error sequences ([#144](https://github.com/harshsinghmp/musememory/pull/144))
+- Active working set compounding and candidate scoring directly from HOT.md ([#314](https://github.com/harshsinghmp/musememory/pull/314))
+- Multi-channel knowledge distillation router across system, content, and health ([#324](https://github.com/harshsinghmp/musememory/pull/324))
+- Pre-mutation 30-snapshot rolling ring buffer for zero-daemon recovery ([#177](https://github.com/harshsinghmp/musememory/pull/177))
+
+#### Bug fixes
+- In-lock mutation safety guards preventing bulk deletion and semantic erosion ([#50](https://github.com/harshsinghmp/musememory/pull/50))
+- Strict CodeAnchor field alignment and dispute tracking type safety ([#325](https://github.com/harshsinghmp/musememory/pull/325))
+
+#### Improvements
+- LangMem logarithmic frequency rank curve with 2x application weighting ([#315](https://github.com/harshsinghmp/musememory/pull/315))
+- Diff-preserving CURRENT.md checkpoint merge semantics for agent handoffs ([#324](https://github.com/harshsinghmp/musememory/pull/324))
+- Constitutional immunity defending non-negotiable rules against strike decay ([#313](https://github.com/harshsinghmp/musememory/pull/313))
+
+*For earlier releases, see the [Changelog](./CHANGELOG.md) or [GitHub Releases](https://github.com/harshsinghmp/musememory/releases).*
 
 ---
 
 ## 📑 Table of Contents
 
-- [🚀 What's New](#-whats-new)
-- [💡 What is Muse Memory? (TL;DR)](#-what-is-muse-memory-tldr)
-- [✨ Key Feature Highlights](#-key-feature-highlights)
-- [⚡ Quick Start & Installation](#-quick-start--installation)
-- [🔄 Upgrading & Self-Healing Maintenance](#-upgrading--self-healing-maintenance)
-- [🧠 Shipped Agent Skills (`.agents/skills/`)](#-shipped-agent-skills-agentsskills)
-- [👤 5 Role Archetypes (`USER.md`)](#-5-zero-fingerprint-role-archetypes-usermd)
-- [🔌 Full CLI Command Matrix](#-full-cli-command-matrix)
-- [🛡️ Vibeguard Zero-Leakage Protocol](#️-vibeguard-zero-leakage-protocol)
-- [🧪 Testing & Verification](#-testing--verification)
-- [🔮 Sprint & Roadmap Board](#-sprint--roadmap-board)
+- [Start here (60 seconds)](#start-here-60-seconds)
+- [What's new](#whats-new)
+- [What Muse Memory does](#what-muse-memory-does)
+- [How it works](#how-it-works)
+- [Key capabilities](#key-capabilities)
+- [Where your memory lives](#where-your-memory-lives)
+- [📖 Documentation map](#-documentation-map)
+- [🔄 Complete lifecycle](#-complete-lifecycle-install--verify--connect--uninstall)
+- [🔄 Upgrading & self-healing](#-upgrading--self-healing-maintenance)
+- [👥 Team & multi-member setup](#-team--multi-member-setup)
+- [🏛️ System capabilities & architecture](#-system-capabilities--architecture)
+- [🌐 Cognitive Studio dashboard](#-cognitive-studio-dashboard-memory-ui--memory-studio)
+- [🔌 CLI & MCP reference](#-cli--mcp-reference)
+- [🧠 Shipped agent skills](#-shipped-agent-skills)
+- [👤 5 role archetypes](#-5-role-archetypes-usermd)
+- [🧪 Testing & verification](#-testing--verification)
+- [🔮 Roadmap](#-roadmap)
 - [📜 License](#-license)
 
 ---
 
-## 💡 What is Muse Memory? (TL;DR)
+## What Muse Memory does
 
-Most AI chatbots and coding assistants have **"goldfish memory"**: every time you close a session, switch tasks, or start a new prompt, they forget your project invariants, coding habits, and the hard-fought bug workarounds you solved yesterday.
+AI agents lose project context when a session ends. Muse Memory keeps that context on your machine, where your tools can retrieve it during the next task.
 
-**Muse Memory gives your AI assistants a persistent, self-organizing cognitive notebook directly on your machine.**
+Store working constraints, decisions, handoffs, and verified facts in one local memory layer. SQLite handles retrieval, while readable Markdown and YAML files keep the important context inspectable in Git.
 
 ```
 ┌─────────────────────────────────────────────────────────────────────────────┐
@@ -97,7 +159,7 @@ Most AI chatbots and coding assistants have **"goldfish memory"**: every time yo
 │ └──────────────────────┘ └──────────────────────┘ └───────────────────────┘ │
 │ ┌──────────────────────┐ ┌──────────────────────┐ ┌───────────────────────┐ │
 │ │ Vibeguard Credential │ │ Dynamic Code Anchors │ │ Universal Migrator    │ │
-│ │    Secret Defense    │ │ & Structural Hashes  │ │     (29 Engines)      │ │
+│ │    Secret Defense    │ │ & Structural Hashes  │ │     (30 Engines)      │ │
 │ └──────────────────────┘ └──────────────────────┘ └───────────────────────┘ │
 └──────────────────────────────────────┬──────────────────────────────────────┘
                                        │ Atomic SQLite & File I/O
@@ -120,28 +182,67 @@ Most AI chatbots and coding assistants have **"goldfish memory"**: every time yo
 
 ---
 
-## ✨ Key Feature Highlights
+## How it works
+
+Three steps, on a loop:
+
+1. **Remember it** — when your assistant makes a decision or fixes a bug, Muse
+   saves a short note about what changed and why.
+2. **Check it** — before the note is stored, Muse confirms the file or function
+   it mentions actually exists. Citations are structural fingerprints, not line
+   numbers, so a refactor does not silently break the note.
+3. **Hand it back** — next time you start work, Muse returns the notes that fit
+   the task, sized to your token budget, not the whole archive.
+
+If a saved fact no longer matches your code, Muse leaves it out and says so,
+rather than serving it as if it were still true.
+
+---
+
+## Key capabilities
 
 - 👤 **Persona & Style Grounding (`USER.md`)**: Configures your role (`developer`, `designer`, `marketer`, `casual`, `custom`) and communication preferences so AI models write code that matches your style.
 - 📐 **Real-Time Active Constraints (`CURRENT.md`)**: Bi-temporal working constraints and invariant tracking synchronized on every mutation to eliminate amnesia during task handoffs.
 - 💾 **SQLite Primary + Dual-Persisted YAML Mirror**: Sub-millisecond queries via SQLite with transparent human-readable `.yaml` files in `.memory/memories/` for seamless Git diffs.
 - ⚖️ **Token Knapsack Retrieval**: Multi-factor scoring (applicability, verification bonus, AST graph overlap, time decay, due date urgency) tightly packed under prompt token ceilings.
+- 🧭 **Optional Local Semantic Recall (`memory embed`)**: Point `retrieval.embedderUrl` at any OpenAI-compatible `/v1/embeddings` endpoint (llama.cpp server, Ollama, or hosted) to add a semantic cosine dimension to ranking. Embeddings are cached as float32 blobs inside SQLite, so nothing changes and no network call happens until you configure an endpoint.
 - 🌐 **Pluggable AST CodeGraph & Symbol Indexing**: Native CodeGraph & Graphify integration that indexes codebase AST symbols, auto-tags memories, and awards graph overlap bonuses.
 - 🌳 **Hierarchical Tree Retrieval & Progressive Disclosure**: Sharded tree partitions with 3-tier progressive disclosure (`L1` abstracts, `L2` summaries, `L3` full context) for massive knowledge bases.
 - 📚 **Obsidian Markdown Wiki & Entity Graph Compiler**: Dual-persistence knowledge compounding compiling linked Markdown pages (`wiki/concepts/`, `wiki/entities/`) with bidirectional `[[wikilinks]]`.
 - 🛡️ **Vibeguard Zero-Leakage Secret Scanner**: Regex-powered memory defense intercepting and rejecting API keys, AWS credentials, private keys, database URIs, and passwords before writes.
-- 🔌 **Zero-Permission Auto-Wiring (80+ Agents)**: Automatically detects and wires Claude Code, Cursor, Antigravity, Windsurf, OpenCode, Codex, Gemini CLI, Hermes, etc.
-- 🔄 **Universal Memory Migrator (29 Engines)**: One-click migration from Letta, Mem0, Supermemory, Cognee, Beads, Mnemosyne, GBrain, and more with state preservation.
+- 🔌 **Zero-Permission Auto-Wiring (52 Agents)**: Automatically detects and wires Claude Code, Cursor, Antigravity, Windsurf, OpenCode, Codex, Gemini CLI, Hermes, etc.
+- 🔄 **Universal Memory Migrator (30 Engines)**: One-click migration from Letta, Mem0, Supermemory, Cognee, Beads, Mnemosyne, GBrain, and more with state preservation.
 - 🎨 **Cognitive Studio Visual Dashboard (`memory ui`)**: Embedded zero-dependency web interface featuring 3D force-directed knowledge graphs, live `CURRENT.md` monitor, wiki reader, and persona editor.
 - ⏰ **Proactive Nudges & Routines Scheduler**: Cron-invoked daily briefings, staleness policy tracking, and ambient open-loop trackers with zero resident background daemons.
 
 ---
 
-## ⚡ Quick Start & Installation
+## Where your memory lives
+
+Everything Muse knows is a folder you can open, read, diff, back up, or commit.
+
+```
+.memory/                                  # project scope — travels with your repo
+├── memory.db                             # SQLite: memories, anchors, graph edges, audit
+├── memories/                             # one YAML file per memory — plain text, reviewable
+├── CURRENT.md                            # active constraints, injected every session
+├── USER.md                               # your persona and working preferences
+├── observations.jsonl                    # append-only event log the harvester mines
+├── audit.jsonl                           # tamper-evident write log
+└── sync_pool/                            # zero-daemon shared gossip pool
+~/.memory/                                # global scope — preferences that follow you
+```
+
+There is no server, no port, and no service to keep alive. Delete the folder
+to delete the memory.
+
+---
+
+## Start with one command
 
 > [!TIP]
-> ### ⚡ Instant 5-Second Setup (Zero-Install NPX / BunX)
-> **No global installation required.** Set up your memory system and wire your AI agents with a single command:
+> ### Install without a global package
+> Set up the memory store and connect your local AI agents with one command:
 >
 > ```bash
 > npx musememory install
@@ -175,8 +276,39 @@ git clone https://github.com/harshsinghmp/musememory.git && cd musememory
 docker build -t musememory .
 ```
 
-> [!NOTE]
-> ### 📊 How does Muse Memory compare to other solutions?
+---
+
+## 📖 Documentation map
+
+Two layers, on purpose. **Human docs** are narrative and explain *why*.
+**Agent docs** are contracts: exact commands, exact tool names, exact failure
+behaviour, with nothing to interpret. An agent should never have to read a
+prose paragraph to learn a flag name.
+
+### For agents — read these
+
+| Document | What it gives you |
+| :--- | :--- |
+| **[Agent reference](docs/agent-reference.md)** | The contract: install, file layout, mandatory session protocol, trust gates, failure semantics. |
+| **[CLI & MCP reference](docs/cli-reference.md)** | Every command and every MCP tool, generated from the source. |
+| **[`mcp-tool-matrix.json`](docs/mcp-tool-matrix.json)** | The tool list as JSON, for programmatic consumption. |
+| **[`claims.json`](claims.json)** | Every countable claim, generated from `src/` — tool, platform and test counts. |
+| **[`llms.txt`](https://harshsinghmp.github.io/musememory/llms.txt)** | The website, for agents. `llms-full.txt` is the whole site as plain text. |
+
+### For humans
+
+| Guide | Intent & Framework | Target Audience |
+| :--- | :--- | :--- |
+| 🧠 **[Core Concepts & Architecture](docs/concepts.md)** | **ACCA Framework**: Explains the guarded 7-state lifecycle machine, dual-scope engine, knapsack scoring, and zero-daemon architecture. | Tech Leads, Architects, Evaluators |
+| 🛡️ **[Failure Attribution & Negative Mining](docs/failure-attribution-and-negative-mining.md)** | **QUEST Framework**: Scoped attribution, decaying strikes, trajectory fix-pair mining, HOT.md compounding, and logarithmic frequency ranking. | AI Engineers, Systems Architects |
+| 🛠️ **[Developer Daily User Guide](docs/user-guide.md)** | **QUEST Framework**: The 3-phase daily pair-programming loop (`/muse-ground` → `CURRENT.md` → `/muse-capture`). | Solo Developers, Daily AI Coders |
+| ⚡ **[Retrieval Performance & Guardrails](docs/retrieval-performance-and-limits.md)** | **QUEST Framework**: WeakMap token sets, memoized runtime anchors, dirty-gating, limit clamping, and dry-run safety. | Platform Engineers, AI Architects |
+| 🏛️ **[Living Architecture & Drift Auditing](docs/living-architecture-and-drift.md)** | **ACCA Framework**: Binding ADRs to line-independent code anchors, write-time `base_path` normalization, and pure read-path drift sentry. | System Architects, Tech Leads |
+| ⚡ **[Real-Time Daemon & Observability](docs/daemon-and-observability.md)** | **QUEST Framework**: Real-time SSE event hub (`memory daemon`), CI upgrade gates (`--check`, `--strict`), and PageIndex depth parameters. | Swarm Engineers, DevOps, Builders |
+| 👥 **[Team Quickstart & Deployment Guide](docs/team-getting-started.md)** | Single-host server deployment, systemd/Docker setups, and per-editor client recipes (Cursor, Opencode, Claude Code, Antigravity, Windsurf). | Engineering Managers, Team Leads |
+| 🏛️ **[Team Slice Wiring & Architecture](docs/architecture/team-slice-wiring.md)** | Technical deep-dive into in-process SQLite WAL vs corrupted network mounts. | Infrastructure Engineers, Systems Architects |
+| 📊 **[Capability Comparison](https://harshsinghmp.github.io/musememory/compare)** | 14-capability comparison of local-first memory against vector stores, graph platforms and session search. | Decision Makers, Evaluators |
+
 ---
 
 ## 🔄 Upgrading & Self-Healing Maintenance
@@ -196,7 +328,7 @@ npx musememory upgrade
 #### What `memory upgrade` automatically handles:
 1. **Package Manager Auto-Detection**: Detects whether your workstation runs `bun`, `npm`, `pnpm`, or `yarn` and pulls the latest published binary.
 2. **Self-Healing Storage Repair**: Recovers missing `.memory/`, `CURRENT.md` constraints, or `USER.md` persona files if corrupted or deleted.
-3. **80+ Agent Platform Re-Discovery**: Scans for newly installed coding agents (Cursor, Claude Code, Windsurf, OpenCode, Codex, Gemini CLI, Hermes, etc.) and auto-wires them with zero permissions.
+3. **52 Agent Platform Re-Discovery**: Scans for newly installed coding agents (Cursor, Claude Code, Windsurf, OpenCode, Codex, Gemini CLI, Hermes, etc.) and auto-wires them with zero permissions.
 4. **AST Symbol Graph Re-Indexing**: Re-synchronizes CodeGraph/Graphify symbol caches under `.memory/graph-symbols.json`.
 
 ---
@@ -212,9 +344,15 @@ npx musememory upgrade
 | **NPX** (Zero-Install) | `npx musememory@latest upgrade` | `npx musememory doctor` |
 
 ```bash
-# Check if updates are available without applying
+# Check if updates are available without applying (exits 0 if up to date, 1 if registry fails)
 memory upgrade --check
 
+# Enforce up-to-date installation in CI pipelines (exits 1 if update is available)
+memory upgrade --check --strict
+
+# Preview upgrade actions in dry-run mode
+memory upgrade --dry-run
+
 # Force re-installation and complete platform re-wiring
 memory upgrade --force
 ```
@@ -244,7 +382,7 @@ npx musememory stats
 npx musememory briefing
 ```
 
-### 3️⃣ Connect Coding Agents (80+ Platforms)
+### 3️⃣ Connect Coding Agents (52 Platforms)
 ```bash
 # Scan workstation for installed AI coding agents
 npx musememory agents
@@ -258,6 +396,10 @@ npx musememory connect cursor
 npx musememory connect antigravity
 npx musememory connect windsurf
 npx musememory connect opencode
+
+# Claude Code lives under ~/.claude*, so it needs an explicit harness opt-in.
+# Without this flag the Claude config is reported as skipped and nothing is written.
+npx musememory connect claude-code --harness claude
 ```
 
 ### 4️⃣ Clean Uninstallation & Removal
@@ -268,7 +410,7 @@ npx musememory connect opencode
 Muse Memory can be cleanly and completely removed with zero trace left on your machine.
 
 #### Step 1: Unwire Coding Agents (Zero-Trace MCP Cleanup)
-Remove the memory MCP server configuration from all 80+ detected agent config files (`cursor`, `claude-code`, `antigravity`, `windsurf`, `opencode`, `codex`, etc.):
+Remove the memory MCP server configuration from every detected agent config file (`cursor`, `claude-code`, `antigravity`, `windsurf`, `opencode`, `codex`, etc.):
 
 ```bash
 # Preview changes before modifying any configuration
@@ -320,6 +462,42 @@ If you installed the pre-commit transcript harvester hook or injected agent prom
 
 ---
 
+## 👥 Team & Multi-Member Setup
+
+Deploy a shared persistent cognitive memory layer across your entire engineering team. All team members' coding agents (Cursor, Opencode, Claude Code, Antigravity, Windsurf) connect to a single host server running in-process SQLite over **MCP Streamable HTTP (2025-06-18)** with Bearer token authentication.
+
+```
+                    Central Team Server (`team.db` + `CURRENT.md`)
+                                       ▲
+                                       │ MCP Streamable HTTP (Bearer Auth)
+         ┌───────────────────┬─────────┴─────────┬───────────────────┐
+      Cursor              Opencode          Antigravity         Claude Code
+```
+
+### 1-Line Team Server Start
+Run on your team's internal VM, build server, or workstation:
+```bash
+# Start server with individual or shared Bearer auth tokens
+musememory serve --port 31338 --host 0.0.0.0 --tokens alice:tok_alice_123,bob:tok_bob_456
+```
+
+### 1-Line Client Recipe Generator
+Generate ready-to-paste configurations tailored to each engineer's specific editor:
+```bash
+# Interactive editor selector
+musememory connect
+
+# Or output directly into console:
+musememory connect --recipe --endpoint http://192.168.1.50:31338/mcp --token tok_alice_123
+```
+
+### Complete Getting Started & Architecture Guide
+For full server setup (systemd service, Docker, reverse proxy), editor-specific client JSON configs, team memory scoping rules (`team.db` vs personal `tenant_<id>.db`), and prompt injection defenses, see:
+- 👉 **[Team Quickstart & Deployment Guide](docs/team-getting-started.md)** — Step-by-step setup for Team Leads and Engineers.
+- 👉 **[Team Slice Wiring & Architecture Spec](docs/architecture/team-slice-wiring.md)** — Technical deep dive into in-process SQLite vs networked mounts.
+
+---
+
 ## 🏛️ System Capabilities & Architecture
 
 ### 1. Dual-Scope Storage (Local vs Global)
@@ -345,6 +523,8 @@ Retrieval dynamically ranks knowledge using a calibrated multi-factor formula:
 $$\text{Score} = 1.0 \times \text{Applicability} + \text{StatusBonus} + \text{VerificationBonus} + \text{GraphBonus} + \text{SalienceBonus} + 0.3 \times e^{-\frac{\Delta t}{90\text{ days}}}$$
 The engine greedily packs ranked memories up to the requested `--token-budget` to guarantee zero prompt overflow.
 
+When a local embedder is configured (`retrieval.embedderUrl`), a semantic cosine dimension (`0.5 ×` cosine similarity) joins the ranking, so paraphrases match even without shared trigrams. Leave the embedder unset and ranking is identical to the lexical behaviour above — no network calls, no new dependency.
+
 ### 4. Real-Time `CURRENT.md` Synchronization & Session Handoff
 - Active constraint memories automatically mirror into `CURRENT.md`.
 - In-flight task states, agent checkpoints, and active loops persist across terminal restarts, context compactions, and sudden interruptions.
@@ -354,7 +534,7 @@ The engine greedily packs ranked memories up to the requested `--token-budget` t
 - **Named Entity Extraction (`memory entities`)**: Automatically extracts persons, products, organizations, tools, and code symbols with co-occurrence edge weights.
 - **PageIndex Reasoning Engine (`memory pageindex`)**: Indexes unstructured documents into hierarchical reasoning trees.
 
-### 6. Universal Migration Engine (29 Memory Formats)
+### 6. Universal Migration Engine (30 Memory Formats)
 Auto-detects and ingests existing memory stores across 29 external engines:
 ```bash
 # Auto-detect all external memory stores on your machine
@@ -366,7 +546,7 @@ memory migrate --provider mem0
 memory migrate --provider beads
 memory migrate --all
 ```
-> See [`musememory-comparison.html`](musememory-comparison.html) for the full table-free 30-system architectural dossier.
+> See the live [capability comparison](https://harshsinghmp.github.io/musememory/compare) for the published page, and [`docs/research/musememory-comparison.html`](docs/research/musememory-comparison.html) for the research survey dossier (68 systems).
 
 ---
 
@@ -395,141 +575,63 @@ Navigate to `http://localhost:2222` to access:
 
 ---
 
-## 📖 Deep Technical References & Documentation
+## 🔌 CLI & MCP reference
 
 <details>
-<summary><b>🔌 Complete MCP Tool Reference (61 Tools across 6 Profiles)</b> — <i>Click to expand</i></summary>
+<summary><b>🔌 CLI & MCP reference (generated from source)</b> — <i>Click to expand</i></summary>
 
-When registered as an MCP server, `musememory` exposes the following native tools (filtered dynamically into role-tailored profiles to eliminate tool bloat):
+The complete command and tool surface is **generated from `src/`**, not
+transcribed by hand, so it cannot drift:
 
-| MCP Tool | Execution Phase | Description |
-| :--- | :--- | :--- |
-| `muse_context` | **Flagship Fusion** | Single-call fused orchestrator combining search, active file, symbol, error messages, and task intent under strict knapsack token budgets. |
-| `muse_health` | **Quality Gate** | 5-Pillar Project Health Gate: audits store integrity, code anchors, doc/code alignment, anti-pattern sentry, and technical debt with A-F grading and pass/fail status. |
-| `muse_why` | **Cognition / "Why"** | Explains *why* code was designed the way it is by reconstructing past ADRs, bug fixes, trade-offs, and timeless rules. |
-| `muse_bug_clusters` | **Fragility Hotspots** | Categorizes recurring bugs into 5 root causes with subsystem fragility scoring. |
-| `muse_tech_debt` | **Technical Debt** | Scans code and memory for TODO/FIXME markers, unsafe `as any` casts, and drifted anchors. |
-| `muse_memory_for_code`| **Code-to-Memory** | Queries all memories, ADRs, constraints, and bugs associated with a code file and symbol. |
-| `muse_code_for_memory`| **Memory-to-Code** | Resolves all native code anchors and affected source files for a given memory entry. |
-| `memory_adr_record` / `list` | **Architecture Decisions** | Records and queries first-class Architecture Decision Records with native code anchors and options considered. |
-| `memory_drift_audit` | **Drift Engine** | Audits bi-directional documentation $\longleftrightarrow$ code drift across 6 alignment states (`DOCUMENTED`, `IMPLEMENTED`, `PARTIAL`, `CONFLICTING`, `STALE`, `MISSING`). |
-| `memory_capture_negative` | **Negative Sentry** | Records failed approaches, anti-patterns, and reproduction commands to prevent repeating mistakes. |
-| `memory_promote_scope` | **Scoped Promotion** | Promotes memory along 3-tier ladder (`local` $\rightarrow$ `project` $\rightarrow$ `global`) with 5× repeated success policy and universal generalization. |
-| `memory_archive` / `rehydrate` | **Archival Lifecycle** | Evaluates and manages `active` $\rightarrow$ `cold` $\rightarrow$ `dormant` $\rightarrow$ `archived` lifecycle with query rehydration. |
-| `memory_lifecycle_stats` / `sweep` | **Lifecycle Sweeper** | Reports store-wide lifecycle statistics and executes sweep transitions for aging memories. |
-| `anchor_create` / `verify` / `audit` | **Code Identity** | Creates, verifies, and audits line-independent structural code anchors. |
-| `muse_sync_broadcast` / `ingest` | **P2P Gossip Mesh** | Broadcasts and ingests portable sealed SyncPackets with deduplication and contradiction flagging. |
-| `muse_sync_status` / `pool` | **Sync Coordination** | Tracks peer vector clocks and synchronizes memories bidirectionally via shared drop-directory pool. |
-| `muse_mesh_status` | **Monorepo Topology** | Discovers monorepo workspaces and multi-repo sibling groups with package dependencies and stores. |
-| `muse_mesh_query` | **Cross-Project Query** | Queries memories across the entire workspace mesh with origin package provenance tags. |
-| `muse_mesh_audit` | **Contract Verification** | Audits cross-package dependency contracts, entrypoint exports, and cross-repo code anchors. |
-| `muse_mesh_link` | **Mesh Linking** | Explicitly links or unlinks external repository paths into the workspace mesh registry. |
-| `profile_list` / `profile_switch` | **Tool Management** | Lists and switches task-focused MCP profiles (`core`, `coding`, `debugging`, `review`, `architecture`, `maintenance`). |
-| `get_context` | **Session Start** | Fetches Top-$K$ ranked memories, `USER.md` profile, active `CURRENT.md` constraints, and supports `--tier 0|1|2`. |
-| `search` | **Investigation** | Searches memory units with query, token budget, project, type, and verification filters. |
-| `memory_current` | **Constraints** | Reads or appends active project working constraints (`CURRENT.md`). |
-| `memory_get_user_profile` | **Context Loading** | Reads active `USER.md` persona and communication preferences. |
-| `memory_set_user_profile` | **Preferences** | Updates `USER.md` profile with inline secret defense. |
-| `memory_capture` | **During Fixes** | Saves a memory entry with inline Vibeguard secret inspection. |
-| `memory_confirm` | **Decision Approval** | Promotes candidate insight to confirmed status. |
-| `memory_supersede` | **Refactoring** | Marks outdated knowledge superseded by a confirmed replacement. |
-| `memory_link` | **Graph Building** | Connects related memories bidirectionally. |
-| `memory_mark_stale` | **Deprecation** | Flags decaying knowledge with deprecation rationale. |
-| `memory_reject` | **Hypothesis Refutation** | Marks invalidated hypotheses as rejected. |
-| `memory_delete` | **Purge** | Permanently deletes an entry and records audit ledger log. |
-| `memory_source_add` / `list` | **Provenance** | Records external docs/RFCs/URLs into `.memory/sources.json` and queries sources. |
-| `memory_claim_record` / `list` | **Claim Ledger** | Records evidence-backed claims tagged with `[RAW]`, `[FETCH]`, `[SEARCH]`, `[INFER]`. |
-| `memory_freeze_run` / `list` | **Execution Snapshots** | Freezes immutable task snapshots with file inventory and SHA-256 memory hashes. |
-| `memory_prompt_list` / `get` / `run` | **Prompt Templates** | Manages and executes native structured prompt templates with live context injection. |
-| `memory_rollup` | **Temporal Compounding** | Aggregates atomic memories into weekly, monthly, and quarterly rollups and updates `HOT.md`. |
-| `memory_loop_record` / `status` | **Gauntlet Loops** | Multi-agent iteration ledger and plateau/regression detector (`.memory/iterations.jsonl`). |
-| `memory_verify_strict` | **Integrity Gate** | Zero-tolerance audit verifying secrets, referential links, wikilinks, claims, and candidates. |
-| `memory_tree_search` | **Tree Retrieval** | Hierarchical reasoning search across partitioned memory shards. |
-| `memory_wiki_compile` | **Wiki Compiler** | Compiles confirmed memories into Obsidian-compatible Markdown pages. |
-| `memory_wiki_search` / `get` | **Wiki Reading** | Searches and reads compiled concept and entity wiki pages. |
-| `memory_entities_search` / `get` | **Entity Graph** | Searches extracted entities and inspects co-occurrence strengths. |
-| `memory_pageindex_index` | **Doc Indexing** | Builds a hierarchical reasoning tree from document content. |
-| `memory_pageindex_search` | **Doc Search** | Searches PageIndex document tree with reasoning explanations. |
-| `memory_pageindex_import` | **Doc Knowledge** | Imports PageIndex search insights directly into memory units. |
-| `memory_search_transcripts` | **History Search** | Full-text search over past `.jsonl` transcripts with dialogue context windows. |
-| `memory_harvest` | **Session End** | Distills conversation turns into structured fix/outcome units. |
-| `memory_import_transcript` | **Transcript Sync** | Ingests `.jsonl` transcript and auto-binds memories to session nodes. |
-| `memory_audit` | **Governance** | Queries the append-only operational audit ledger. |
-| `memory_detect_agents` | **Onboarding** | Scans workstation for 80+ coding agent installations. |
-| `memory_connect` | **Setup** | Auto-wires MCP server into detected installed agents with zero permissions. |
-| `memory_detect_providers` | **Migration** | Scans machine for 29 external memory formats. |
-| `memory_migrate` | **Migration** | Ingests external memories with state preservation and secret scrubbing. |
-| `memory_export` / `import` | **Team Sharing** | Exports and imports portable JSON memory snapshots. |
-| `memory_validate` | **Integrity Check** | Verifies database integrity and scans for credential leaks. |
-| `memory_settings_get` / `set` | **Configuration** | Reads and updates unified global or project configuration settings. |
-| `graph_status` | **AST Graph** | Inspects CodeGraph/Graphify symbol overlap provider status. |
-| `graph_index` | **AST Graph** | Indexes AST symbol graph and caches in `.memory/graph-symbols.json`. |
+| Document | Contents |
+| :--- | :--- |
+| **[`docs/cli-reference.md`](docs/cli-reference.md)** | Every CLI command with its flags, and every MCP tool with its required parameters — grouped by purpose. |
+| **[`docs/mcp-tool-matrix.json`](docs/mcp-tool-matrix.json)** | The MCP tool list as JSON, for programmatic consumption. |
+| **[`docs/agent-reference.md`](docs/agent-reference.md)** | The contract an agent must follow: session protocol, trust gates, failure semantics. |
+| **[`claims.json`](claims.json)** | Every countable claim, generated from `src/`. |
 
-</details>
-
-<details>
-<summary><b>💻 Full CLI Command Matrix (47 Commands)</b> — <i>Click to expand</i></summary>
+### The commands you will actually use
 
 ```bash
-memory <command> [arguments] [flags]  # alias: musememory
+memory context [query] --token-budget N   # top-ranked context for prompt injection
+memory search <query> --limit N           # ranked search with a score breakdown
+memory capture "<text>" --project P       # persist a memory (secret-scanned, citation-verified)
+memory propose "<text>" --project P       # propose a candidate without confirming it
+memory confirm <id>                       # promote a candidate to confirmed
+memory supersede <old_id> --with <new_id> # replace outdated knowledge, keep lineage
+memory current get | set "<text>"         # read/write active constraints
+memory link <id> --related <id1,id2>      # bidirectional relation between entries
+memory audit [--operation OP]             # query the append-only audit ledger
+memory doctor                             # full ecosystem health diagnostic
+memory health                             # 5-pillar health gate with a letter grade
+memory verify <id> --strict               # run an entry's verification command
+memory harvest "<text>" --project P       # distil a turn into a fix/decision unit
+memory wiki compile                       # compile memories into an Obsidian wiki
+memory benchmark                          # measured speed, quality and token-economy report
 ```
 
-| Command | Arguments / Flags | Description |
-| :--- | :--- | :--- |
-| `health` | `[--json] [--global]` | **Unified 5-Pillar Project Health Gate**: audits Store Integrity, Code Anchors, Drift, Sentry, and Tech Debt with A-F grading and pass/fail gate. |
-| `studio` / `ui` | `[--port N] [--global]` | **Web Observability Studio**: visual dashboard with 5-pillar health, ADR drift, why reasoner, and live mesh (default port: `2222`). |
-| `sync` | `[status\|broadcast\|ingest\|pool] [flags]` | **P2P Gossip Mesh**: peer vector clock status, packet export, ingestion, and shared pool gossip sync. |
-| `mesh` | `[overview\|query\|check\|link\|unlink\|propagate] [flags]` | **Monorepo & Multi-Repo Mesh**: workspace discovery, cross-project memory query, and contract drift audit. |
-| `adr` | `[record\|list\|supersede] [args]` | **Architecture Decision Records**: record, list, and supersede living architecture decisions. |
-| `anchor` | `[create\|verify\|audit] [args]` | **Code Anchors**: create, verify, and audit line-independent structural code anchors. |
-| `install` | `[path] [--global]` | **One-line complete setup**: initializes `.memory/`, `USER.md`, and auto-wires coding agents. |
-| `doctor` | `[path] [--global]` | **System diagnostic**: checks SQLite primary, schemas, secrets, and MCP connections. |
-| `uninstall` | `[agent] [--purge] [--dry-run]` | **Clean uninstaller**: unwires MCP configs (and optionally purges `.memory/`). |
-| `init` | `[path] [--legacy] [--global]` | Initialize `.memory/` directory and SQLite database. |
-| `user` | `[get\|init\|set] [args] [--global]` | Manage `USER.md` persona & preferences across 5 clean archetypes. |
-| `connect` | `[agent] [--all] [--force] [--dry-run]` | Auto-wire MCP into detected installed agents with zero permissions. |
-| `agents` | *(none)* | Scan workstation for 80+ coding agents (Cursor, Claude Code, Antigravity, etc.). |
-| `detect` | *(none)* | Scan workstation and local workspace for 29 external memory systems. |
-| `migrate` | `[--provider P] [--all] [--dry-run] [--overwrite]` | Migrate memories into Muse Memory preserving active/archived state. |
-| `context` | `[query] [--token-budget N] [--limit N] [--tier 0\|1\|2]` | Retrieve Top-$K$ ranked active context for prompt injection. |
-| `search` | `<query> [--limit N] [--token-budget N] [--type T]` | Ranked multi-factor token search with score breakdown. |
-| `search-transcript` | `<query> [file.jsonl] [--window N]` | Full-text search past transcripts with dialogue context windows. |
-| `learn` / `sync-chats` | `[--confirm] [--force] [--max N]` | **Universal auto-learner**: auto-discovers and distills memories from all agent chats across host machine. |
-| `harvest` | `<text\|file> --project P [--confirmed]` | Distill conversation turns into structured fix/decision memory units. |
-| `import-transcript` | `<file.jsonl> [--project P] [--confirmed]` | Ingest raw `.jsonl` session transcripts from coding agents. |
-| `capture` / `propose` | `<text> --project P [--title T] [--type T]` | Propose a memory entry with inline Vibeguard secret inspection. |
-| `recall` | `<query> [--limit N] [--token-budget N]` | Rich recall displaying verification levels and related graph links. |
-| `confirm` | `<id> [--global]` | Promote `candidate`, `disputed`, or `stale` entry to `confirmed`. |
-| `supersede` | `<old_id> --with <new_id>` | Mark old entry superseded by new confirmed replacement. |
-| `mark-stale` | `<id> [--reason <text>]` | Mark an entry stale with deprecation rationale. |
-| `reject` | `<id> [--global]` | Mark an entry rejected. |
-| `delete` | `<id> [--reason <text>]` | Permanently delete a memory entry and record audit event. |
-| `source` | `add\|list\|show <url> [--title T] [--type T]` | Manage external documentation and URLs in provenance Source Ledger (`.memory/sources.json`). |
-| `claim` | `record\|list\|show <text> [--confidence RAW\|FETCH\|SEARCH\|INFER]` | Record and query verifiable claims connected to sources (`.memory/claims.json`). |
-| `freeze` | `--task <task.md\|text> [--run-id R]` | Capture immutable execution snapshot with file inventory and SHA-256 memory hashes. |
-| `prompt` | `list\|show\|run <name> [--args k=v,...]` | Manage and run structured prompt templates with live context injection. |
-| `rollup` | `--period week\|month\|quarter [--date YYYY-MM-DD]` | Multi-scale temporal compounding and `.memory/HOT.md` working memory cache compiler. |
-| `loop` | `record\|status\|clear` | Multi-agent Gauntlet iteration ledger and plateau/regression detector. |
-| `verify` | `<id> [--timeout S] [--strict]` | Execute a fix entry's test command or run full strict integrity gate. |
-| `audit` | `[--operation OP] [--entry-id ID] [--limit N]` | Query append-only operational audit trail (`.memory/audit.jsonl`). |
-| `link` | `<id> --related <id1,id2>` | Synchronize bidirectional relation links between entries. |
-| `export` / `import` | `[--out <file.json>]` / `<file.json>` | Export and import portable JSON memory snapshots. |
-| `list` / `ls` | `[--status S] [--type T] [--project P]` | List memory entries with multi-field status and type filtering. |
-| `stats` | `[--global]` | Breakdown statistics of total memories, status, and type metrics. |
-| `briefing` | `[--limit N] [--global]` | Active summary of recent entries, status counts, and due items. |
-| `nudge` | `[--global]` | Proactive attention list: overdue entries, stale policies, open loops. |
-| `routine` | `run <name>` / `install [name]` | Execute `.memory/routines.yaml` steps or print crontab lines. |
-| `wiki` | `compile\|list\|show <slug>` | Compile and browse Obsidian-compatible Markdown wiki pages. |
-| `entities` | `list\|show <id>\|related <id>` | Inspect extracted knowledge graph entities and co-occurrence weights. |
-| `settings` | `get\|set\|reset\|export\|import` | Manage unified settings across retrieval, wiki, PageIndex, and UI. |
-| `current` | `get` / `set <text> --project P` | Read or append hard constraints in `.memory/CURRENT.md`. |
-| `graph` | `status` / `index` | Query active CodeGraph provider status or index AST symbol map. |
-| `mcp` | *(none)* | Start stdio MCP server (Protocol 2024-11-05). |
+### The MCP tools you will actually use
+
+| Tool | When |
+| :--- | :--- |
+| `get_context` | **First turn of any session.** Persona, constraints, top-K memories. |
+| `muse_context` | Task-shaped fused context (constraints + memories + negative lessons + anchors). |
+| `memory_capture` | Right after a fix, a decision, or a new constraint. |
+| `memory_supersede` | When knowledge is replaced — never `delete`. |
+| `search` / `memory_tree_search` | Investigating what is already known. |
+| `muse_why` | Before a refactor: why is the code like this? |
+| `muse_code_impact` | Before touching a file: what depends on it? |
+| `memory_audit` | When you need to know who changed what, and when. |
+| `muse_profile_list` | Which tools are exposed in the current profile. |
+
+Tools are exposed through 7 task-focused profiles (`core`, `coding`,
+`debugging`, `review`, `architecture`, `maintenance`, `full`) so an agent is
+never handed the whole surface. Select one with `MUSE_MCP_PROFILE`.
 
 </details>
 
 <details>
-<summary><b>🧠 Shipped Agent Skills (<code>.agents/skills/</code>)</b> — <i>Click to expand</i></summary>
+<summary><b>🧠 Shipped agent skills (<code>.agents/skills/</code>)</b> — <i>Click to expand</i></summary>
 
 Muse Memory ships with 11 turnkey Agent Skills designed for coding agents (Claude Code, Cursor, Antigravity, OpenCode, Codex, Gemini CLI, etc.) under `.agents/skills/`:
 
@@ -580,86 +682,31 @@ memory user set "- Prefers TypeScript, Bun, and ultra terse responses"
 
 ```bash
 bun install
-bun test          # 497 passed across 84 test files (2190 assertions)
+bun test          # 1335 pass, 0 fail, 6123 assertions across 205 files
 bun run typecheck # 0 static type errors
 bun run build     # Clean bundled distribution build (dist/index.js)
 ```
 
----
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the branch/PR model, the per-commit gate, and the post-merge sequence.
 
-## 🔮 Sprint & Roadmap Board
-
-<details>
-<summary><b>🔮 Sprint & Roadmap Lifecycle (Requested ➔ Planned ➔ In Progress ➔ Done)</b> — <i>Click to expand</i></summary>
+---
 
-Muse Memory features are developed in structured sprints moving across 4 deterministic lifecycle phases following strict `vX.Y.Z` semantic versioning. Every sprint is delivered via PR from `dev` to `main` with associated GitHub milestones. Live tracking: [GitHub Issues & Milestones](https://github.com/harshsinghmp/musememory/issues).
+## 🔮 Roadmap
 
-```
-[ 📋 Requested ] ──► [ 📅 Planned ] ──► [ ⚡ In Progress ] ──► [ ✅ Done ]
- (Issues / PRs)     (Sprint Backlog)    (Active PR / Milestone)  (Shipped to Main)
-```
+Work moves through four phases — requested → planned → in progress → done —
+and ships as a pull request from `dev` to `main`.
 
-### 🏷️ Semantic Versioning Protocol (`vX.Y.Z`)
-- **`X` (Major)**: Breaking architectural changes, core schema shifts, or protocol overhauls (`vX.0.0`).
-- **`Y` (Feature)**: Substantive new agent capabilities, MCP tools, or CLI subcommands (`vX.Y.0`).
-- **`Z` (Minor / Hotfix / Critical Fix)**: Bug remediations, security patches, performance, and urgent hotfixes (`vX.Y.Z`).
-
-### 📋 Phase 1: Requested (Backlog)
-*Incoming community proposals, agent adapters, and feature requests pending sprint triage:*
-- [ ] Multi-Agent Consensus Verification Protocol (cross-agent memory agreement)
-- [ ] Continuous Background Memory Compaction & Pruning Cron
-- [ ] Export to Local Vector GGUF Embedding Index
-
-### 📅 Phase 2: Planned
-*Confirmed high-leverage features scheduled for upcoming sprints:*
-- [ ] **Tiered Retrieval Engine**: Deterministic Tier 0 (manifest), Tier 1 (invariants), Tier 2 (bounded bodies) knapsack retrieval
-- [ ] **Provenance & Claim Ledgers**: Direct memory citations with `[RAW]`, `[FETCH]`, `[SEARCH]`, and `[INFER]` confidence tagging
-- [ ] **Frozen Context Snapshots**: Immutable SHA-256 state tracking for reproducible agent execution
-- [ ] **Native Prompt Registry**: Declarative prompt library & runner (`.memory/prompts/*.md`, `memory prompt run`)
-- [ ] **Temporal Compounding**: Multi-scale Day $\to$ Week $\to$ Quarter wiki rollups & `.memory/HOT.md` cache
-- [ ] **Gauntlet Iteration Ledger**: Multi-turn improvement loop tracking and plateau detection
-- [ ] **Strict Health Gate**: Comprehensive `memory verify --strict` referential, link, and secret validator
-
-### ⚡ Phase 3: In Progress (Active Sprint / PR)
-*Currently under active development on dedicated feature branches:*
-- *(None — Sprint SOW-200 completed and shipped)*
-
-### ✅ Phase 4: Done (Shipped to Production)
-*All completed, tested, and released milestones:*
-| Status | Milestone / Feature | Shipped Release / Tracker |
-| :--- | :--- | :--- |
-| ✅ | **SOW-201**: Live Runtime File & Symbol Verification Gate (`STRONG`/`WEAK`/`STALE`) | shipped v1.8.0 |
-| ✅ | **SOW-202**: Deterministic Relevance Cutoff Gate (hard score threshold $\ge 0.45$) | shipped v1.8.0 |
-| ✅ | **SOW-203**: Git Code-Drift Scanner CLI (`memory drift` / `memory check`) | shipped v1.8.0 |
-| ✅ | **SOW-204**: Gradient-Free Hebbian Co-Activation Plasticity (synaptic link reinforcement) | shipped v1.8.0 |
-| ✅ | **SOW-205**: Semantic Memory Prompt Compression (`memory compress` lossless prompt packer) | shipped v1.8.0 |
-| ✅ | Turnkey Agent Skills Suite (`muse-ground`, `muse-capture`, etc.) | shipped v1.7.0 |
-| ✅ | AST Symbol Graph Integration (CodeGraph / Graphify) | [#35](https://github.com/harshsinghmp/musememory/issues/35) / v1.7.0 |
-| ✅ | Zero-Friction Installation Lifecycle Fix | shipped v1.7.1 |
-| ✅ | Proactive Nudges & Check-ins (`memory nudge`) — SOW-101 | [#28](https://github.com/harshsinghmp/musememory/issues/28) |
-| ✅ | Daily Briefing & Routines Scheduler (cron-invoked, no daemon) — SOW-102 | [#29](https://github.com/harshsinghmp/musememory/issues/29) |
-| ✅ | Open-Loop / Task Extraction from Transcripts — SOW-103 | [#30](https://github.com/harshsinghmp/musememory/issues/30) |
-| ✅ | Calendar / Time-Aware Follow-ups (`due_at` / `expires_at`) — SOW-104 | [#31](https://github.com/harshsinghmp/musememory/issues/31) |
-| ✅ | muse-agents ↔ musememory Integration Contract (`--for-agent`) — SOW-106 | [#33](https://github.com/harshsinghmp/musememory/issues/33) |
-| ✅ | Dynamic Prompt Token Budgeter (`--token-budget N`) | shipped v1.1.0 |
-| ✅ | Scene-Based Hierarchical Consolidation (`memory consolidate`) | [#1](https://github.com/harshsinghmp/musememory/issues/1) |
-| ✅ | Autonomous Verification Oracle (`memory verify <id>`) | [#2](https://github.com/harshsinghmp/musememory/issues/2) |
-| ✅ | Multi-Hop Causality Graph Tracer (`memory trace <id>`) | [#3](https://github.com/harshsinghmp/musememory/issues/3) |
-| ✅ | In-Place Core Memory Partitioning (`memory core`) | [#4](https://github.com/harshsinghmp/musememory/issues/4) |
-| ✅ | Automated Post-Turn Transcript Harvester Hook | [#5](https://github.com/harshsinghmp/musememory/issues/5) |
-| ✅ | Real-Time Agency WebSocket Hub (`memory daemon`) | [#6](https://github.com/harshsinghmp/musememory/issues/6) |
-| ✅ | Local Offline Hybrid Vector Engine | [#7](https://github.com/harshsinghmp/musememory/issues/7) |
-| ✅ | Delete Deprecated `MemoryStore` Shim | [#8](https://github.com/harshsinghmp/musememory/issues/8) / v1.5.0 |
-| ✅ | Self-Evolving Skill Distillation | [#9](https://github.com/harshsinghmp/musememory/issues/9) |
-| ✅ | 3-Layer Progressive Disclosure | [#10](https://github.com/harshsinghmp/musememory/issues/10) |
-| ✅ | Bi-Temporal Reinforcement Feedback | [#11](https://github.com/harshsinghmp/musememory/issues/11) |
-| ✅ | Ambient Open-Loop Tracker | [#12](https://github.com/harshsinghmp/musememory/issues/12) |
-| ✅ | Knowledge Graph UI v2 | [#13](https://github.com/harshsinghmp/musememory/issues/13) |
+| Phase | Status |
+| :--- | :--- |
+| 📋 Requested | 4 items in the backlog |
+| 📅 Planned | 7 confirmed features scheduled |
+| ⚡ In progress | none — sprint SOW-200 shipped |
+| ✅ Done | shipped to production |
 
-</details>
+**[Full roadmap →](docs/roadmap.md)** · [Live issues & milestones](https://github.com/harshsinghmp/musememory/issues) · [CHANGELOG](CHANGELOG.md)
 
 ---
 
 ## 📜 License
 
-MIT License. Built for the AI Developer Ecosystem.
+MIT License. Built for the AI Developer Ecosystem.