musememory 2.2.1 → 3.0.0

package/.agents/context/current.md

@@ -1,7 +1,145 @@
 # 📍 Current Shipped State & Active Invariants
 
-> **Version**: `v2.2.1`  
-> **Status**: Production Release (Hardened v2.2 with Linus-Style Code Review Bug Fixes)
+> **Version**: `v3.0.0`  
+> **Status**: Major Release (Failure Attribution, Negative Memory Mining, HOT.md Working Set Compounding & LangMem Logarithmic Frequency Ranking)
+
+---
+
+## ⏭️ Next Up (Post-Wave 22 Focus)
+- **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).
+
+---
+
+## 🏁 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,12 +176,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`](file:///home/harsh/Projects/github/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.

package/.agents/context/deep-research-memory-adaptation-2026-10.md

@@ -0,0 +1,107 @@
+# Deep research — memory adaptation shortlist (2026-10)
+
+**Workstream**: A of the competitor-adaptation plan. **No implementation here.**
+**Method**: primary sources (repos, specs, docs) plus the existing 86-system study in
+`deep-research-memory-mechanisms-2026-09.md`. Every row names its source and marks what
+Muse already ships, so nothing already built is re-proposed.
+
+**Not re-proposed** (shipped and verified in `current.md` #35–37): write-time citation
+verification, the recall-time freshness gate, and the 3-event hook pack.
+
+## Scoring
+
+Score = **impact × feasibility** (both 1–5). Impact is measured against the §14 gap
+scorecard where Muse's weakest axis is hands-free use at 4/10 (trust 7/10, speed 15/16,
+observability 8/8). Feasibility discounts anything requiring an LLM, an API key, a daemon,
+or host support that does not exist yet.
+
+---
+
+## Scored adaptation table
+
+| # | Candidate | Mechanism (primary source) | What Muse already has | Adaptation | Impact | Feas | Score |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| A1 | **Full hook coverage** | agentmemory fires 12 Claude Code lifecycle events (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, PreCompact, Stop, SubagentStop, SessionEnd, …); the newer hosts expose 18–30. Claude Code's own docs list the full set. | 3 of them: SessionStart, PostToolUse, Stop (`src/hooks/pack.ts`) | Add **UserPromptSubmit** (per-prompt top-K injection), **PreCompact** (flush checkpoint + distill before context loss), **PreToolUse(Read)** (inject verified memory for the file about to be opened), **PostToolUseFailure**, **SubagentStop**, **SessionEnd**. | 5 | 4 | **20** |
+| A2 | **"Starts full" install** | deja-vu `install --auto` indexes history already on disk at install time and writes guidance into each harness's *own* rules file, because hosts ignore bare MCP tool descriptions. | 24+ format migrator, transcript harvesters, `connect --with-hooks`, 80+ platform detection | At `connect`: (a) harvest existing transcripts before first session, (b) detect each host's rules file (AGENTS.md / CLAUDE.md / .cursor/rules) and write an idempotent memory-protocol block. | 5 | 4 | **20** |
+| A3 | **Incremental symbol-index maintenance** | deja-vu keeps a per-file `manifest.gob` and only re-reads grown files; 17.6 s to index 19,195 sessions, ~0.2 s end-to-end lookups. | `loadGraphSymbolIndex()` reads and parses `.memory/graph-symbols.json` per call, no invalidation | Persist a per-file mtime+size manifest; load the index once per process keyed by manifest digest; invalidate on `indexGraph` write. | 4 | 5 | **20** |
+| A4 | **Progressive-disclosure recall (L0/L1/L2)** | OpenViking writes generated `.abstract.md` (L0, ~100 tokens) and `.overview.md` (L1, ~2k tokens) beside every directory, so agents judge relevance before opening full content; measured −34.3–91.0% input tokens and −58.45–66.10% query latency on LoCoMo. | Wiki pages already expose an L1 detail level; L0 cache is *infrastructure*, not a disclosure tier | Return one-line L0 abstracts for ranked candidates plus a drill-down handle, so an agent can scan cheaply and expand only the winners — instead of one fused package for every call. | 4 | 4 | **16** |
+| A5 | **PR-time staleness gate** | Kage's `kage pr check` warns before the PR when a cited file changed; 0% stale-served measured. | Recall-time freshness gate, drift engine, `memory pr-context`, `memory code-impact` | `memory pr check`: fail or warn when the diff touches files whose anchored memories drifted, with the drift list inline. Fits CI as a standalone step. | 4 | 4 | **16** |
+| A6 | **Standing answers / mental models** | hindsight consolidates facts into **observations** (with evidence quotes and proof counts) and then **mental models** — standing answer pages read as a plain DB read with no retrieval and no LLM; agents boot with settled knowledge. | Distiller → candidates, wiki pages, ADRs, rollups | A derived `.memory/ANSWERS.md` of settled, high-utility confirmed facts, refreshed by the optimizer, injected at SessionStart — a read, not a query. | 4 | 3 | **12** |
+| A7 | **Suppress, don't delete** | Vestige keeps an append-only hash-chained log; `suppress` removes an entry from every read while keeping the bytes, and `receipt replay` re-derives state to detect tampering. | Append-only audit trail, 7-state lifecycle, `deleteEntry` | Add a `suppressed` lifecycle state that hides without destroying, and make the audit trail hash-chained so state can be re-derived and verified. | 3 | 3 | **9** |
+| A8 | **Graph-native multi-hop recall** | Vestige `causal_walk` traces a failure backward over *recorded* edges only (≤8 hops) to find the root cause rather than a lookalike. | `related_memory_ids`, mesh contracts, negative memories, "graph overlap" is 1 of the 11 ranking dimensions | A bounded walk over recorded edges from a failing anchor/symbol to surface the causal chain, exposed in the debugging profile. | 4 | 2 | **8** |
+| A9 | **Savings ledger (`gains`)** | Kage `kage gains` and deja-vu `stats --card` quantify tokens and money avoided, traceable to logged events. | `memory benchmark` (latency/quality), utility ROI fields | A ledger that converts avoided re-explanation and avoided grep passes into tokens and dollars, sourced from logged events. Also the strongest **website** proof point available. | 3 | 3 | **9** |
+| A10 | **Scoped retrieval** | OpenViking scopes semantic search to a project or memory subtree instead of a flat pool. | mesh resolution, project filters, path proximity in ranking | Scope recall to a subtree/package, with the scope reported in the result. | 3 | 3 | **9** |
+| A11 | **Single-file portable store** | Memvid packs data, indexes, and crash recovery into one `.mv2` file you can commit, scp, or share; `@memvid/sdk` does BM25 + vector ranking from that file. | `.memory/` YAML + SQLite, `exportSnapshot`, sealed `SyncPacket` | Not adopted: Muse already ships repo-local files plus a sealed sync packet, and the portability win is smaller than the migration cost. | 2 | 2 | **4** |
+| A12 | **Hybrid lexical + dense ranking** | agentmemory runs BM25 + local MiniLM vectors + structural graph with 3-way RRF: 14 ms p50, 95.2% R@5. | 11-dimension lexical + structural + graph ranking, keyless by design | Not adopted now: dense retrieval means an embedding model, which breaks the keyless, zero-model promise. Revisit only as an optional local reranker behind a flag. | 3 | 2 | **6** |
+| A13 | **MCP resource subscriptions (push, not poll)** | MCP spec 2025-06-18 supports optional `resources/subscribe` with `notifications/resources/updated`, gated on `capabilities.resources.subscribe`. | stdio MCP server (2024-11-05), 69 tools, 6 profiles | Blocked: Claude Code has an open request for resource-subscription support (issue #7252), so the main host would not receive the pushes. Do not build on it yet; re-check host support before investing. | 3 | 1 | **3** |
+| A14 | **Spaced-repetition decay + co-activation** | Vestige applies FSRS-6 decay (unused memories fade, use strengthens) and `dream_compile` strengthens co-activated edges. | recency decay, reinforcement counters, utility ROI, optimizer cadence | Partially covered today; the transferable piece is strengthening *co-activated* neighbours during consolidation rather than only the entry that was used. | 2 | 3 | **6** |
+
+---
+
+## Top 3 ranked adaptations
+
+### 1. A1 — Full hook coverage (score 20)
+
+**Why first**: hands-free use is Muse's weakest axis (4/10), and the pack that fixes it is
+already shipped with 3 of the ~12 events the ecosystem uses. The three added events carry
+most of the value: UserPromptSubmit removes the need for the agent to *choose* to recall,
+PreCompact stops losing in-flight knowledge exactly when context is discarded, and
+PreToolUse(Read) delivers memory at the moment it is provably relevant.
+
+**Acceptance criteria**
+- `memory hooks install` registers 6 events idempotently and preserves existing user hooks.
+- Every handler stays fail-open: a throwing handler must not block the host.
+- UserPromptSubmit returns top-K within its token budget, and returns nothing rather than
+  overrunning it.
+- PreCompact writes a CURRENT.md checkpoint and a distillation candidate before exit.
+- PreToolUse(Read) injects only memories whose anchors verify against the file being opened.
+
+**Tests to extend**: `test/hooks.test.ts` (per-event contracts, fail-open, idempotency),
+`test/governor.test.ts` (PreCompact checkpoint), `test/freshness.test.ts` (PreToolUse must
+not inject drifted memories).
+
+### 2. A2 — "Starts full" install (score 20)
+
+**Why second**: value on day one is the difference between a memory tool that compounds and
+one that is abandoned before it has anything to recall. Two halves, both independently
+useful: harvest what is already on disk, and tell each host *when* to call memory by editing
+the rules file it actually reads.
+
+**Acceptance criteria**
+- `memory connect` (and `--with-hooks`) harvests existing transcripts before the first
+  session, reporting the count and the sources it read.
+- For each detected platform, the correct rules file is identified (AGENTS.md, CLAUDE.md,
+  .cursor/rules, …) and a delimited memory-protocol block is written.
+- The write is idempotent and never clobbers user-authored content outside its delimiters.
+- `--dry-run` prints exactly which files would change.
+
+**Tests to extend**: `test/hooks.test.ts` (installer contract), plus a new
+`test/connect.test.ts` covering idempotency, delimiter safety, and dry-run output.
+
+### 3. A3 — Incremental symbol-index maintenance (score 20)
+
+**Why third**: it is the only candidate that is simultaneously a user-visible speedup and a
+prerequisite for Workstream C. The baseline measured this pass shows the dashboard path is
+*not* where the symbol index hurts; the retrieval path is, and C's first fix step assumes a
+memoized, mtime-invalidated index that does not exist yet.
+
+**Acceptance criteria**
+- The symbol index is parsed once per process and reused; a second call re-reads nothing.
+- A changed file (mtime or size) invalidates only its own entries, not the whole index.
+- A deleted file's entries are dropped on the next load.
+- Recall latency is unchanged from the measured sub-2 ms baseline on a warm store.
+
+**Tests to extend**: `test/graph.test.ts` and `test/graph_ast.test.ts` (invalidation and
+reuse assertions), plus a latency regression guard as C's step 1 lands.
+
+---
+
+## Notes on two notable non-adoptions
+
+- **A13 (MCP subscriptions)** is the one candidate whose mechanism is attractive and
+  standardised but whose delivery path is missing: the spec supports it, the host does not
+  yet. Recording it here so it is not "discovered" and half-built later.
+- **A12 (dense vectors)** is the clearest strategic conflict found. The competitor numbers
+  are strong (95.2% R@5) but every one of them requires an embedding model. Muse's keyless,
+  zero-model, sub-2 ms position is worth more than the recall delta, and the accepted
+  tradeoff is explicit rather than accidental.