musememory 2.3.0 → 3.0.1

package/.agents/context/current.md

@@ -1,7 +1,201 @@
 # 📍 Current Shipped State & Active Invariants
 
-> **Version**: `v2.3.0`  
-> **Status**: Feature Release (Autonomous Memory Optimizer, UI Dashboard Controls & Concurrent Multi-Agent Workstream Tracking)
+> **Version**: `v3.0.1`  
+> **Status**: Patch Release — correctness fixes from the cross-file invariant audit, machine-verified published claims, and the website redesign.
+
+---
+
+## 🔬 Latest Session — Audit, Documentation & Website Redesign (2026-10-21)
+
+A cross-file invariant audit, a documentation audit, and a full website
+redesign landed together. Everything below is verified by the test suite.
+
+### Code fixes (all regression-tested)
+
+- **Prompt-injection bypass closed (BLOCKER)**: `setCurrent()` in `src/governor.ts` now sanitises injected context blocks before writing `CURRENT.md`, and the session-handoff discovery line in `src/mcp.ts` is sanitised too. Previously only the *stored memory* was sanitised (by `propose()`), so a `memory_capture(type="constraint")` could persist an injection that was replayed into every later prompt. Fixes T-110's stated scope. Cover: `test/audit_blocker_regressions.test.ts`.
+- **Store could fail its own schema (BLOCKER)**: `schema.json` had `additionalProperties: false` but omitted `stale_embedder`, a flag the embedder writes onto entries. Every entry that failed embedding was reported corrupt by `memory validate`, `memory doctor` and `memory verify --strict`.
+- **Bi-temporal queries served the wrong snapshot (BLOCKER)**: the L1 context cache key omitted `as_of` (and the include/type/tag flags), so a "what did we believe in Q1?" query could be answered from a 30-second-old current-state cache entry.
+- **Tiered context dropped `as_of` (BLOCKER)**: `get_context(tier=1, as_of=...)` returned the current state while the untiered path returned the historical one. Both branches now forward `as_of` and `depth`.
+- **Access counter never accumulated (BLOCKER)**: `readEntry()` re-inserted the YAML mirror over the SQLite row, resetting `access_count` to its baseline on every read. The counter fed the access-frequency ranking axis, the LangMem frequency axis and the retention half-life — all were permanently starved. The database row is now authoritative for the counter.
+- **Tier token budget was declared but never enforced**: `resolveTierBudget()` was exported and documented but never called, so Tier 0 emitted 327 tokens against a 200-token budget. The budget now bounds the rendered output and reports what it dropped.
+- **MCP server advertised version `1.6.0`** while the package was at `3.0.0`. The version now comes from `package.json` (`src/version.ts`).
+- **Undiscoverable tools**: `memory_recall`, `memory_get_constraints` and `memory_set_constraints` were callable but absent from `ListTools`. All three are now registered.
+- **Undeclared destructive flags**: `memory_delete` honoured undocumented `apply`/`force` aliases that silently disabled the dry-run default. Only the declared `dry_run` and `confirm` can now disable it.
+- **Snapshot restore had no path containment**: `restoreSnapshotRing()` now resolves strictly inside `.memory/snapshots/`.
+- **`"checkpoint" as any`**: the audit operation is now a declared member of the `AuditOperation` union.
+- **Corroboration predicate de-duplicated**: the 13-line "is this source synthetic" predicate existed in two files. The predicate is now shared (`src/quality/corroboration.ts`); the two *bars* it feeds stay deliberately different and are documented as such.
+- **Title/tag limits declared but not used**: `MAX_TITLE_LENGTH` and `MAX_TAGS` existed while the enforced values were magic numbers. The store and harvester now use the constants, and the draft-title limit is declared as `MAX_DRAFT_TITLE_LENGTH`.
+
+### Published-claim integrity (new)
+
+`scripts/generate-claims.ts` derives every countable claim from `src/` and
+writes `claims.json`; `scripts/generate-cli-reference.ts` writes
+`docs/cli-reference.md` and `docs/mcp-tool-matrix.json`. The website imports
+`claims.json` instead of hard-coding figures.
+
+This exists because the site advertised **80+ coding agents** (real: 52),
+**45+ credential shapes** (real: 8 rule families) and **69 tools across 6
+profiles** (real: 115 across 7), while the README was already honest at 52.
+`test/marketing_claims.test.ts` now fails the build on any drift, on any
+stale figure in the published prose, and on any agent-facing document that
+names a tool which does not exist.
+
+### Documentation
+
+- `docs/agent-reference.md` — new: the agent contract (install, layout, mandatory session protocol, trust gates, failure semantics).
+- `docs/cli-reference.md` — new: generated CLI + MCP reference.
+- `docs/roadmap.md` — new: the sprint board, moved out of the README.
+- `README.md` — restructured: 60-second start, "How it works", "Where your memory lives", a documentation map that separates human docs from agent docs, and a 54KB → 39KB reduction.
+- `.agents/context/product.md` — rewritten against the live registry; it previously named six tools that do not exist.
+- `.agents/standards/frontend-astro.md` — rewritten to match this repo's actual stack (static output, plain CSS, no SSR adapter, no Tailwind, no Motion.dev).
+
+### Website
+
+- Redesigned `apps/website`: shared `Nav`/`Footer`/`Logo` components (the 404 page previously had no navigation at all), a real mobile menu (the nav links were hidden below 860px with no replacement), full SEO head (canonical, OG, Twitter, icons, manifest, skip link), a new "Your memory is a folder" section, and a capability grid that replaces eight long editorial bands.
+- New brand system: a redesigned monogram (the previous mark read as a zigzag, not an "M"), favicon, Apple touch icon, PWA icons, OG card, Twitter card, README banner — all generated deterministically with resvg from the fonts already vendored in the repo.
+- New agent-readable layer: `llms.txt` and `llms-full.txt`, generated from the built HTML.
+- Fixed two real defects the audits caught: a `scrollable-region-focusable` axe failure on `/docs`, and a reveal runtime that stranded any `.reveal` taller than the viewport (the observer used a ratio threshold).
+
+---
+
+## ⏭️ Next Up (Post-Wave 22 Focus)
+- **Production-Grade Showcase Demo**: Re-record high-fidelity terminal demo video/GIF reflecting v3.0.0 capabilities (failure attribution, HOT.md compounding, memory branch/checkout, MCP context recall) to replace removed legacy demo.
+- **Wave 23**: Review next backlog items from `.agents/context/ticket-plan.md` (e.g. Hebbian co-activation retrieval expansion, query-seeded PPR restart set, retrieval weight auto-tuner, and contradiction engine calibration).
+- **Consolidate the remaining duplicated tables** (deferred from this session as behaviour-changing; full detail with exact locations in [`docs/roadmap.md`](../../docs/roadmap.md) → *Engineering debt*): the three divergent per-type TTL tables in `src/retention.ts`, the eight separate token estimators, the divergent limit-clamping ceilings across retrieval paths, and the remaining zero-caller exports.
+- **Remove the legacy `web/` directory** — done in this session. It was a second, hand-written copy of the site that `apps/website/` superseded; keeping it was the same "second copy that gets forgotten" failure mode this session fixed everywhere else.
+
+---
+
+## 🏁 Recently Landed Waves (Verified on `dev`)
+- [x] **Wave 22: Failure Attribution, Negative Memory Mining & Retrieval Compounding**:
+  - `T-313`: Scoped failure attribution matching code anchors (`file_path`, `symbol_name`), affected paths, and reproduction commands; session-deduplicated strikes (max 1/session); dual-decay strike counter (2 clean runs or 30 days without failure); constitutional immunity protecting constraints, timeless memories, and salience $\ge 0.95$ from auto-dispute (`test/failure_attribution.test.ts`, commit `41feec4`, `3b270b5`).
+  - `T-144`: Trajectory fix-pair mining discovering negative memories (`AVOID: ...`) from *Error ➔ Remediation ➔ No Recurrence* observation sequences with affinity filters excluding non-mutating commands (`ls`, `cat`), dynamic line number normalization, Vibeguard secret scrubbing, and session volume cap of max 3 candidates (`test/fix_pair_mining.test.ts`, commit `cc4b5c5`).
+  - `T-314`: Source-tagged recall hits wiring `.memory/HOT.md` candidates into retrieval ranking with sub-millisecond memoized `mtime` cache, origin tagging (`source_channels: ("hot" | "fts" | "vector" | "tree" | "distilled")[]`), relevance-gated `sourceBonus` (+0.20), and explainability tokens (`source:hot`, `source:fts`) (`test/source_tagging_frequency.test.ts`, commit `f9f6a93`).
+  - `T-315`: LangMem logarithmic frequency rank curve ($0.25 \times \frac{\ln(1 + \text{effectiveCount})}{\ln(1 + 50)}$) replacing unbounded linear frequency scoring; weights verified memory applications $2\times$ over passive context loads; 7-day recency bonus (+0.05) capped at 0.30; outputs `freq:high` tokens (`test/source_tagging_frequency.test.ts`, commit `f3c8f1d`).
+- [x] **Wave 21: LifeOS Distillation, Mutation Safety & Knowledge Routing**:
+  - `T-050`: Overnight & in-lock mutation safety guards (`verifyMutationSafety`, `MutationSafetyError`, `ESUSPECT_SHRINK`, `ESUSPECT_EROSION`, `allowDrastic`) preventing accidental bulk erasure or semantic erosion during compaction/governance (`test/mutation_guards.test.ts`, commit `439e31c`).
+  - `T-177`: Pre-mutation 30-snapshot rolling ring buffer (`captureSnapshotRing`, `listSnapshotRing`, `restoreSnapshotRing`) with zero resident daemons in `.memory/snapshots/` before write transactions and compaction handoffs (`test/snapshot_ring.test.ts`, commit `76c58eb`).
+  - `T-324`: Diff-preserving `CURRENT.md` checkpoint merge semantics (`parseCurrentConstraints`, `mergeCurrentConstraints`), preventing mid-session hand-added constraints from being overwritten (`test/current_compaction_guard.test.ts`, commit `f1a4756`).
+  - Multi-Channel Distillation Router: Distills verified memories across `system` (rules/fixes), `content` (architecture concepts), and `health` (contradictions/staleness) lanes with SHA-256 state deduplication (`.memory/distill_state.json`) and draft generation (`.agents/drafts/`), exposed via `distill-route` CLI and `memory_distill_route` MCP tool (`test/distill_router.test.ts`, `test/mcp_distill_route.test.ts`, commits `c6badf1`, `e634bdb`).
+- [x] **Wave 20: Quality Telemetry, Honesty Gates & Retrieval Fault Signals**:
+  - `T-127`: Recall→usage telemetry join (`usage_rate` feeds ROI) (PR #291, Closes #290)
+  - `T-128`: `[DRAFT]` marking with separate confident-answer key (PR #293, Closes #292)
+  - `T-129`: Config-honesty AST audit (`auditConfigHonesty`, WIRED/DORMANT/UNREAD, build-failing) (PR #295, Closes #294)
+  - `T-130`: Storage-version compat tests in CI matrix (`test/storage_version_compat.test.ts`, `schema_versions.json`) (PR #297, Closes #296)
+  - `T-131`: Honest benchmark labels (measured-vs-claimed) on all published numbers (PR #299, Closes #298)
+  - `T-132`: Constitution contract: rules injected first, trim-exempt, no write tool (PR #301, Closes #300)
+  - `T-133`: `degraded − notes` fault signal (`degraded_notes`, `formatDegradedFaultNotice`) (PR #303, Closes #302)
+  - `T-134`: Ground-moved reporting for anchors (silent when undeterminable) (PR #305, Closes #304)
+  - `T-135`: Tiered retrieval ladder labeling loosened matches (`executeRetrievalLadder`, `formatLoosenedBadge`) (PR #307, Closes #306)
+- [x] **Wave 19: Scoring Refinements & Abstract Sidecars**:
+  - `T-118`: Query-intent bias multipliers (`detectQueryIntent`, `computeIntentMultiplier`, `taskIntent`) (PR #274, Closes #273)
+  - `T-119`: `effective_score = base × reinforcement × decay` with utility reinforcement boosts and floor limits (PR #276, Closes #275)
+  - `T-120`: Reciprocal Rank Fusion (RRF) weight tuning + A/B variant presets (control/A vs treatment/B) (PR #278, Closes #277)
+  - `T-121`: Typed drop/keep reasons per candidate with granular audit tokens (PR #280, Closes #279)
+  - `T-122`: Clean-room MIT L0 (<=120 chars) and structured L1 abstract sidecars with disk and SQLite caching (PR #282, Closes #281)
+  - `T-123`: Ratio-batched sidecar refresh (`getSidecarStaleness`, `refreshSidecarsRatioBatched`) (PR #284, Closes #283)
+  - `T-124`: Resident INDEX route-map in orchestrator (`buildResidentRouteMap`, `matchResidentRoutes`, `INDEX.json`) (PR #286, Closes #285)
+  - `T-125`: Tier budgets as named constants with provenance (`TIER_BUDGET_PROVENANCE`, `resolveTierBudget`) (PR #288, Closes #287)
+- [x] **Wave 18: Ingestion, Suppression & Curation Gates**:
+  - `T-106`: Curator concept: agent appends empirical evidence/application outcomes, deterministic promotion decides records (PR #256, Closes #255)
+  - `T-107`: Two-tier promotion staging (`pending_promotions.json`) and session-end atomic flush (`memory_flush_pending`) (PR #258, Closes #257)
+  - `T-108`: Re-injection suppression per session with 6-turn LRU window and constraint/timeless exemptions (PR #260, Closes #259)
+  - `T-109`: Self-echo suppression via capture-side provenance within 10-minute horizon (PR #262, Closes #261)
+  - `T-110`: `<memory-context>` and injected block sanitization before propose and harvest (PR #264, Closes #263)
+  - `T-111`: Seen-chunk TTL suppression in retrieval with 5-minute window and chunk key tracking (PR #266, Closes #265)
+  - `T-112`: Topic-overlap >0.6 prefetch skip in retrieval caching context packs on consecutive queries (PR #268, Closes #267)
+  - `T-113`: Trivial-prompt gate bypassing recall on conversational greetings while preserving constraints (PR #270, Closes #269)
+- [x] **Wave 17: Packing, Graph, Lineage & Provenance**:
+  - `T-095`: `linked_memory_ids` write-time graph edges auto-seeded during capture and indexed in SQLite (PR #239, Closes #238)
+  - `T-096`: HyAtlas supersede-not-delete lifecycle marking `valid_to`/`valid_to_exact` with hidden-count-aware over-fetching (PR #241, Closes #240)
+  - `T-097`: `prefer_observations` recall-time dedup scoped to top-2×budget candidate window with Jaccard threshold $\ge 0.65$ and $+0.10$ veracity boost (PR #243, Closes #242)
+  - `T-098`: Progressive multi-hop wikilink expansion after reciprocal rank fusion (`extractWikilinks`, `expandFusedWikilinks`) with token budget bounds (PR #245, Closes #244)
+  - `T-099`: Semantic `fact_provenance` append-only SQLite table with triple-unique index `(entity, relation, target)` (PR #247, Closes #246)
+  - `T-100`: First-class lineage foreign keys `supersedes_id` and `conflicts_with_id` in SQLite schema and indexing (PR #249, Closes #248)
+  - `T-101`: Lineage BFS DAG walker (`walkLineageBfs`) traversing ancestors, descendants, conflicts, and links with cycle prevention (PR #251, Closes #250)
+  - `T-102`: Tamper-evident cryptographic hash-chained audit ledger with per-day salt rotation (`audit_salts.json`) and session Merkle checkpoints (`createSessionMerkleCheckpoint`) (PR #253, Closes #252)
+- [x] **Wave 16: Temporal Transitions, Contradiction Engine & Verbs**:
+  - `T-082`: `valid_to_exact` flag on transitions stamping exact historical cessation boundaries vs runtime transitions (PR #219, Closes #218)
+  - `T-083`: `as_of` queries returning `{results, undetermined}` without date invention (PR #221, Closes #220)
+  - `T-084`: Five-verb lifecycle (`change`, `end`, `correct`, `revert`, `forget` with GDPR hard/soft tombstones) and typed audit logging (PR #223, Closes #222)
+  - `T-085`: `searchTemporal(atTime)` default-excluding superseded knowledge while returning undetermined boundary candidates (PR #225, Closes #224)
+  - `T-086`: Keep-both `conflicts` SQLite table (Migration v6) preserving contradictions without deletion (PR #227, Closes #226)
+  - `T-087`: Scoped invalidation requiring semantic `(entity, relation, target, scope)` alignment to eliminate Graphiti #1728 false-positive conflicts across environments (PR #229, Closes #228)
+  - `T-088`: Federation handshake protocol for mesh-mode conflict deduplication and resolution propagation (`supersede`, `keep_both`, `historical`, `reject`) (PR #231, Closes #230)
+  - `T-089`: Provenance veracity rank weighting (`user` 1.0, `agent` 0.7, `external` 0.5, `system` 0.3) with tie-breaker bonuses and `minVeracity` filtering (PR #233, Closes #232)
+  - `T-090`: `src_ts` evidence-age stamping (Migration v7) ensuring memory freshness cannot exceed underlying source document age (PR #235, Closes #234)
+- [x] **Wave 15: Expiry, Decay & Confidence Hardening**:
+  - `T-072`: Tokenizer-matched abstention gate (`evaluateAbstentionGate`) matching FTS5 Unicode61 boundary rules (PR #200, Closes #199)
+  - `T-073`: `no_confident_match` result mode across `queryContext`, `formatPromptContext`, and MCP `get_context`/`search` (PR #202, Closes #201)
+  - `T-074`: Materialized `decay_score` in SQLite memories table with importance-gated half-life scaling (0.4x to 3.0x) (PR #204, Closes #203)
+  - `T-076`: Bayesian corroboration confidence $C(n) = 1 - 0.7^n$ scaling from initial observation to asymptotic certainty (PR #206, Closes #205)
+  - `T-077`: Trust-tier-keyed half-life (T1 365d → T4 30d) defending against OWASP ASI06 memory poisoning (PR #208, Closes #207)
+  - `T-078`: Per-type admission `expires_at` defaults (fix 90d, op 180d, arch 365d, disc 30d, pref/constraint null) with pin exemptions (PR #210, Closes #209)
+  - `T-079`: Stamped `status: 'expired'`, `expired_at` timestamp, and `expired_by` rule tracking with pin-protected sweeps (PR #212, Closes #211)
+  - `T-080`: Pin-capable first-match-wins declarative expiry policy YAML engine (`.memory/expiry.yaml`) in store admission and sweeps (PR #214, Closes #213)
+  - `T-081`: Optional Weibull per-type decay curves $R(t) = \exp(-(t/\lambda)^k)$ preserving $R(t_{1/2}) = 0.5$ invariant across all shape $k$ values (PR #216, Closes #215)
+- [x] **Wave 14: Invalidation, Attribution & Ranking Rigor**:
+  - `T-302`: `memory_capture` full propose options passthrough (evidence, source, verification, dedup, valid_from/to, due_at, expires_at, salience, trust, mem_path, idempotency_key, source_ids) (PR #188, Closes #187)
+  - `T-304`: Incremental vector index synchronization on `save()` (`upsertIndexEntry`) and `deleteEntry()` (`removeIndexEntry`) (PR #190, Closes #189)
+  - `T-307`: Bounded Hebbian plasticity co-activation (8 seeds, 30 edges/node, 500 nodes max), atomic `.tmp` swap, candidate expansion in retrieval (PR #192, Closes #191)
+  - `T-309`: IDF-weighted symbol matching downweighting generic verbs (`get`, `set`) to 0.05 and rewarding distinctive compound identifiers (`SessionManager`, `auth_token`) with 1.0 (PR #194, Closes #193)
+  - `T-310`: Word-boundary token matching (`matchesWordBoundary`) preventing substring false positives (`race⊂trace`, `port⊂report`, `lock⊂deadlock`) (PR #196, Closes #195)
+  - `T-312`: FTS failure degraded signal distinguishing genuine zero-match from SQLite execution errors with loud `[FTS5_DEGRADED]` logging (PR #198, Closes #197)
+- [x] **Wave 13: Retrieval Performance & Store Hot-Paths**:
+  - `T-021`: Memoized runtime file verification in ranking hot path (PR #172, Closes #171)
+  - `T-022`: Precomputed token sets per memory to drop per-query retokenization (PR #174, Closes #173)
+  - `T-023`: `openStore` dirty-gate with SQLite fingerprinting to skip redundant wiki recompiles & CURRENT.md sync (PR #176, Closes #175)
+  - `T-028`: `recordRetrievals` wiring into `get_context` deferred writes & `memory_recall` (PR #178, Closes #177)
+  - `T-029`: `touchActivity` wiring into `save()` with 1-second throttling (PR #180, Closes #179)
+  - `T-062`: Clamp model-supplied `limit` values across all retrieval engines and MCP handlers (PR #182, Closes #181)
+  - `T-063`: Dry-run-by-default and point-ID-only validation for destructive ops (PR #184, Closes #183)
+  - `T-064`: Read-path `stale: true` and `from_cache: boolean` provenance tags for degraded reads (PR #186, Closes #185)
+- [x] **Wave 12: Daemon Reliability, Upgrade Signals & Living Decisions**:
+  - `T-345`: Daemon server.on("error") collision handling, /publish origin validation, active socket disposal on close (PR #156, Closes #155)
+  - `T-346`: Upgrade CLI exit codes with --check registry error truthfulness, --fail-on-update, and --strict (PR #158, Closes #157)
+  - `T-350`: Drift endpoint symlink throwIfNoEntry guard, precomputed lowercase corpus, and pure read path (PR #160, Closes #159)
+  - `T-352`: ADR status mapping (rejected -> stale, proposed -> candidate) and save-before-supersede atomicity (PR #162, Closes #161)
+  - `T-356`: PageIndex search maxDepth node pruning and 3-tier disclosureDepth (L1/L2/L3) (PR #164, Closes #163)
+  - `T-358`: Daemon port integer validation (0-65535) and SIGINT/SIGTERM graceful socket shutdown (PR #166, Closes #165)
+  - `T-359`: Upgrade audit honesty (scanSecrets in Vibeguard step, distinct agent wiring, RepairResult.errors) (PR #168, Closes #167)
+  - `T-365`: Anchor base normalization at write time and unified multi-root path resolution in drift and mesh contracts (PR #170, Closes #169)
+- [x] **Wave 0: Pre-Flight Integrity & Baseline Fixes**: `T-402`, `T-403`, `T-404`, `T-401`, `T-370`.
+- [x] **Wave 1: Storage Engine, Outbox & Concurrency**: `T-041`, `T-042`, `T-044`, `T-038`, `T-039`, `T-040`, `T-055`, `T-056`.
+- [x] **Wave 2: Write Admission, Trust & Anti-Poisoning**: `T-104` (scoreRetain 0.3 gate), `T-075` (trust tiers + withholding), `T-058`/`T-059` (read-path re-validation), `T-103` (FTS index-time secret redaction), `T-105`/`T-105b` (corroboration & syntax promotion gates), `T-391` (citation validation against live registry).
+- [x] **Wave 3: Retrieval Quality, Ranking & Token Economics**: `T-035` (iterative safeMax/safeMin scale safety), `T-036` (in-memory IDF caching via WeakMap), `T-037` (drop redundant full-list scans via countMemories), `T-060` (safe FTS5 query token escaping), `T-061` (compound-token expansion), `T-070` (IDF-weighted relevance gate 0.3), `T-114` (Soft-OR evidence fusion formula), `T-115` (low_discrimination conditional reranking), `T-117` (watermark staleness tracking), `T-126` (deterministic why_retrieved reason tokens), and priority knapsack packing for negative anti-pattern lessons.
+- [x] **Wave 4: Compaction, Ephemeral Observations & Distillation**: `T-305` (distillation body cap 1500 chars), `T-306` (atomic write + rotation + 256KB size cap for observations), `T-045` (`on_pre_compress` hook + `extractInvariantsPreCompress`), `T-047` (never-empty checkpoint contract), `T-046` (persisted SHA-256 digest dedup store), `T-053` (honest dual-measure token accounting), `T-054` (refuse-incomplete digest contract), `T-091` (compact context-pack formatter), `T-092` (never-drop context manifest TOC), `T-093` (truncation hierarchy with `[N omitted — budget M]`), `T-094` (reserved slots for USER.md profile).
+- [x] **Wave 5: Security Hardening & UI Protection**: `T-002`/`T-003` (UI XSS escaping for `p.title`, `p.slug`, `r.entry_id`, `r.actor`, checkpoints, and details), `T-004` (UI optimizer gate dry-run default + localhost/token check), `T-380` (unit test suite for `escapeHtml`), `T-388` (Hook SessionStart `<muse-memory>` block sanitization), `T-389` (`recordObservation` metadata JSON credential scanning), `T-399` (routine step allowlist, flag rejection, and depth > 5 re-entrancy recursion guard), `T-400` (UI read routes `/api/memories` and `/api/snapshot` projection allowlist).
+- [x] **Wave 6: Semantic Embeddings & Eval Harness**: `T-381` (llama-cpp wire protocol embeddings spike), `T-071` (dual calibrated thresholds: `SEMANTIC_COSINE_MIN_THRESHOLD = 0.30`, `BM25_MIN_THRESHOLD = 0.25`), `T-136` (engine fingerprint pinning `model|dims|endpoint`), `T-137` (FTS5-floor / vector-upgrade degradation path), `T-138` (in-process brute-force cosine over SQLite `BLOB` raw floats), `T-139` (`stale_embedder` stamp on reindex misses and doctor reporting), `T-140` (recall-set grading: must-return, distractor discrimination, abstention, noise-as-failure), `T-141` (frozen benchmark corpus drift discipline), `T-142` (p50/p95/p99 latency reporting beside recall scores), `T-143` (fixture promotion requires usage telemetry).
+- [x] **Wave 7: Team Slice (On-Demand / Opt-In)**: `T-150` (MCP Streamable HTTP transport 2025-06-18 spec, PR #84, Closes #83), `T-151` (Origin validation + session ID + protocol version headers, PR #86, Closes #85), `T-386` (Bearer token auth with per-peer allowlist, PR #88, Closes #87), `T-153` (Multi-DB topology: shared team store `team.db` + per-member local DBs, PR #90, Closes #89), `T-387` (Member wiring docs, client config recipes, and shared vs personal scoping policy, PR #92, Closes #91).
+- [x] **Wave 8: Residual Surfaces Audit**: `T-392` (Embedder URL SSRF & metadata IP validator, PR #94, Closes #93), `T-393` (Claims & provenance array/metadata secret scan gaps, PR #96, Closes #95), `T-394` (Enforce decorative settings `mcp.enabledTools` allowlist & `imports.secretScanEnabled`, PR #98, Closes #97), `T-395` (Upgrade failure signal in `playPandaLoader` and non-zero exit, PR #100, Closes #99), `T-396` (`healBunGlobalConfig` safety, `.bak` backup, error surfacing, and opt-in gate, PR #102, Closes #101), `T-397` (`getLatestNpmVersion` command injection defense with `execFileSync`, PR #104, Closes #103), `T-398` (`memory_harvest` schema and handler alignment with validation error on missing text, PR #106, Closes #105).
+- [x] **Wave 9: Runtime Integrity, Seams & Drift Elimination**:
+  - `T-010`: Align profile tool definitions with live registered MCP tools (PR #112, Closes #111)
+  - `T-011`: Align ALL_MEMORY_TOOLS with live registered MCP tools (PR #114, Closes #113)
+  - `T-012`: Delete dead zero-caller `maybeAutoOptimize` (PR #116, Closes #115)
+  - `T-364`: Unique-ID seam collision prevention with crypto.randomUUID in ADRs & PageIndex (PR #118, Closes #117)
+  - `T-341`: Enforce dryRun in upgrade repairInstallation (PR #120, Closes #119)
+  - `T-343`: Guard against malformed Host header crashes with HTTP 400 (PR #122, Closes #121)
+  - `T-344`: Reject Origin: null in CORS and CSRF defense (PR #124, Closes #123)
+  - `T-361`: Sanitize priority badge class & escape item.priority in remediation UI (PR #126, Closes #125)
+- [x] **Wave 10: CLI Rigor, Governance & Hardened Parsers**:
+  - `T-013`: Formally retire unreachable LSP tier while keeping provider slot in chain signature (PR #128, Closes #127)
+  - `T-014`: Delete dead registry methods, registerProvider, and unused governor exports (PR #130, Closes #129)
+  - `T-347`: UI Port contract validation & auto-increment on collision when port omitted (PR #132, Closes #131)
+  - `T-353`: Wiki frontmatter YAML scalar escaping via JSON.stringify (PR #134, Closes #133)
+  - `T-354`: CLI argument parsing hardening (POSIX `--` terminator, split on first `=`, negative values) (PR #136, Closes #135)
+  - `T-360`: Clean Web Studio keep-alive socket destruction & numeric parameter clamping (PR #138, Closes #137)
+- [x] **Wave 11: Migrator Quarantine, Anti-Poisoning & Validation Hardening**:
+  - `T-366`: Intake schema validation, candidate quarantine, and strip self-certified verification (PR #140, Closes #139)
+  - `T-338`: Strip unearned verification level from external agentmemory records (PR #142, Closes #141)
+  - `T-339`: Prevent Letta core memory (human/persona) prompt injection into CURRENT.md (PR #144, Closes #143)
+  - `T-340`: Generic adapter intake sanitization (reject package.json/configs, bound document size, no loose Object.values) (PR #146, Closes #145)
+  - `T-348`: Path fallback expansion and empty directory defense to enable truthful skipped status (PR #148, Closes #147)
+  - `T-349`: Track deduplication metrics and enforce within-batch dedup in dry runs (PR #150, Closes #149)
+  - `T-357`: Memory status validation and normalizeMemoryStatus (default omitted isLatest to candidate) (PR #152, Closes #151)
+  - `T-362`: Remove dead global config and tighten normalizeMemoryType against loose op substring (PR #154, Closes #153)
+- [x] **Team Onboarding & Documentation**: `docs(team)` Dedicated team getting started guide in `docs/team-getting-started.md` and README team setup section (PR #108, Closes #107).
+- [x] **User Documentation Suite**: `docs(user)` Core Concepts (`docs/concepts.md` via ACCA) and Developer Daily User Guide (`docs/user-guide.md` via QUEST) with README documentation hub (PR #110, Closes #109).
+- **Full Roadmap**: `.agents/context/roadmap.md` and detailed audit report `.agents/artifacts/audit-and-realigned-roadmap-20261015.md`.
 
 ---
 
@@ -38,14 +232,39 @@
 29. **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`).
 30. **Interactive Code Anchor Reconciler**: Audits and repairs code anchors across memories, pruning dead references and updating structural hashes (`memory reconcile` / `muse_reconcile_anchors`).
 31. **Latency & Quality Telemetry Suite**: Benchmarks microsecond hot caches, FTS5 BM25 search, knapsack token packing, and ROI in a clean ASCII scoreboard (`memory benchmark`).
-32. **Linus-Style Architectural Hardening (v2.2.1)**: Elimination of shell command injection via `execFileSync`, concurrency-safe `PRAGMA busy_timeout = 5000` on SQLite WAL mode, O(N) stat storm elimination in `list(store)`, structured warnings on YAML dual-write failures, and tightened word-boundary/code-anchor ADR matching.
+32. **Linus-Style Architectural Hardening (v2.2.1, completed by T-001 #58 + T-363 #59)**: template-gated command execution (no shell — memory selects which test file, never what code) replacing the earlier `execFileSync` claim, `resolveWithin`/`resolveExternal` path containment, concurrency-safe `PRAGMA busy_timeout = 5000` on SQLite WAL mode, O(N) stat storm elimination in `list(store)`, structured warnings on YAML dual-write failures, tightened word-boundary/code-anchor ADR matching, and harness-independent hook install (`.agents/` default, `--harness` opt-in). **Verification oracle templates** (`src/verify.ts: checkTemplate`) — only three shapes run: `bun test <relative *.test.ts|*.spec.js>` (must resolve in-root), `bunx tsc --noEmit` (verbatim), `node --check <relative path>`; `-e`/`--eval`-style flags, non-test script paths and bare binaries are refused, nothing executes, and the refusal is audit-logged as `verify_refused`. **Path containment** — `resolveWithin` guards wiki/pageindex-family paths (strict containment: no absolute segments, no `..` escape), `resolveExternal` is the deliberate opt-out for intentionally-external pool/mesh directories, and PageIndex `indexId` must be a bare filename.
 33. **Autonomous Memory Optimizer & Auto-Cadence Engine (v2.3.0)**: Multi-factor noise and junk pruning engine with zero-daemon auto-cadence (every 7 days or after 48h idle), SQLite WAL defragmentation (`VACUUM;` + `PRAGMA optimize;`), CLI command `memory optimize`, and dashboard "⚡ Optimize" button.
 34. **Concurrent Multi-Agent Workstream Tracking & Clean `CURRENT.md` (v2.3.0)**: Live `AgentWorkstream` tracking table in `CURRENT.md` enabling multi-agent swarms across separate chat sessions to coordinate active tasks and target scopes; injected into prompt context (`formatPromptContext`, `resolveMuseContext`); sanitized single-pane executive summary for humans with strict grounding rules for agents.
+35. **Write-Time Citation Verification (v2.3.1, GAP-1)**: Kage-pattern trust gate — every code anchor is verified against the live filesystem before a memory write is admitted. Hallucinated citations (file/symbol does not exist) reject the write under the default `fail_fast` policy; drift is flagged and stamped; all decisions audited (`src/anchors/verify-write.ts`, enforced in `attachAnchorToMemory` + `memory_anchor_create` MCP tool).
+36. **Recall-Time Freshness Gate (v2.3.1, GAP-3)**: Memories whose anchors drifted or whose cited files/symbols no longer exist are **withheld from `muse_context` by default** and reported via `withheld_memories` + `freshness_notice` (never silently served). Opt-in `include_drifted: true` returns them with `⚠ FRESHNESS` provenance warnings. Per-`(path, symbol, mtime)` memoized verdicts keep recall sub-ms (`src/orchestrator/freshness.ts`).  37. **Claude Code Lifecycle Hook Pack (v2.3.1, GAP-2)**: Hands-free memory — `SessionStart` injects constraints + top-5 memories before the agent's first turn, `PostToolUse` captures Vibeguard-scanned observations, `Stop` distills the session into candidate memories. Installed via `memory hooks install` or `memory connect --with-hooks`; idempotent, preserves user hooks, every handler fail-open (`src/hooks/pack.ts`).
+  38. **Professional Website Copy Pass (v2.3.1)**: Full content-mode rewrite of `apps/website` — AIDA-structured landing copy anchored to a developer reader with one primary action (`npx musememory connect`); FAQPage + SoftwareApplication JSON-LD for AEO; anti-puffery scrub (all claims verifiable: sub-2ms, <50µs, 80+, 24+, 69 tools, 527 tests, 0 daemons); corrected stale 498/86 stats; fixed `BASE_URL` link bug (`/musememorydocs` missing slash) site-wide and duplicated OG meta in Base.astro; compare page heading hierarchy fixed (h2→h1). Second pass fixed real defects found by a new responsive visual audit (`scripts/audit-visual.ts`, 375/768/1280 × 3 pages): motion runtime was silently dead (`initMotion` returned `<style>+<script>` markup nested inside the layout's `<script>` — now returns raw JS only; `.reveal` opacity CSS lives solely in global.css, so no-JS users see all content); docs grid overflow fixed (`.docs-body { min-width: 0 }`); decorative orbs hidden ≤640px + `html { overflow-x: clip }`; prose links underlined (WCAG 1.4.1, caught once audit server served real /docs + /compare instead of the 404 page — both audit servers now resolve directory paths GitHub-Pages style). Gate: 4-page build + WCAG 2.2 AA audit (24/24 pairs, axe clean on all 4 pages) + visual review 9/9 viewports + 527 tests + tsc clean. CI showreel hash reseeded (`public/brand/.showreel-hash`).
+  39. **HyperFrames Showreel (v2.3.1)**: The showreel is a motion-designed composition, not a screen capture — `apps/website/showreel-hf/index.html` (HyperFrames: HTML/CSS + one GSAP timeline on `window.__timelines`, self-hosted Inter/IBM Plex Mono), 4 scenes over 10s with only verifiable numbers (sub-2ms recall, <50µs L0, 0 daemons, 80+ platforms, 527 tests). Built via `bun run site:showreel` (`scripts/build-showreel.ts`: master render → 1280×720 H.264 → poster → ffprobe verify). `hyperframes check` is the composition gate (0 errors, 19/19 WCAG AA); CI hash covers composition+fonts+script and fails deploys on drift (manual dispatch can rebuild in CI). Decision: the HyperFrames *skill bundle* stays uninstalled — safe-skills hard-blocked it twice (prompt-injection, credential-file-pattern flags, judged false-positive-prone but unreviewed); the npm `hyperframes` CLI (devDependency) is used instead with public docs as reference.
+
+  40. **Non-Technical Homepage & 3D Depth System (v2.3.1)**: `apps/website` rewritten for a mixed audience with SEO/AEO structure — question-shaped `h2`s, answer-first quotable blocks, a plain-English glossary (`<dl>` term/definition pairs), and FAQ questions phrased the way a non-user actually asks them. Structured data now covers three types (FAQPage, SoftwareApplication, HowTo) and the site gained `robots.txt` + a hand-written `sitemap.xml` (no new build dependency); the favicon link was root-absolute and 404'd under the `/musememory/` base path (now `BASE_URL`-relative). Layout uses a CSS 3D depth system in `global.css` — perspective scenes, layered `--z` planes, pointer tilt, scroll parallax on a wrapper (never on `.reveal`, since both own `transform`), a clipping marquee band, and a drifting gradient mesh — all disabled under `prefers-reduced-motion` and flattened below 640px. Text sitting on the new lit glass surfaces moved from `--text-faint` to `--text-dim` to hold AA. Two audit fixes: `audit-visual.ts` now skips elements inside a clipping ancestor (marquee tracks are deliberately oversized) and `<pre>` blocks wrap instead of scrolling (`scrollable-region-focusable` was a real axe failure). Gate: 4-page build + 24/24 contrast pairs + axe clean on 4 pages + visual review 9/9 viewports + 527 tests + tsc clean.
+  41. **Template-Gated Test Execution (`T-001`, PR #58)**: Strict template allowlist (`bun test <relative-test>`, `bunx tsc --noEmit`, `node --check <relative-path>`). Direct execution with zero shell invocation; eliminates RCE via memory-stored commands; audit-logged refusals (`verify_refused`).
+  42. **Strict Boundary Path Containment (`T-363`, PR #59)**: `resolveWithin` containment on all wiki, pageindex, pool, and mesh boundary paths, with `resolveExternal` explicit opt-out.
+  43. **Harness-Independent Hook Resolution (`T-390`, PR #61)**: Global standard first (`~/.agents`), explicit `--harness` opt-in.
+  44. **Read-Path Purity Engine (`T-301`, PR #69)**: Asynchronous non-blocking write queue in `mcp.ts` ensuring read operations (`get_context`, `muse_context`) never execute synchronous store mutations.
+  45. **Row-Level Lifecycle & Project Filtering (`T-303`, PR #70)**: `hybridSearch` row filters applied before vector/FTS fusion; eliminates superseded/archived/cross-project leakage at scale (>100 entries).
+  46. **Additive Schema Migrations Framework (`T-368`, PR #71)**: Ordered `MIGRATIONS` array with `PRAGMA user_version` stamps and automatic backfills from existing `data` JSON blobs.
+  47. **Store Invalidation & FTS Parity (`T-020`, `T-024`, `T-025`, `T-026`, PR #73)**: Query cache invalidation on writes, bounded FTS preflight token caps, single-transaction atomic batch writes, and automated FTS-to-row parity audits and repair.
+  48. **Authoritative Retrieval Unification & Unicode Tokenization (`T-308`, `T-311`, PR #74)**: Unified scoring model between `get_context` and `muse_context`; multilingual unicode-aware tokenization across CJK and accented scripts with non-lexical penalties.
+  49. **Tombstones, Memory Restoration & Audit Replay (`T-030`, `T-031`, `T-032`, PR #75)**: Soft-delete tombstone architecture (`deleted_at`, `deleted_by`) with automatic read-path exclusion; `memory restore` CLI and `memory_restore` MCP tool; and ledger rebuild from `audit.jsonl` via `replayFromAudit`.
+  50. **Storage Engine, Outbox State Machine & Concurrency (Wave 1: `T-041`, `T-042`, `T-044`, `T-038`, `T-039`, `T-040`, `T-055`, `T-056`)**: Durable SQLite `outbox` table via migration v3 (`pending` → `processing` → `sent` / `held` / `failed`), 300s stale-lock recovery sweep on store open, single-writer file flock (`.lock`) that fails loud, crash-durable `fsync` on every JSONL audit event, `idempotency_key` unique index with divergent-retry conflict detection, case/whitespace-normalized `content_hash` fast SQLite deduplication, store circuit breaker (5 failures → 120s cooldown → graceful degradation), and `beforeExit`/`closeStore` bounded join (5000ms max) for async write workers.
 
 ---
 
+### Website Competitor-Reference Cleanup (session)
+Removed remaining competitor product names and external comparison links from website content to satisfy the no-competitor-references constraint:
+- `index.astro`: Replaced "Mem0, Letta, AgentMemory…" benchmark note with "legacy memory systems"; replaced FAQ body mentioning those names with "from other memory systems".
+- `compare.astro`: Removed hyperlink to `ai-memory-comparison` project (lists competitors); replaced with capability-only methodology statement.
+- Gate: 527 tests pass, `tsc --noEmit` clean, website build succeeds (4 pages).
+
 ## 🔒 Active System Invariants
 
 - **Zero External Daemons**: All operations must execute in-process via SQLite (`memory.db`) or flat files. Never depend on background servers.
 - **Fail Fast**: Throw loudly on secret detection, invalid schema shapes, or unconfirmed supersessions.
 - **Verification Gate**: Before declaring changes complete, `bun test`, `bun run build`, and `tsc --noEmit` must pass.
+
+## 1. Verified Shipped Reality
+- **2026-10-20**: Wave 21: LifeOS Distillation, Mutation Safety & Knowledge Routing (T-050, T-177, T-324)

package/.agents/context/decisions.md

@@ -23,3 +23,7 @@
 ### ADR-005: Bun-First Runtime & Toolchain
 - **Decision**: Use Bun as the primary test runner, bundler, and local runtime, compiling to portable Node.js binaries for npm distribution.
 - **Rationale**: Instant test iteration (`bun test`) and seamless zero-dependency distribution.
+
+### ADR-006: Harness-Independent Hook Installation (Global Standard First)
+- **Decision**: `memory hooks install` resolves its target as explicit `settingsPath` → explicit `--harness` opt-in → global standard (project `.agents/hooks.json` when a `.agents/` directory exists, otherwise `~/.agents/hooks.json`). A harness path (e.g. `~/.claude/settings.json`) is never auto-selected, and `connectAgent` skips harness-specific agents without an explicit `--harness` opt-in.
+- **Rationale** (principal ruling, 2026-10-15): the runtime is vendor-neutral — hooks must not couple memory to one harness or create a harness directory unprompted. A pre-existing harness settings file does not imply consent; only `--harness claude` does.

package/.agents/context/deep-research-agentic-memory-evolution.md

@@ -0,0 +1,261 @@
+# 🧠 Deep Research Brief: The Evolution of Muse Memory into an Autonomous Agentic Cognitive OS
+
+**Topic**: Evolving Muse Memory into the Next-Generation Agentic Cognitive Memory System  
+**Depth**: Deep (Local scan, ecosystem signals, frontier literature, competitive analysis, architectural specification)  
+**Date**: 2026-09-06  
+**Operating Identity**: Muse (Chief Agency Orchestrator)  
+**Primary Repository**: [`musememory`](../../)  
+
+---
+
+## Executive Summary
+
+Modern AI coding agents face a fundamental cognitive barrier: while models possess massive context windows, **raw context stuffing degrades reasoning quality, wastes tokens, and lacks stateful learning across tasks and sessions**. Current agent memory solutions either act as dumb similarity-vector dumps (Mem0, Supermemory), require heavyweight external daemon infrastructure like Neo4j and Python background services (Zep, Cognee), or remain locked within proprietary walled-garden IDEs (Windsurf, Claude Projects).
+
+Muse Memory currently sets the gold standard for **zero-daemon, file-first, AST code-anchored memory** with SQLite FTS5 BM25, 7-state lifecycle governance, living ADRs, 5-pillar health gates, and inline Vibeguard secret scrubbing across 80+ agent platforms.
+
+This deep research brief establishes the architectural blueprint for **Muse Memory v3.0 & Beyond**. It formalizes the transition from a developer knowledge store into a **complete Agentic Cognitive Operating System** across 6 transformative pillars:
+1. **Tri-Cognitive Memory Architecture**: Incorporating executable **Procedural Playbooks** (`ProceduralMemory`) and **Episodic Causal Horizons** alongside timeless semantic memory, bounded by **Bi-Temporal Validity Windows** and **Ebbinghaus utility decay**.
+2. **AST-Aware Speculative Context & Associative Callgraphs**: In-process SQLite recursive CTE associative multi-hop retrieval (Zero-Daemon HippoRAG) and editor/git-hook speculative pre-flight context pushing.
+3. **Git-Branchable Memories & Agency Multi-Tenant Enclaves**: Branch-scoped memory overlays (`memory branch`) mirroring git lifecycle and cryptographically isolated client enclaves for agency orchestration.
+4. **Test-Driven Memory Reinforcement & Automated Regression Sentry**: Tight integration with test runners (`bun test`, `jest`) to automatically increase memory ROI and flag anti-pattern regressions.
+5. **In-Process Zero-API-Key Local Embeddings**: 100% offline, zero-cloud quantized vector embeddings (FastEmbed / SQLite-Vec) fused via Reciprocal Rank Fusion (RRF).
+6. **Agent Development Environment (ADE) & Meta-Cognitive Self-Reflection**: Tools (`muse_reflect`, `muse_counterfactual`) giving agents introspective self-editing memory control.
+
+---
+
+## 🌐 Competitive Landscape: The 42-Engine Matrix
+
+The landscape of agent memory has expanded dramatically into four distinct architectural camps:
+
+| Category | Typical Providers | Key Strengths | Fundamental Failure Mode vs Muse Memory |
+| :--- | :--- | :--- | :--- |
+| **Local File-First** | Muse Memory, Beads, ByteRover, Kungfu, Windsurf, OpenHands, Mex, SLM | Instant local access, version-controllable, zero cloud bills | Most lack AST code identity, deterministic state machines, or living ADR drift detection |
+| **Graph / Vector DB** | Zep (Graphiti), Mem0, Cognee, Memori, HippoRAG, LightRAG, Pensieve | Entity relationships, multi-hop semantic graph traversal | Heavy infrastructure tax (Neo4j, Docker, Python daemons), lacks code anchor line-invariance |
+| **Agent Harnesses** | Letta (MemGPT), LangMem, A-Mem, GBrain, Rory Plans, Autocontext | Tiered memory (RAM/Recall/Archival), agent self-editing | Framework lock-in (LangChain, Letta runtime), non-standard MCP integration |
+| **Cloud Managed** | Claude Projects, Second Brain Cloudflare, Actx0, Liminary, Mem.ai | Cloud sync, automated background ingestion | Zero secret defense, privacy leak, zero offline CLI access, proprietary lock-in |
+
+### Landmark System Comparisons
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────────────────────────────┐
+│                                    Agent Memory Landscape (2026)                                        │
+│                                                                                                         │
+│                 Heavy Cloud / API Key Required          Zero-Daemon / 100% Local-First                  │
+│               ┌─────────────────────────────────┬──────────────────────────────────────────┐            │
+│               │                                 │                                          │            │
+│  Specialized  │  • Zep / Graphiti               │  • MUSE MEMORY (v2.3+ / v3.0)            │            │
+│  Agent Memory │    (Bi-temporal graph + Neo4j)  │    (SQLite WAL + AST Anchors + Playbooks)│            │
+│  & Cognition  │  • Mem0                         │  • Mex Memory                            │            │
+│               │    (SaaS vector + graph)        │    (Scaffold + Git drift CLI)            │            │
+│               │  • Letta / MemGPT               │  • SuperLocalMemory (SLM)                │            │
+│               │    (Stateful Agent Runtime OS)  │    (7-layer control plane)               │            │
+│               ├─────────────────────────────────┼──────────────────────────────────────────┤            │
+│               │                                 │                                          │            │
+│  Generic RAG  │  • LangMem (LangGraph Store)    │  • LightRAG (NanoVectorDB / NetworkX)    │            │
+│  & Text Dumps │  • Claude Projects Memory       │  • HippoRAG (Academic Python PPR)        │            │
+│               │  • Second Brain (Cloudflare D1) │  • Windsurf / Cursor Rules               │            │
+│               │                                 │                                          │            │
+│               └─────────────────────────────────┴──────────────────────────────────────────┘            │
+└─────────────────────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+1. **Zep (Graphiti)**: Pioneer in bi-temporal knowledge graphs. Solves fact invalidation (e.g. user moved from London to Tokyo). *Limitation*: Heavy Python stack, requires Neo4j/FalkorDB Docker containers, lacks code symbol anchoring.
+2. **Mem0**: Leading developer drop-in memory layer. Strong benchmark performance on LongMemEval. *Limitation*: Relies on remote APIs or external vector databases, lacks pre-write secret scrubbing, no living ADR synchronization.
+3. **Letta (MemGPT)**: Treats agents like an operating system with RAM/Recall/Archival tiers and self-editing memory blocks. *Limitation*: Heavy agent runtime wrapper rather than a lightweight tool harness that drops cleanly into any existing agent (Claude Code, Cursor, Windsurf).
+4. **LangMem**: Elegant developer SDK for LangGraph. *Limitation*: Tightly coupled to LangChain abstractions; does not inspect repository ASTs or provide CLI tooling.
+5. **HippoRAG & LightRAG**: Neurobiologically inspired associative recall via Personalized PageRank and lightweight dual-level graphs. *Limitation*: Academic scripts; no MCP stdio servers, no state-machine promotion ladder (`candidate ➔ confirmed ➔ superseded`).
+6. **A-Mem**: Zettelkasten slip-box note graph with dynamic note evolution. *Limitation*: Academic focus on conversational dialog rather than production software architecture, build systems, or monorepo meshes.
+
+---
+
+## 🚀 6 Transformative Feature Pillars for Muse Memory Evolution
+
+---
+
+### Pillar 1: Tri-Cognitive Memory Tiers (Procedural + Episodic + Semantic)
+
+Currently, Muse Memory excels at **Semantic Memory** (facts, rules, ADRs, preferences) and transient event logging (**Observations**). To become a true cognitive OS, it must formalize **Procedural** and **Episodic** memory tiers.
+
+```
+┌──────────────────────────────────────────────────────────────────────────────────────────────┐
+│                              Tri-Cognitive Agent Memory System                               │
+├──────────────────────────────┬───────────────────────────────┬───────────────────────────────┤
+│    1. Semantic Memory        │     2. Episodic Memory        │    3. Procedural Memory       │
+│    ("What We Know")          │     ("What Happened")         │    ("How To Do It")           │
+├──────────────────────────────┼───────────────────────────────┼───────────────────────────────┤
+│ • Timeless architectural ADRs│ • Session narrative episodes  │ • Executable action playbooks │
+│ • Bug workarounds & fixes    │ • Causal failure cascades     │ • Tool invocation trajectories│
+│ • Hard invariants & policies │ • Trial-and-error transcripts │ • Verification assertions     │
+│ • Bi-temporal validity bounds│ • Retrospective reflections   │ • Rollback recipes            │
+└──────────────────────────────┴───────────────────────────────┴───────────────────────────────┘
+```
+
+#### A. Procedural Playbook Engine (`ProceduralMemory`)
+- **Schema**:
+  ```typescript
+  interface ProceduralPlaybook {
+    id: string; // e.g. "pb_nextjs_d1_migration"
+    title: string;
+    goal: string;
+    preconditions: string[]; // e.g. ["wrangler.toml exists", "D1 binding configured"]
+    step_sequence: {
+      step: number;
+      action: string;
+      tool: string; // e.g. "run_command"
+      command?: string;
+      expected_output_pattern?: string;
+      failure_recovery?: string;
+    }[];
+    verification_assertions: string[]; // e.g. ["bun test migrations passed"]
+    anchors: CodeAnchor[];
+    success_rate: number;
+    execution_count: number;
+  }
+  ```
+- **Autonomous Distillation**: When an agent completes a multi-step task involving 3+ tool calls that ends in a verified state, `muse_harvester` distills the sequence into a candidate `ProceduralPlaybook`.
+- **MCP Surface**:
+  - `muse_playbook_recall(goal: string, context_files?: string[])`: Retrieves the proven execution sequence.
+  - `muse_playbook_record(...)`: Manually or autonomously captures a workflow.
+
+#### B. Episodic Causal Narrative Horizon
+- Group raw observation events (`observations.jsonl`) into structured **Episodes**:
+  - `Goal ➔ Hypothesis ➔ Action Trajectory ➔ Verification Result ➔ Retrospective Insight`.
+- When an agent encounters an error, query past episodes: *"Have we encountered this exact error sequence before, what failed, and what eventually succeeded?"*
+
+#### C. Bi-Temporal Validity Windows (Zep / Graphiti Pattern)
+- Every memory stores:
+  - `asserted_at`: Transaction timestamp when recorded.
+  - `valid_from`: Beginning timestamp when the rule/fact became active in reality.
+  - `valid_until`: Expiration timestamp when the rule was superseded by an environmental change (e.g. framework upgrade).
+- Enables accurate historical code reviews on legacy git tags without clobbering current constraints.
+
+#### D. Ebbinghaus Cognitive Forgetting Curve
+- Exponential decay formula: $S(t) = S_0 \cdot e^{-t / \tau} \cdot (1 + \text{utility\_roi})$.
+- Memories with verified green test runs and repeated tool applications reset their half-life $\tau$.
+- Unverified, noisy candidate fragments smoothly decay into cold storage without manual administrative pruning.
+
+---
+
+### Pillar 2: AST Associative Callgraph Retrieval & Speculative Pre-Flight Recall
+
+#### A. Recursive SQLite CTE Associative Expansion (Zero-Daemon Local HippoRAG)
+- Standard retrieval matches direct query tokens or direct symbol names.
+- **The Problem**: A developer asks about `createCheckoutSession()`. That function calls `validateCartToken()`, which calls `verifyStripeNonce()`. The critical negative memory `DO_NOT_REUSE_PAYMENT_NONCE` is anchored to `verifyStripeNonce()`. Standard RAG misses it.
+- **The Solution**: An in-process SQLite recursive Common Table Expression over the AST symbol table:
+  ```sql
+  WITH RECURSIVE call_tree(caller, callee, depth) AS (
+    SELECT caller_symbol, callee_symbol, 1
+    FROM symbol_calls
+    WHERE caller_symbol = :entry_symbol
+    UNION ALL
+    SELECT sc.caller_symbol, sc.callee_symbol, ct.depth + 1
+    FROM symbol_calls sc
+    JOIN call_tree ct ON sc.caller_symbol = ct.callee
+    WHERE ct.depth < 3
+  )
+  SELECT DISTINCT m.*
+  FROM memories m
+  JOIN memory_anchors a ON m.id = a.memory_id
+  JOIN call_tree ct ON a.symbol_name = ct.callee
+  WHERE m.status = 'confirmed';
+  ```
+- Delivers HippoRAG-grade multi-hop associative recall with **zero external graph database daemons**, running entirely within SQLite WAL in sub-10ms!
+
+#### B. Speculative Pre-Flight Context Push
+- **Trigger**: Git checkout event, IDE file open event, or branch switch (`git checkout -b feat/payment-v2`).
+- **Mechanism**: Muse Memory speculatively computes the knapsack context package for touched files in background and stages it into `.memory/HOT.md`.
+- When the agent starts turn 1, `get_context` or `muse_context` completes in sub-1 millisecond with zero search latency.
+
+---
+
+### Pillar 3: Git-Branchable Memories & Multi-Tenant Agency Enclaves
+
+#### A. Git-Aware Branchable Memory Overlays (`memory branch`)
+- In modern agency setups, multiple subagents work across parallel branches (`feature/auth`, `feature/billing`, `dev`).
+- **Mechanism**:
+  - `memory branch create feat/auth`: Branches `.memory/branches/feat-auth.db` overlay.
+  - Candidate memories recorded during the branch remain in the branch overlay.
+  - `memory branch merge feat/auth`: Reconciles branch-local memories with `main`, detects semantic contradictions, triggers Vibeguard secret audits, and commits unified knowledge.
+
+#### B. Multi-Tenant Agency Enclaves (`scope: client`)
+- Tailored for Harsh's agency model with 4 internal divisions: Sol, Jasper, Crew, Nexus.
+- **Isolation Rule**:
+  - `scope: client`: Enclave isolated per client ID (`client_id: "client-acme"`).
+  - Client A’s confidential database schemas and domain logic are never exposed to Client B.
+  - Universal architectural principles (`scope: global`) propagate freely across all client workspaces.
+
+---
+
+### Pillar 4: Test-Driven Memory Reinforcement & Autonomous Regression Sentry
+
+#### A. Automated CI / Test Harness Feedback Loop
+- Directly couple memory utility metrics to test runners:
+  ```bash
+  memory test -- bun test
+  ```
+- **Operational Logic**:
+  - When tests pass, memories anchored to modified files receive an increment to `application_count` and `successful_applications`.
+  - When tests fail, Muse Memory inspects stack traces against the negative memory index (`BUG_PRONE_PATTERN`, `DO_NOT_USE`).
+  - If a stack trace matches a known negative pattern, Muse Memory instantly outputs:
+    `🚨 REGRESSION SENTRY: You tripped known anti-pattern [m_anti_pattern_123]. Proven fix: [pb_recovery_playbook].`
+
+---
+
+### Pillar 5: In-Process Zero-API-Key Local Vector Embeddings (FastEmbed / SQLite-Vec)
+
+- **The Trade-Off Today**: Most vector databases require either cloud API keys (OpenAI `$0.02/1M tokens`) or heavy Python servers (Chroma, Qdrant, LanceDB).
+- **The Local-First Solution**:
+  - Integrate an embedded quantized embedding engine (e.g., pure in-process `fastembed` or ONNX MiniLM-L6-v2) directly into Bun/Node.
+  - Store 384-dimensional quantized vectors directly inside SQLite using vector BLOBs or SQLite-Vec extensions.
+- **Reciprocal Rank Fusion (RRF)**:
+  $$\text{Score}(d) = \sum_{m \in \{\text{BM25}, \text{Vector}, \text{AST}\}} \frac{w_m}{k + \text{Rank}_m(d)}$$
+  Fuses lexical BM25 keyword precision, AST code structural proximity, and dense semantic vector meaning into a singular, unbeatable ranking list.
+
+---
+
+### Pillar 6: Agent Development Environment (ADE) & Meta-Cognitive Self-Reflection MCP
+
+- **`muse_reflect`**:
+  - Called at the conclusion of an agent session.
+  - Evaluates:
+    1. Did we make unnecessary tool queries?
+    2. Did any approach fail before we found the solution?
+    3. Are there new hard invariants that should be written to `CURRENT.md`?
+  - Automatically synthesizes and stages candidate memory updates.
+- **`muse_counterfactual`**:
+  - Captures the reasoning behind rejected architectural paths: *"We chose SQLite WAL over PostgreSQL because the application must run zero-daemon in CI and local CLI."*
+  - Permanently prevents future agents from endlessly debating or re-proposing rejected options.
+
+---
+
+## 📅 Evolution Roadmap: Implementation Phasing (R17 ➔ R22)
+
+```
+2026 Q3                                                                  2026 Q4
+┌───────────────────────────┐      ┌───────────────────────────┐      ┌───────────────────────────┐
+│ R17: Tri-Cognitive Tiers  │ ───► │ R18: AST Associative CTE  │ ───► │ R19: Git Branch & Enclaves│
+│ • Procedural Playbooks    │      │ • In-Process HippoRAG     │      │ • Branchable Memory       │
+│ • Episodic Horizons       │      │ • Speculative Pre-Flight  │      │ • Client Enclave Security │
+│ • Bi-Temporal Bounds      │      │ • Blast-Radius Scoring    │      │ • Signed Attestation      │
+└───────────────────────────┘      └───────────────────────────┘      └───────────────────────────┘
+              │                                                                     │
+              ▼                                                                     ▼
+┌───────────────────────────┐      ┌───────────────────────────┐      ┌───────────────────────────┐
+│ R20: Test-Driven Sentry   │ ───► │ R21: Zero-Key Vectors     │ ───► │ R22: ADE Self-Reflection  │
+│ • CI Test Hook Integration│      │ • FastEmbed In-Process    │      │ • muse_reflect MCP        │
+│ • Anti-Pattern Watchdog   │      │ • RRF Hybrid Search Fusion│      │ • Counterfactual Reasoner │
+│ • Flaky Test Detection    │      │ • 100% Offline Quantized  │      │ • A-Mem Auto-Consolidator │
+└───────────────────────────┘      └───────────────────────────┘      └───────────────────────────┘
+```
+
+---
+
+## 🔒 Architectural Invariants Preserved
+
+Every feature in this evolution plan strictly honors the non-negotiable Muse Memory invariants:
+1. **Zero External Daemons**: No background servers, no Python daemons, no Docker dependencies. Runs in-process via SQLite WAL mode and Bun/Node.
+2. **Zero Secret Leakage (Vibeguard Protocol)**: All new memory structures (playbooks, episodes, enclaves, vectors) pass through the 45+ credential regex scanner before touching disk.
+3. **AST Structural Code Grounding**: Memories remain anchored to concrete code identifiers, with line-independent structural hashing and drift auditing.
+4. **Deterministic LifeCycle Governance**: 7-state state machine (`candidate ➔ confirmed ➔ superseded`) with immutable logging in `audit.jsonl`.
+5. **Token Knapsack Budgeting**: Strict token budgeting prevents agent context bloat across all retrieval modes.