musememory 3.0.2 → 3.3.0

package/README.md

@@ -20,7 +20,7 @@
 ![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-1335%20Passed-brightgreen?style=for-the-badge&logo=checkmarx)
+![CI Tests](https://img.shields.io/badge/Tests-1444%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-Majority%20Supported-4F46E5?style=for-the-badge&logo=openai)
 ![License](https://img.shields.io/badge/License-MIT-9333EA?style=for-the-badge)
@@ -64,56 +64,149 @@ has since changed.
 
 ---
 
+## 🏆 The Golden Sequence: Best-Practice Workflow for AI Agents
+
+To get the absolute best results out of Muse Memory across any AI coding agent (Cursor, Claude Code, Windsurf, OpenCode, Antigravity, Gemini CLI, Hermes, etc.), execute this end-to-end sequence:
+
+```text
+1. INITIALIZE & AUTO-WIRE → 2. PERSONA & PROFILE SETUP → 3. SESSION GROUNDING → 4. IN-FLIGHT TRACKING → 5. DECISION CAPTURE → 6. CONTINUOUS HARVESTING → 7. GOVERNANCE & AUDIT
+```
+
+### 1️⃣ Onboarding & Workstation Auto-Wiring
+Connect all installed AI coding agents on your machine to Muse Memory in one command:
+```bash
+# Wire Muse Memory into every detected agent on your workstation with lifecycle hooks
+npx musememory connect all --with-hooks
+
+# Confirm ecosystem health, database schemas, and toolchain integrity
+memory doctor
+
+# Generate host hardware & toolchain terrain map for agent orientation
+memory terrain --out .memory/system.md
+```
+
+### 2️⃣ Persona Archetype & Working Preferences
+Establish your role and communication habits using sovereign templates with placeholders:
+```bash
+# Initialize standard developer profile (or designer / marketer / casual / custom)
+memory user init developer
+
+# Or initialize a custom profile with bracketed placeholders ([Name], [Role], [Preferences])
+memory user init custom
+
+# Inspect your rendered active profile
+memory user get
+```
+
+### 3️⃣ Daily Agent Development Loop
+In every active pair-programming session with an AI agent, follow this 4-step cadence:
+
+1. **Ground Context (Session Start)**:
+   Agent or prompt retrieves top-ranked architectural decisions, bug fixes, and active constraints:
+   ```bash
+   memory context "refactor auth middleware" --token-budget 2000
+   ```
+2. **Lock Active Working Constraints**:
+   Keep track of invariants, WIP status, and tasks across session boundaries:
+   ```bash
+   memory current checkpoint "migrating session tokens to ed25519"
+   ```
+3. **Capture Non-Trivial Decisions & Bug Fixes**:
+   Every time an architectural choice is made or a bug is resolved, capture it with inline Vibeguard secret defense:
+   ```bash
+   memory capture "Use ed25519 for session tokens; rs256 rejected due to key rotation latency" --project my-app
+   ```
+4. **Mark In-Flight Session Complete**:
+   ```bash
+   memory current done "Token migration completed and verified"
+   ```
+
+### 4️⃣ Compounding, Auditing & Knowledge Governance
+```bash
+# Harvest learnings and fix-pairs from all agent chat logs across your machine
+memory learn
+
+# Compile confirmed memories into Obsidian-compatible Markdown wiki pages
+memory wiki compile
+
+# Run native Vibeguard credential security audit (zero external dependencies)
+memory scan-secrets
+
+# Verify 5-pillar architectural health & clean database optimization
+memory health
+memory optimize
+```
+
+---
+
 ## 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).*
+> One flat list of what is current. Historical releases live in the
+> [Changelog](./CHANGELOG.md) and the [GitHub Releases](https://github.com/harshsinghmp/musememory/releases) pages.
+
+**Correctness**
+
+- **Five defects closed in the engine**: a prompt-injection channel through
+  `CURRENT.md`, a store that could fail its own schema validator, bi-temporal
+  queries answered from a stale cache entry, a tiered-context path that
+  silently dropped `as_of`, and an access counter that never accumulated.
+- **Every published number is generated from the source** and checked by a test,
+  so the site can no longer advertise a figure the code does not produce.
+- **The contradiction engine no longer flags unrelated memories.** It used to
+  compare two memories with bare keyword pairs, so "pooling is enabled" and
+  "pooling is disabled" looked like a conflict. It now compares *claims* about
+  the same subject in the same scope, and a read-only
+  `memory conflicts --dry-run` previews what it would flag.
+- **The health report no longer attributes a store-wide number to one
+  arbitrary project.** It states its own scope — the filter, the projects it
+  covered, the entry count — and `memory health --project P` asks for one
+  project's health directly. The same filter now reaches every audit
+  surface — anchor audit, drift audit, bug clusters, technical debt — plus
+  a labelled **Project Scope** control in the studio whose value is carried
+  in the URL, so a scoped report can be shared or reloaded.
+
+**Delivery discipline**
+
+- **A commit is not a delivery.** `check:landed` runs in CI on every pull
+  request and push: work is *landed* only when it is reachable from the
+  integration branch *on the remote*, and every report must be able to
+  quote that evidence instead of asserting it.
+- **Shared checkouts are leased.** Two agents in one tree cannot collide
+  silently: the checkout is leased before git mutations, broad `git add`
+  is banned, and staging is verified against `git status` immediately
+  before a commit.
+- **The page no longer reads blank without JavaScript**, and the mobile menu
+  no longer overflows the viewport.
+
+**The website**
+
+- **Rebuilt** on a developer-vertical anatomy — hero, demo, architecture, code
+  grid, proof, quickstart — with a fluid token system, a new twelve-second
+  showreel and a line-icon set. Every figure is bound to the same manifest the
+  code generates, so no number on the page can drift from the code.
+- **The release gate is executable code** (`apps/website/scripts/qa-gate.ts`):
+  critical paths, keyboard-only navigation, 200% zoom reflow, the
+  no-JavaScript first frame, animation performance, the payload budget and a
+  second rendering engine. It exits non-zero on a blocking failure and runs in
+  CI, so a broken page cannot ship.
+
+**Capabilities**
+
+- Closed-loop failure attribution matching code anchors with decaying strike
+  counters.
+- Trajectory fix-pair mining that discovers negative lessons from agent error
+  sequences.
+- Active working-set compounding and candidate scoring straight from `HOT.md`.
+- LangMem logarithmic frequency ranking with 2x application weighting.
+- A multi-channel distillation router across system, content and health.
+- A pre-mutation snapshot ring for zero-daemon recovery.
 
 ---
 
 ## 📑 Table of Contents
 
 - [Start here (60 seconds)](#start-here-60-seconds)
+- [🏆 The Golden Sequence](#-the-golden-sequence-best-practice-workflow-for-ai-agents)
 - [What's new](#whats-new)
 - [What Muse Memory does](#what-muse-memory-does)
 - [How it works](#how-it-works)
@@ -240,13 +333,13 @@ to delete the memory.
 
 ## Start with one command
 
-> [!TIP]
-> ### Install without a global package
-> Set up the memory store and connect your local AI agents with one command:
+> [!IMPORTANT]
+> ### Always install and run with `@latest`
+> To ensure you never execute an outdated or cached version, always explicitly append `@latest` when installing or invoking via NPX or Bun:
 >
 > ```bash
-> npx musememory install
-> # (or with Bun: bunx musememory install)
+> npx musememory@latest install
+> # (or with Bun: bunx musememory@latest install)
 > ```
 >
 > This command automatically:
@@ -255,23 +348,34 @@ to delete the memory.
 > 3. Auto-wires the memory MCP server into installed agents with zero-permission auto-approval.
 > 4. Scans for existing memory stores (Letta, Mem0, Beads, Supermemory, etc.) for instant migration.
 >
-> **Verify anytime**: `npx musememory doctor`  
-> **Explore Studio UI**: `npx musememory ui` (Opens cognitive studio on port 2222)
+> **Verify anytime**: `npx musememory@latest doctor`  
+> **Explore Studio UI**: `npx musememory@latest ui` (Opens cognitive studio on port 2222)
 
 ---
 
 ### 📦 Persistent Installation Options
 
-```bash
-# Option A: Global Install with NPM or Bun (Recommended)
-npm install -g musememory
-# or with Bun:
-bun add -g musememory
+Always specify `@latest` across every package manager to ensure you run the newest engine capabilities and security patches:
 
-# Option B: One-Line Shell Installer
+```bash
+# Option A: Global Workstation Install (Always use @latest)
+bun add -g musememory@latest
+# or with NPM:
+npm install -g musememory@latest
+# or with PNPM:
+pnpm add -g musememory@latest
+# or with Yarn:
+yarn global add musememory@latest
+
+# Option B: Local Project Dependency (Pinned in package.json)
+bun add musememory@latest
+# or with NPM:
+npm install musememory@latest
+
+# Option C: One-Line Shell Installer (Pulls latest release binary)
 curl -fsSL https://raw.githubusercontent.com/harshsinghmp/musememory/main/scripts/install.sh | bash
 
-# Option C: Docker Container
+# Option D: Docker Container
 git clone https://github.com/harshsinghmp/musememory.git && cd musememory
 docker build -t musememory .
 ```
@@ -311,89 +415,117 @@ prose paragraph to learn a flag name.
 
 ---
 
-## 🔄 Upgrading & Self-Healing Maintenance
+## 🔄 Updating the System, Project & Packages
 
-Keep Muse Memory and all your connected AI coding agents at peak cognitive performance with automated updates and self-healing environment repairs.
+Keep Muse Memory and all your connected AI coding agents at peak cognitive performance with automated updates, self-healing environment repairs, and consistent `@latest` versioning.
 
-### ⚡ 1-Command Autonomous Upgrade (`memory upgrade`)
-
-Run `memory upgrade` (or `npx musememory upgrade`) to trigger the **Gamified Level-Up Matrix**:
+### 1️⃣ Updating the Global Package / Workstation CLI
+Always use `@latest` across every package manager to pull the newest releases:
 
 ```bash
+# ⚡ Method 1: Autonomous Self-Healing Updater (Recommended)
 memory upgrade
 # or with NPX zero-install:
-npx musememory upgrade
+npx musememory@latest upgrade
+
+# 📦 Method 2: Explicit Package Manager Upgrade (Always specify @latest)
+bun add -g musememory@latest           # Bun (Fastest)
+npm install -g musememory@latest       # NPM
+pnpm add -g musememory@latest          # PNPM
+yarn global add musememory@latest      # Yarn
+
+# 🌐 Method 3: One-Line Shell Script Update
+curl -fsSL https://raw.githubusercontent.com/harshsinghmp/musememory/main/scripts/install.sh | bash
 ```
 
 #### 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. **Coding Agent Re-Discovery**: Scans for newly installed coding agents (Cursor, Claude Code, Windsurf, OpenCode, Codex, Gemini CLI, Hermes, and the rest of the mainstream field) and auto-wires them with zero permissions.
-4. **AST Symbol Graph Re-Indexing**: Re-synchronizes CodeGraph/Graphify symbol caches under `.memory/graph-symbols.json`.
+1. **Package Manager Auto-Detection**: Detects whether your workstation runs `bun`, `npm`, `pnpm`, or `yarn` and updates to the latest release without redundant downgrades.
+2. **Global vs. Per-Project Scoping**:
+   - **Per-Project (`memory upgrade`)**: Operates on `./.memory/`. Repairs local constraints (`CURRENT.md`), project user persona overrides (`USER.md`), re-indexes AST code symbols via CodeGraph/Graphify, and installs Git pre-commit transcript harvesting hooks.
+   - **Global (`memory upgrade --global`)**: Operates on `~/.memory/`. Re-aligns sovereign master profiles (`USER.md`), validates machine-wide constraints, updates global SQLite schemas, heals `~/.local/bin` symlinks, and auto-wires all detected agent platforms workstation-wide.
+3. **Self-Healing Storage Repair**: Recovers missing `.memory/`, `CURRENT.md` constraints, or `USER.md` persona files if corrupted or deleted.
+4. **Coding Agent Re-Discovery**: Scans for newly installed coding agents (Cursor, Claude Code, Windsurf, OpenCode, Codex, Gemini CLI, Hermes, and the rest of the mainstream field) and auto-wires them with zero permissions.
+5. **AST Symbol Graph Re-Indexing**: Re-synchronizes CodeGraph/Graphify symbol caches under `.memory/graph-symbols.json`.
 
 ---
 
-### 📦 Manual Package Manager Upgrades
+### 2️⃣ Updating a Project / Workspace
+To upgrade and synchronize memory inside a specific project repository:
 
-| Toolchain / Runtime | Upgrade Command | Verification |
-| :--- | :--- | :--- |
-| **Bun** (Ultra-Fast) | `bun add -g musememory@latest` | `memory doctor` |
-| **NPM** (Standard Node) | `npm install -g musememory@latest` | `memory doctor` |
-| **PNPM** | `pnpm add -g musememory@latest` | `memory doctor` |
-| **Yarn** | `yarn global add musememory@latest` | `memory doctor` |
-| **NPX** (Zero-Install) | `npx musememory@latest upgrade` | `npx musememory doctor` |
+```bash
+# Update project-level dependency (pinned in package.json)
+bun add musememory@latest
+# or with NPM:
+npm install musememory@latest
+
+# Re-scan and re-wire all local project agent configurations
+memory connect all
+
+# Re-index symbol callgraphs and recompile Markdown wiki
+memory reindex
+memory wiki compile
+
+# Inspect and verify active working constraints
+memory current get
+memory briefing
+```
+
+---
+
+### 3️⃣ Updating the System & Memory Storage (Self-Healing & Migrations)
+To audit, repair, or defragment the underlying SQLite database and knowledge files:
 
 ```bash
-# Check if updates are available without applying (exits 0 if up to date, 1 if registry fails)
-memory upgrade --check
+# Full ecosystem diagnostic and automated schema healing
+memory doctor
 
-# Enforce up-to-date installation in CI pipelines (exits 1 if update is available)
-memory upgrade --check --strict
+# Optimize memory storage: prunes test noise, removes duplicates, runs SQLite VACUUM
+memory optimize
 
-# Preview upgrade actions in dry-run mode
-memory upgrade --dry-run
+# Scan and migrate legacy stores (Letta, Mem0, Beads, Supermemory)
+memory migrate
 
-# Force re-installation and complete platform re-wiring
-memory upgrade --force
+# Check for updates without applying (exits 0 if up to date, 1 if update available)
+memory upgrade --check
 ```
 
 ---
 
 ## 🔄 Complete Lifecycle (Install → Verify → Connect → Uninstall)
 
-Every command works with **zero installation** via `npx musememory <cmd>` (or `bunx musememory <cmd>`). Use plain `memory <cmd>` if installed globally.
+Every command works with **zero installation** via `npx musememory@latest <cmd>` (or `bunx musememory@latest <cmd>`). Use plain `memory <cmd>` if installed globally.
 
 ### 1️⃣ Install & Auto-Wire
 ```bash
 # Full setup: init .memory/, detect agents, wire MCP, scan for migratable stores
-npx musememory install
+npx musememory@latest install
 
 # Initialize workspace only (no agent wiring)
-npx musememory init
+npx musememory@latest init
 ```
 
 ### 2️⃣ Verify & Health Check
 ```bash
 # Comprehensive ecosystem diagnostic (storage, schemas, secrets, MCP wiring)
-npx musememory doctor
+npx musememory@latest doctor
 
 # Memory store breakdown and active briefing
-npx musememory stats
-npx musememory briefing
+npx musememory@latest stats
+npx musememory@latest briefing
 ```
 
 ### 3️⃣ Connect Coding Agents (the majority of platforms)
 ```bash
 # Scan workstation for installed AI coding agents
-npx musememory agents
+npx musememory@latest agents
 
 # Auto-wire all detected agents with zero permissions
-npx musememory connect all
+npx musememory@latest connect all
 
 # Wire one specific agent explicitly
-npx musememory connect claude-code
-npx musememory connect cursor
-npx musememory connect antigravity
+npx musememory@latest connect claude-code
+npx musememory@latest connect cursor
+npx musememory@latest connect antigravity
 npx musememory connect windsurf
 npx musememory connect opencode
 
@@ -603,7 +735,7 @@ 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 health                             # 5-pillar health gate with a letter grade (--project P to scope it)
 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

package/claims.json

@@ -1,7 +1,7 @@
 {
   "$comment": "Generated by scripts/generate-claims.ts. Do not hand-edit: test/marketing_claims.test.ts re-derives every value from src/ and fails on drift.",
-  "version": "3.0.2",
-  "mcpTools": 115,
+  "version": "3.3.0",
+  "mcpTools": 119,
   "mcpProfiles": 7,
   "agentPlatforms": 52,
   "migratorProviders": 30,
@@ -14,8 +14,8 @@
     "networkMillis": 300
   },
   "tests": {
-    "count": 1354,
-    "assertions": 6172,
-    "files": 206
+    "count": 1528,
+    "assertions": 7303,
+    "files": 241
   }
 }