musememory 2.2.1 → 3.0.0

package/.agents/research/ecosystem-teardown-2026-10.md

@@ -0,0 +1,289 @@
+# Competitive Ecosystem Teardown & Improvement Catalog — 2026-10-14
+
+**Milestone R17 (extended).** Inputs: principal's 69-URL list (Hermes plugin ecosystem + major OSS memory systems), Hermes platform docs, DB/transport research for server mode, plus the prior Walrus/SOTA brief.
+**Branches**: `feat/docs-memory-arch-roadmap-walrus` · Baseline `bun test`: 502 pass / 0 fail / 85 suites.
+**Method**: REA-derived methodology (question checklist, evidence → inference → unknown tiers, bounded negative search). All web lanes ran in dedicated subagents; this parent session stayed write-clean. Verdicts are mechanism-level; licenses honored per-repo (AGPL/BSL/PolyForm/proprietary = idea-only, reimplement).
+
+---
+
+## 1. Headline Conclusions
+
+1. **The Hermes plugin ecosystem is a vendor land grab, not a competitor set**: ~48 plugins surveyed, nearly all 0–16 stars, all created Jun–Oct 2026, 12+ of them are thin HTTP shims for hosted SaaS (penny, dexio, hicortex, cortexlayer, metronix, hydradb, pastdotdev, brethof) with zero storage/retrieval of their own. **None is a validated competitor.** The genuinely mature ones: `indigokarasu/chronicle` (event-sourced, production-grade, updated daily), `ashmoonori-afk/birkin` (benchmark-disciplined), `cnkang/hermes-plugin-qdrant-memory` (only one in the official catalog, 5★), `RohiRIK/OpenLtm` (27★, Hermes-catalog-pinned at 2.16.2), `xraysight/hermes-memory-ui` (73★, read-only inspector).
+2. **Muse Memory is architecturally ahead of nearly all of it**: local-first SQLite+FTS5+YAML mirror + MCP + code anchors + contradiction engine + ROI tracking vs. plugins that are Qdrant-daemon adapters or SaaS shims. The risk is not a competitor stealing the architecture — it is **us not shipping the mechanisms the whole field already agrees on**.
+3. **The field's convergence (see R17 brief) is confirmed by this teardown**: ADD-only append, hybrid fusion, event-triggered consolidation — plus three new cross-cutting agreements: (a) **abstention as a first-class outcome** (Compartment, limbic, lancedb-suite, EntropicMem all independently converged), (b) **loss must be visible** (tombstones, omission markers, degraded-signals), (c) **forgetting is a policy, executable and auditable** (memanto stamped expiry, memoria trust-tier half-lives, memex8 Weibull, OpenLtm decay_score).
+4. **The best single mechanisms for Muse Memory** (ROI-ranked): materialized `decay_score` column (OpenLtm), trust-tier-keyed half-life decay (memoria), `linked_memory_ids` write-time edges (mem0), dual-threshold abstention gate (lancedb-suite), soft-OR evidence fusion (Compartment), echo suppression (mnemostack), FTS5-tokenizer-matched abstention gate + never-drop manifest TOC, provenance/lineage tables (intelligent-memory), admission ledger (qdrant-memory).
+
+---
+
+## 2. Competition List (canonical, all surveyed — source of truth; NOT in `src/`)
+
+> Rule: this list exists in `.agents/research/` and the public `musememory-comparison.html` only. No competitor identity in `src/`. Licensed-restricted repos are marked ⟦idea-only⟧.
+
+### 2.1 Major memory systems (from R17 + this pass)
+| System | One-liner | Verdict | Steal |
+|---|---|---|---|
+| mem0ai/mem0 (67k★) | De-facto memory layer; ADD-only v3; OSS = 3-signal fusion | ADAPT | `linked_memory_ids` write-time edges (graph for free); semantic threshold gate **before** BM25/entity fusion; query-length-adaptive BM25 sigmoid; `explain=True` score details |
+| volcengine/OpenViking (40k★, AGPL ⟦idea-only⟧) | VFS context DB with L0/L1 abstract sidecars | ADAPT | Generated `.abstract/.overview` sidecars + ratio-batched parent-summary refresh (~40 LOC, daemon-free) |
+| moorcheh-ai/memanto (2.3k★, MIT) | Memory-agent curator, per-agent namespaces | ADAPT | Stamped expiry `status/expired_at/expired_by(rule name)` + pin-capable first-match-wins YAML policy; reversible, self-explaining forgetting |
+| matrixorigin/memoria (612★, Apache-2.0) | "Git for agent memory", governance tasks | ADAPT | **TrustTier-keyed half-life (365/180/60/30d)**; safety snapshot before governance passes; feedback→weight auto-tuner |
+| BetterDB-inc/monitor packages (1.3k★) | Valkey monorepo hiding agent-memory lib | ADAPT | Two-mode `consolidate()` (lossy summary vs subject-reconciled facts + tombstones, additive); single shared recall/eviction weight function; datedness-from-field edge cases |
+| Walrus Memory / MemWal (R17) | Decentralized Sui+Walrus memory | IDEAS ONLY | Content-addressed ids, hash-chain audit, extend-before-expiry discipline |
+| vectorize-io/hindsight (49.6k★, MIT) | Postgres bank-based biomimetic memory service | MIT | `prefer_observations` recall-time supersession dedup (scoped to top-2×budget so a far observation can't suppress a top fact); watermark staleness (staleness measured from `last_memory_seen_at`, not clocks); insertion-time invalidation cascades; `RecallArms` engine-resolves-before-store contract |
+| plastic-labs/honcho (7.6k★, **AGPL**) | Peer-centric memory infrastructure + Dialectic agent | AGPL ⟦idea-only⟧ | Concepts only: observer/observed directional queries ("{observer}'s understanding of {observed}") — cleanest multi-agent mental-model primitive; surprisal-gated consolidation via random-projection tree path log-prob (reimplement from concept, never copy code) |
+| mnemosyne-oss/mnemosyne (3.4k★, MIT) | SQLite-only BEAM 3-tier memory — closest sibling | MIT | Veracity tiers (stated 1.0/inferred 0.7/unknown 0.8/imported 0.6/tool 0.5) + Bayesian `1-0.7^n` confidence + conflicts-table-never-delete + same-(subject,predicate) auto-supersede chains; collision-safe length-prefixed fact IDs; additive consolidation (`consolidated_at`, never delete); zero-LLM 13-type ingest classification; federation handshake (cross-bank conflict dedup, fail-closed probes outside the write lock). ⚠️ README withdraws its own headline benchmark; config layer has 50/106 keys silently ignored — port mechanisms only |
+| agentscope-ai/ReMe (3.6k★, Apache-2.0) | "Memory as File" Markdown + wikilinks, rebuildable index | Apache-2.0 | Files-as-truth with rebuildable `metadata/`; progressive wikilink expansion after RRF; seen-chunk TTL (`skipped_seen`); path-level locks; mutation rollback via mtime/size snapshot diff; shared-directory multi-agent with zero coordination |
+| vshulcz/deja-vu (1.2k★, MIT) | Transcript indexer, 42 harnesses, no model | MIT | `SrcTS` evidence-age stamping (a memory is only as fresh as its evidence); index-time credential redaction keeping surrounding text searchable; tiered retrieval ladder with visible loosening; ground-moved reporting (silent when it can't tell); fix-pair mining (error→command→no-recurrence, 81% measured); read-only agent clients + single writer |
+| Zep/Graphiti, Letta, Supermemory, Cognee, LangMem, A-MEM, HippoRAG (R17) | see prior brief | ADAPT | see prior brief |
+
+### 2.2 Hermes plugin ecosystem — the long tail (verdicts from 6 teardown lanes)
+| Repo | What it is | License | Verdict | Steal (mechanism) |
+|---|---|---|---|---|
+| 3L0935/hermes-lancedb-memory-suite | LanceDB provider + visualizer, calibration discipline | MIT | **ADOPT** | Dual-threshold abstain gate + named calibrated-engine constant (`SEARCH_MAX_COSINE_DISTANCE`/`SEARCH_MIN_BM25_SCORE`) |
+| fred0m/hermes-memobase-provider | Memobase backend, in-plugin 3-leg retriever | MIT | **ADOPT** | `low_discrimination()` conditional rerank (top1/top2 ratio <1.01, overlap <0.3 → rerank); idf boost for rare tokens |
+| Pinutss/jev-memory-selector | Post-retrieval budget filter | MIT | **ADAPT** | Typed drop-reason/keep-reason audit trail; deterministic tie-break |
+| kuehnberger/hermes-qdrant-memory | Qdrant + SQLite FTS5 md index | MIT | **ADAPT** | `_clamp_limit` (tool arg ≠ human budget); dry-run point-ID-only delete; url-without-userinfo |
+| indigokarasu/chronicle-agent-context-and-memory | Event-sourced local-first engine (100k LOC-scale) | MIT | **ADAPT** | Config-honesty AST audit (WIRED/DORMANT/UNREAD + build-failing test); `[DRAFT]` marking + separate confident-answer key; raise-on-removed-security-key; bounded hook-driven maintenance (5ms budget, at most one job) |
+| ashmoonori-afk/birkin-mnemosyne | Pure-stdlib Markdown vault + BM25 | MIT | **ADOPT** | Resident INDEX route-map (~800 tok for 240 docs); search-time query expansion (synonyms/keywords/related fields); curation executor with **no delete verb** + archive caps; frozen-benchmark discipline |
+| labyrinth-analytics/loreconvo | Cross-surface SQLite FTS5 memory | BSL 1.1 ⟦idea-only⟧ | **ADAPT** | Compound-token FTS5 expansion (camelCase/snake_case split; claimed +36pp Recall@5); split search/autoload half-lives (90d/30d) |
+| magnus919/hermes-cashew | sqlite-vec thought graph + cron sleep | Apache-2.0 | **ADAPT** | Ownership-token cron reconciliation; cron job carries full validated effective config |
+| Ex8-ca/memex8 | Rust + Qdrant + Weibull decay | MIT | **ADAPT** | Per-type Weibull decay table (21 curves); regex query-intent bias table (no LLM); spreading activation on recall |
+| hoysama/hermes-intelligent-memory | SQLite FTS5 Arab/multilingual provider | MIT | **ADOPT** | `fact_provenance` append-only + triple-unique index; `supersedes_id`/`conflicts_with_id` lineage FKs; `UNIQUE(profile, content_hash)` idempotency; epoch compression; self-healing doctor |
+| ottosulin/hwiki | Markdown wiki → FTS5 | MIT | **ADAPT** | Untrusted-zone quarantine re-verified per hit; context-conditional read-only (write tool withheld from schema for cron/subagent); write-time labelled-secret guard; safe FTS token quoting; FTS5 capability probe |
+| MCarlomagno/hermes-pubky | Agent portability to Pubky | MIT | **ADAPT** | Head-moves-last immutable checkpoint ordering (`seal→verify→publish→move head`); base/head two-pointer restore model; exit-code contract |
+| Cortex-Layer/cortexlayer-hermes-plugin | CortexLayer shim | Apache-2.0 | **ADAPT** | Digest-deduped `on_pre_compress` capture + persisted digest set; never return empty checkpoint |
+| Neboy72/nexus-memory | Qdrant shared brain + daemon | MIT | **ADAPT** | `effective_score = base × reinforcement × decay`; fail-closed access level (missing ⇒ private; refuse widening) |
+| gamaze-labs/hicortex-hermes-plugin | Pushed recall-index shim | (unset) | **ADAPT** | Pushed recall index + lazy hydrate = the fetch is the reinforcement signal; hard per-recall timeout |
+| aean0x/hermes-gbrain-retrieval-reflex | Ambient pointer injection | MIT | **ADAPT** | Self-injection strip; trivial-turn gate (<4 chars); hard byte-cap; fail-soft invariant |
+| Ufonik88/EntropicMem | Standalone knowledge engine | MIT | **ADOPT** | FTS5-tokenizer-matched abstention gate (transient in-memory FTS w/ identical tokenizer config); deterministic `why_retrieved` reason tokens; decay-with-floor |
+| Nacho-Labs-LLC/hermes-plugin-nachos | Three-tier budgeted assembly | MIT | **ADOPT** | Never-drop manifest TOC (descending summary cap, entry line never omitted); rank title+summary not body |
+| udjin-labs/hermes-mnemostack | TAM/Qdrant transport | MIT | **ADOPT** | Capture-side provenance echo suppression (age-bounded, not fence-parsing); deterministic `(source,offset,text)` ids; event-time-at-capture; `degraded − notes` fault signal |
+| vbcherepanov/hermes-tam-memory | TAM MCP front | MIT | **ADOPT** | `<memory-context>` + base64 strip before re-capture; bounded drop-oldest write queue + deadline flush |
+| vimona3ds/hermes-snapcompact | Bitmap-PNG context compaction | MIT | **ADAPT (1 fn)** | Dual-measure honest-vs-host token accounting fail-safe before committing any compaction |
+| kerrz2020/hermes-gbrain | Postgres+pgvector installer | MIT | SKIP | Testing discipline only: `verify-install-fresh.sh` isolated-`$HOME` drill with pinned expected values |
+| itpartypattaya/hermes-dreaming | Nightly deterministic consolidation skill | MIT | **ADOPT (top value)** | `{"wakeAgent":false}` gate + actionable-keys allowlist; `memory_pressure` ceiling as actionable event; overnight loss guard (25% entry/char drop, alert-only, head-hash); corroboration-gated promotion (≥2 days, machine sources excluded); conflict≠duplicate; atomic multi-op writes |
+| itpartypattaya/hermes-plugin-holographic | Ex-Hermes-core default SQLite FTS5 fact store (6.8k LOC, 35 test files) | MIT | **ADOPT (top value)** | IDF-weighted relevance gate before FTS5 (0.3, identifier-decisive, greeting short-circuit); `_not_recent()` re-injection suppression (6 turns); read-path re-validation (injection/credential/markup); five-verb bitemporal lifecycle with `valid_to_exact` + `as_of → {results, undetermined}`; forget tombstone + `secure_delete` VACUUM; `retrieval_count`/`helpful_count` feedback columns; scope-derived DB filenames |
+| esaradev/icarus-plugin | Markdown fabric + fine-tune pipeline (154★) | MIT | **ADAPT** | recall→usage telemetry join (`usage_rate = used∩recalled/recalled`) — closes Muse's missing usage-feedback loop; >0.6 topic-overlap prefetch skip |
+| patrykkopycinski/hermes-plugin-agent-memory-es | Elasticsearch SaaS shim | no license | **ADAPT (principle)** | user-words→episodic vs agent-prose→semantic tier split as provenance; `is_trivial_prompt()` prefetch gate |
+| aska-digital/optchat-memory | Append-only JSONL + binary summary tree | MIT | **ADOPT** | fsync-per-line JSONL + single-writer flock that fails loud; `id+n` positional zoom addressing; age-graded view tiling; free-node rule (no summarize when payload fits) |
+| supermemoryai/hermes-supermemory | Supermemory SaaS client | MIT | **ADAPT** | 4-hour bucketed `customId` (`<session>_<date>_b0..5`) collapsing turns ≤6 docs/day; bounded oldest-first retry buffer with bytes cap |
+| yonro/hermes-xmemo-plugin | xmemo SaaS + SQLite reliability layer | MIT | **ADOPT** | write outbox state machine (`pending→processing→sent/held/failed`), `idempotency_key` UNIQUE, `recover_stale_locks(300s)`, `auto_replay=0→held` for non-idempotent ops, `stale:true` degraded-read tag |
+| Markgatcha/memos (MemOS) | Local-first SQLite+FTS5 graph memory | MIT | **ADAPT** | TOON token-compact context pack (claimed 77.6% vs JSON); bitemporal `searchTemporal(atTime)` default-excluding superseded; `scoreRetain` 0.3 write gate (refuse junk writes); trust-from-provenance table (user 1.0/agent 0.7/external 0.5/system 0.3); local rule-based extraction |
+| matebenyovszky/agentplaybooks | SaaS playbooks + Hermes shim | MIT | **ADAPT (1 pattern)** | `NoRedirects` + strict `validate_url` (HTTPS only, no userinfo, loopback HTTP opt-in) for any remote surface; strict tool-arg surface; `identity_signature()` cross-profile cache guard |
+| lancedb/hermes-agent-memory | LanceDB hybrid provider | Apache-2.0 | **ADOPT (hook) / SKIP (store)** | **`on_pre_compress` extraction as a write trigger** (facts survive compaction — the highest-leverage hook in the ecosystem); fact-first + turns-as-provenance; whitespace/case-normalized `content_hash` dedup; `stable_turn_id` from content not index; fail-loud on schema/dim mismatch |
+| rarf/optmem-hermes-plugin | Append-only fixed-width log + decay tree (17★) | MIT | **ADAPT** | power-of-two-aligned blocks as idempotent resumable compaction units; `WakeNeedsCompression` refusal (never emit an incomplete digest) |
+| tuancookiez-hub/HyAtlas-Memory | Go server + 8-layer memory | Apache-2.0 | **ADAPT** | supersede-not-delete + per-layer `hidden` counter for over-fetch (`WHERE superseded_at IS NULL`); RRF with floor applied to vector hits only; corroboration-gated schema induction (≥2 turns) |
+| electricsheephq/lcm-x | SQLite DAG lossless context engine (93★) | MIT | **ADAPT** | summary DAG with source-lineage edges (every summary drillable to raw); directness scoring (tool-output JSON −4.0); age-decay blended into rank; bounded externalization refs |
+| yantrikos/yantrikdb-hermes-plugin | Temporal context graph, embedded (96★) | MIT | **ADOPT** | `idempotency_key` on capture (retry→0 writes, divergent retry→named conflict); constitution-file pattern (CURRENT.md-style rules injected first, never trimmed, no write tool); dual-trigger maintenance cadence (N turns AND wall-clock); `why_retrieved` on every hit |
+| roboticforce/sugar | SQLite memory + MCP (98★, AGPL ⟦idea-only⟧) | AGPL-3.0 | **ADAPT (idea only)** | reserved guideline slots (global/USER.md-class entries always surface); per-type `expires_at`; vec→FTS5→LIKE 3-tier cascade; importance+access_count orthogonal axes |
+| topoteretes/cognee-integrations | Cognee Hermes adapter (100★) | Apache-2.0 | **ADAPT** | two-tier promotion (cheap `pending` tier → explicit session-end flush to durable tier — never per-write LLM); circuit breaker (5 fails→120s cooldown); pre-compaction memory anchor; creds redacted before store |
+| praggybuilds/hermes-gbrain-pointer | Read-only pointer injector | MIT | **ADOPT** | Generation-counter invalidation of in-flight queue_prefetch (no stale pointers after rewind); pop-once cache; bounded body reads; secret-fingerprint comparison |
+| kalice-vi/hermes-excel-line | xlsx workbook memory | MIT | SKIP | Strictly worse than SQLite+FTS5 |
+| dexio-wiki/hermes-plugin | Dexio SaaS shim | MIT | SKIP | Remote, no ranking |
+| BrethofAI/brethof-brain-client | 20-harness hosted client | proprietary ⟦idea-only⟧ | SKIP | Concept only: curator gate (agent appends evidence; deterministic promotion decides records) |
+| aska-digital/cognition-memory | Session-end regex facts | Apache-2.0 | **ADOPT** | Truncation order `pin > provenance > recency > salience` + mandatory `[N omitted — budget M]` marker; fetch-first merge keep-both; tombstones on eviction ("loss is always visible"); mandatory provenance gate (empty string = missing); lock ladder |
+| mtrnix/hermes-memory-metronix | Metronix REST proxy | Apache-2.0 | SKIP | prefetch=cache / queue_prefetch=background pattern (trivial port) |
+| hydra-db/hydradb-hermes-plugin | 60-line adapter | Apache-2.0 | SKIP | None |
+| HelperLabs/penny-hermes | Hosted MCP client | MIT | SKIP | Transport hardening only (NoRedirect, bounded response, content-free errors) |
+| Karb-Interactive/hermes-plugin-stack-memory | Git-wiki + LLM retriever | **no license** | SKIP code | Design only: thread-scoped `store_jail` (fail-open documented boundary); `verified|drifted|unknown` anchor triage |
+| pastdotdev/hermes-plugin | past.dev SaaS + session buffer | MIT | **ADAPT** | Silence-gap episodic cuts (`sittings()`); named budget constants with provenance; never-raise contract |
+| PIR8-Software/hermes-brain-graph | Markdown → graph UI | MIT | **ADAPT** | Rename-as-planned-transaction with snapshot rollback; `resolved|ambiguous|unresolved` link triage |
+| MaxFreedomPollard/Compartment | Encrypted offline MCP memory | Apache-2.0 | **ADOPT** | Soft-OR evidence fusion `P=1-(1-pv)(1-pl)`; fixed-bound cosine→prob (0.25–0.85, ceiling 0.88 forced by weights); multiplicative priors; age-in-memories; windowed embedding for long texts; one ranking module imported by all surfaces |
+| dyiapanis/limbic | Qdrant self-tuning memory | PolyForm NC ⟦idea-only⟧ | **ADAPT** | `no_confident_match` abstention; `matured_at`/`atrophy_marked_at` mark-and-sweep; reconsolidation-without-mutation; writer-lock postmortem |
+| RohiRIK/OpenLtm | SQLite+FTS5 local-first (27★, catalog-pinned) | MIT | **ADOPT** | **Materialized `decay_score` column + importance-gated half-lives (14/30/90/180d) + `<0.25→deprecated`, 2 SQL statements** — highest ROI in survey; FTS5-as-floor/vectors-as-upgrade; dedup queues suggestions never auto-merges |
+| cnkang/hermes-plugin-qdrant-memory | Official-catalog Qdrant provider (5★) | MIT | **ADAPT** | Synchronous SQLite admission ledger before async extraction; capability-honesty README discipline |
+| kuntao2011/kkk-hermes-memory-zvec | Zvec lock governance | MIT | **ADAPT** | `atexit` bounded join before daemon-thread teardown (fixes zero-row loss); amortized index maintenance |
+| lumberroom/lumberroom-hermes | Cloud/self-hosted provider | Apache-2.0 | **ADAPT** | Fail-closed two-level ownership gate (`session_allowed`+`turn_allowed`); provider never implicitly writes |
+| kyssta-exe/hermes-obsidian-memory | Vault browser | no LICENSE file | SKIP | Read-only inspector pattern only |
+| xraysight/hermes-memory-ui | Cross-provider read-only UI (73★) | MIT | SKIP | UI reference for studio read-only inspector design |
+| m0re repos pending lanes | see pending list above | | | |
+| vectorize-io/hindsight, plastic-labs/honcho, mnemosyne-oss/mnemosyne, agentscope-ai/ReMe, vshulcz/deja-vu | (pending lane) | | | |
+
+---
+
+## 3. Steal List — merged, ranked by (impact × maturity) ÷ effort
+
+### Tier A — implement first (cheap, closes audited gaps)
+| # | Mechanism | Source | Effort |
+|---|---|---|---|
+| A1 | `decay_score` materialized column + importance-gated half-lives + deprecate pass | OpenLtm | ~40 LOC SQL |
+| A2 | Trust-tier-keyed half-life (provenance → decay rate) | memoria | ~20 LOC |
+| A3 | Dual-threshold abstraction gate + calibrated-constant discipline | lancedb-suite | ~60 LOC |
+| A4 | Soft-OR fusion + fixed-bound cosine→prob + multiplicative priors | Compartment | ~80 LOC |
+| A5 | `<memory-context>`/injected-block strip before capture (self-echo suppression) | TAM + mnemostack | ~40 LOC |
+| A6 | FTS5-tokenizer-matched abstention gate | EntropicMem | ~150 LOC |
+| A7 | Never-drop manifest TOC + truncation `pin>provenance>recency>salience` + `[N omitted]` marker | nachos + cognition-memory | ~120 LOC |
+| A8 | `linked_memory_ids` write-time linking (dedup against recent window) | mem0 | ~40 LOC |
+| A9 | Safe FTS5 query construction (quote every token) + compound-token expansion | hwiki + loreconvo | ~15 LOC |
+| A10 | Admission ledger (SQLite write-ahead of async extraction) | qdrant-memory | ~60 LOC |
+| A11 | Event-time-at-capture stamping + deterministic `(source,offset,text)` ids | mnemostack | ~20 LOC |
+| A12 | Typed drop/keep reasons on retrieval ranking | jev | ~40 LOC |
+| A13 | Tombstones-on-eviction + omission-visible loss + `memory_restore` | cognition-memory + R30 | ~60 LOC |
+
+### Tier B — capability upgrades (v2.5.0)
+| # | Mechanism | Source |
+|---|---|---|
+| B1 | `fact_provenance` append-only + lineage FKs + UNIQUE content_hash | intelligent-memory |
+| B2 | Lineage BFS walker (`supersedes∪related∪evidence`) | R17 P1 + above |
+| B3 | Hash-chained audit + session Merkle checkpoints | R17 (Walrus idea) |
+| B4 | Compaction-triggered consolidation (Letta pattern) | R17 |
+| B5 | `[DRAFT]` marking + separable confident-answer key | chronicle |
+| B6 | Config-honesty AST audit (WIRED/DORMANT/UNREAD + build-failing test) | chronicle |
+| B7 | Stamped expiry + pin-capable policy YAML | memanto |
+| B8 | Two-mode consolidate (summary vs reconcile+tombstones) + shared recall/eviction weights | BetterDB |
+| B9 | L0/L1 generated abstracts + ratio-batched refresh | OpenViking (reimplement) |
+| B10 | `why_retrieved` reason tokens; `low_discrimination()` rerank gate | EntropicMem + memobase |
+| B11 | `atexit` bounded join; generation-counter prefetch invalidation | zvec + gbrain-pointer |
+| B12 | Untrusted-zone quarantine + context-conditional read-only + write-time secret guard | hwiki |
+| B13 | Real embeddings + RRF hybrid (R21 spec branch) + semantic threshold gate pre-fusion | R21 + mem0 |
+| B14 | Intent-bias query multipliers (regex, no LLM) + per-type Weibull/decay curves | memex8 |
+| B15 | Recall-set eval harness (R27 branch) + frozen benchmark discipline | birkin + R27 |
+
+### Tier C — server-mode & UI (see §5/§6)
+Streamable HTTP transport, per-tenant DB files, Litestream, admission ledger, fail-closed gates; studio recall-debug rehaul.
+
+---
+
+## 4. Decisions: HAVE / IMPLEMENT / DEPRECATE
+
+**Already have or spec'd (do not rebuild):**
+- R21 llama.cpp embeddings (spec'd on `feat/local-embeddings-llama-cpp`) → covers B13.
+- R27 recall eval harness (spec'd `feat/recall-eval-harness`) → covers B15.
+- R28 trust tiers (spec'd) + GAP-3 freshness gate → foundation for A2/B12.
+- R29 I/O budget telemetry (spec'd) + R30 tombstones (spec'd) → covers A13.
+- R31 multi-writer merge (spec'd) → foundation for B1/B8.
+- R32 studio recall-debug (spec'd) → §6.
+- GAP-1 write-time citation verification, GAP-2 lifecycle hooks, GAP-3 freshness gate: shipped.
+- R17 P0 defects (cache self-destruction, stat storm, `/bin/sh -c`, dead features): fixes not yet landed.
+- SyncPackets + gossip pool: already the right team-sync primitive (§5).
+
+**Implement (net-new, not covered by existing branches):** A1–A13, B1–B12, B14 — full mechanism catalog above; each lands as its own commit against the P0/P1 lanes in `.agents/context/roadmap.md`.
+
+**Deprecate / remove (now demonstrably dead weight):**
+1. `benchmark/suite.ts` mislabels (D13) — replace with honest harness feeding R27.
+2. Four dead-code paths (B9: `dedup`/`checkConflict` never passed, `recordRetrievals` uncalled, `maybeAutoOptimize`/`touchActivity` uncalled) — wire or delete; docs must not claim shipped.
+3. `vector.ts` char-trigram hybrid search — superseded by R21 real embeddings; keep only as the zero-dependency fallback until embeddings ship.
+4. Full-file injection path in `get_context` — replace with never-drop manifest TOC (A7).
+5. Optimizer regex deletion (B5) — replaced by A13 tombstones + B7 stamped expiry; delete verb disappears entirely (birkin discipline: no delete verb in any curation surface).
+6. `autoCompileWiki` + `syncConstraints` on every `openStore` — dirty-gated (R17 P0 #3).
+
+---
+
+## 5. Server Mode — "team memories on one self-hosted instance"
+
+**Constraint verdict from research**: keep SQLite (ADR-001); add a **transport**, not a database. Recommended stack:
+1. **Remote access = MCP Streamable HTTP** (spec 2025-06-18; the HTTP+SSE transport is deprecated). Same Bun binary, second listener; MUST validate Origin, bind 127.0.0.1 when local, `Mcp-Session-Id` + `MCP-Protocol-Version` headers, SSE `Last-Event-ID` resumability so a dropped stream cannot silently lose a `memory_capture`.
+2. **Multi-tenant = per-tenant DB file** (tenant resolved from auth token). Strongest isolation with least code; a cross-tenant bug is a wrong path, not a leaked row. (Postgres RLS is the alternative only if we ever leave SQLite.)
+3. **Sync = extend `src/sync/pool.ts`** from filesystem drop-dir to HTTP POST against the team endpoint; the **YAML mirror + git remote** is the human-reviewable distribution path (ADR-002 already makes memory diffable).
+4. **Backups/DR = Litestream** (single sidecar, S3-compatible target, any host: MinIO/Backblaze/bare metal). Nothing else adds a process.
+5. **Individual users**: unchanged — local/global `.memory/`, stdio MCP, zero network dependency.
+
+**Rejected**: LiteFS (FUSE+Consul, beta), Corrosion (mesh daemons), rqlite/dqlite (HTTP data-layer rewrite), cr-sqlite (wrong abstraction level), PGlite (single-connection dead end), Electric+Postgres (correct only if we outgrow this; read-path only + proxy requirement), Syncthing for the live `.db` (unsafe; fine for the YAML mirror), Redis/Valkey (daemon, no gain). **Safest multi-writer** if the team later demands it: one-region Postgres + RLS (force RLS, non-owner role; beware owner/superuser/TRUNCATE bypasses) with SQLite clients as read cache — never two-way SQLite↔Postgres sync.
+
+**Known limit (must be documented, not silently shipped)**: git-mirror sync inherits git merge semantics — concurrent edits of the same YAML produce a textual conflict needing human resolution. Safer than silent LWW, not zero-touch.
+
+---
+
+## 6. Dashboard Rehaul (R32 + lancedb-suite + xraysight patterns)
+
+Target surface (granular control per user request):
+1. **Memory browser** with per-factor score breakdown ("why was this retrieved") — R32 + A12 typed drop reasons on both kept and rejected.
+2. **Provenance & lineage view** — memory graph from `linked_memory_ids` + lineage BFS + `fact_provenance` rows; inline ADR/drift links.
+3. **Eval panel** — R27 recall-set grading (must-return/must-not-return, abstention, noise) with p50 latency beside it; one-click fixture freeze (birkin discipline).
+4. **Lifecycle control tower** — trust-tier/decay state, tombstones & restore, stamped-expiry policy editor (pin rules), optimizer proposals (never auto-delete).
+5. **Config honesty panel** — WIRED/DORMANT/UNREAD audit output; fail-loud indicators for removed security keys.
+6. **Team mesh view** (server mode) — per-tenant stores, sync pool state, admission ledger, Litestream replica health.
+7. **Read-only inspector pattern** (xraysight): UI never writes directly; every mutation goes through the same validated write path (locking, mirroring, FTS maintenance).
+
+---
+
+## 7. "Always-On Memory" vision — auto start / auto improve / auto fetch / never forget
+
+| Wish | Mechanism (already identified) |
+|---|---|
+| Auto-started | GAP-2 lifecycle hook pack (shipped) + Streamable HTTP server mode (§5) + config-carrying cron reconciliation (cashew) |
+| Auto-fetched | Ambient recall with abstention gates (A3/A6), never-drop manifest (A7), echo suppression (A5), trivial-turn gate, generation-counter invalidation |
+| Auto-improved | Event-triggered consolidation on compaction/step-count (B4), two-mode consolidate (B8), decay/refresh policies (A1/A2/B9), feedback auto-tuner (memoria) |
+| Always remembered | ADD-only append, tombstones (A13), audit replay restore, hash-chained audit (B3), head-moves-last snapshots (pubky), **no delete verb** in any surface |
+
+---
+
+## 8. Identity & Code-Identity Audit (this commit)
+
+- `package.json`: `author` set to **"Harsh Singh"** (was "Harsh"). Repo URLs keep `harshsinghmp` (allowed).
+- Repo-wide grep: no personal emails/identities in code, docs, or configs. Git author placeholder is neutral.
+- Competitor identity audit of `src/`: competitor names appear **only** in functional paths — `src/migrator/*` (import format detection for agentmemory/mem0/letta/everos) and `src/agents/registry.ts` (platform detection incl. letta-code binaries). No marketing/comparison identity ships in code. The competition list lives here + `musememory-comparison.html` (non-code artifacts).
+
+---
+
+## 9. Sources
+Per-repo raw READMEs/APIs cited in each teardown lane; consolidated URL set accompanies this file in git history. Primary anchor repos: mem0ai/mem0, volcengine/OpenViking, moorcheh-ai/memanto, matrixorigin/memoria, BetterDB-inc/monitor, indigokarasu/chronicle, ashmoonori-afk/birkin-mnemosyne, RohiRIK/OpenLtm, Ufonik88/EntropicMem, MaxFreedomPollard/Compartment, Nacho-Labs-LLC/hermes-plugin-nachos, udjin-labs/hermes-mnemostack, hoysama/hermes-intelligent-memory, ottosulin/hwiki, 3L0935/hermes-lancedb-memory-suite, fred0m/hermes-memobase-provider, Pinutss/jev-memory-selector, kuehnberger/hermes-qdrant-memory, cnkang/hermes-plugin-qdrant-memory, padding lanes as noted. DB/transport: modelcontextprotocol.io spec 2025-06-18 (transports + authorization), litestream.io, litefs, libsql/sqld, rqlite, dqlite, pglite.dev, electric-sql, postgresql.org RLS docs, syncthing.net FAQ, valkey.io, lancedb docs.
+
+---
+
+## 10. CONSOLIDATED IMPLEMENTATION CATALOG (all 15 lanes)
+Supersedes the ad-hoc tier lists in §3 for planning purposes. Every item: mechanism ← source(s). Items already spec'd on existing branches are marked (R##).
+
+### Wave P0 — correctness & reliability (v2.4.0; ~700 LOC total; each item is a separate commit)
+1. Query-cache self-destruction fix (`store.ts:281`) ← audit R17
+2. Ranking hot-path: memoized file verification + precomputed token sets ← audit R17
+3. `openStore` dirty-gate for wiki recompile + CURRENT.md sync ← audit R17
+4. Bounded FTS preflight; single-transaction writes; FTS↔row parity + repair ← audit R17
+5. `/bin/sh -c` removal in `memory verify` ← audit R17 (critical security; captured as negative memory)
+6. Wire 4 dead features or delete: `dedup`, `recordRetrievals`, `maybeAutoOptimize`, `touchActivity` ← audit R17
+7. Tombstones + `memory_restore` + audit-replay restore (replaces optimizer regex deletion) ← R30 + cognition-memory + holographic (forget tombstone + `secure_delete` VACUUM)
+8. `Math.max` spread crash + IDF caching + redundant list() in hybridSearch ← audit R17
+9. **Idempotency layer**: `idempotency_key` UNIQUE on capture (retry→0 writes; divergent retry→named conflict naming existing id) + whitespace/case-normalized `content_hash` dedup ← xmemo + yantrikdb + memos + lancedb
+10. **Write outbox / admission ledger**: durable `pending→processing→sent/held/failed` states, `recover_stale_locks(300s)`, `auto_replay=0→held` for non-idempotent ops, append-only fsync JSONL event log with single-writer flock that fails loud ← xmemo + qdrant-memory + optchat
+11. **`on_pre_compress` extraction**: fact/memory capture before compaction, digest-deduped with persisted digest set, never-empty checkpoint ← lancedb + holographic + cortexlayer (closes "compaction ate my memory")
+12. **Wake gate**: background passes only wake the agent when an explicit actionable-keys allowlist matches; exit 0 always ← hermes-dreaming
+13. **Overnight loss guard**: snapshot entry-head hashes; >25% entry/char loss → alert-only, restore nothing ← hermes-dreaming
+14. **memory_pressure as first-class event**: store near char/size ceiling alerts instead of silently refusing writes ← hermes-dreaming
+15. **Honest token accounting**: any auto-compaction commits only if the payload shrinks under BOTH the harness estimate and a pessimistic (image/long-text) cost model ← snapcompact
+16. Refuse-incomplete contract: never emit a partial `get_context` digest; raise/retry instead ← optmem (`WakeNeedsCompression`)
+17. Circuit breaker around every store path (5 failures → 120 s cooldown → degraded "no memory", never a stalled turn) ← cognee-integrations
+18. `atexit` bounded join for any async write worker; generation-counter invalidation for in-flight prefetch ← zvec + gbrain-pointer
+19. Read-path re-validation: entries containing injection markup/credentials/invisible chars excluded from recall, logged once, still visible in search/list ← holographic
+20. Safe FTS5 query construction (quote every token — audit: possible live injection in any FTS MCP tool) + compound-token expansion (camelCase/snake_case split; +36pp Recall@5 claim) ← hwiki + loreconvo
+21. Clamp model-supplied `limit` values; dry-run-by-default, point-id-only destructive ops ← kuehnberger qdrant
+22. Read-path `stale:true` provenance tag for degraded/cache reads ← xmemo
+
+### Wave P1 — memory quality engine (v2.5.0)
+23. **Abstention gates** (consolidate the ecosystem's convergence): IDF-weighted relevance gate before FTS5 (holographic `relevant()` 0.3, identifier-decisive, greeting short-circuit) + dual calibrated thresholds (lancedb-suite `SEARCH_MAX_COSINE_DISTANCE`/`SEARCH_MIN_BM25_SCORE` + engine-pin constant) + FTS5-tokenizer-matched gate (EntropicMem) + `no_confident_match` (limbic)
+24. **Decay & forgetting engine**: materialized `decay_score` column with importance-gated half-lives (OpenLtm) + veracity tiers with Bayesian `1-0.7^n` confidence (mnemosyne) + trust-tier-keyed half-life T1 365d/T2 180d/T3 60d/T4 30d (memoria) + per-type `expires_at` (sugar) + stamped expiry `status/expired_at/expired_by` with pin-capable first-match-wins YAML policy (memanto) + optional Weibull per-type curves (memex8 — re-derive, don't port constants)
+25. **Bitemporal discipline**: `valid_to_exact` flag + `as_of` queries returning `{results, undetermined}` (store invents no dates) + five-verb lifecycle change/end/correct/revert/forget + `searchTemporal(atTime)` default-excluding superseded (holographic + memos)
+26. **Contradiction**: keep-both conflicts table (never delete) + scoped invalidation requiring (entity, relation, target) alignment + federation handshake for mesh mode (mnemosyne + Graphiti #1728 lesson)
+27. **Veracity/provenance trust table**: user_input 1.0 / agent_inferred 0.7 / external_data 0.5 / system 0.3 as rank boost + filter; `src_ts` evidence-age stamping (a memory is only as fresh as its evidence) ← memos + deja-vu
+28. **Context packing**: TOON-style row-wise compaction of context packs (claimed 77.6% vs JSON — verify ourselves) + never-drop manifest TOC with descending summary caps (entry line never omitted) + truncation order `pin > provenance > recency > salience` with mandatory `[N omitted — budget M]` marker + reserved slots for global/USER.md-class entries ← memos + nachos + cognition-memory + sugar
+29. **Memory graph**: `linked_memory_ids` write-time edges seeded during capture (mem0) + supersede-not-delete with hidden-count-aware over-fetch (HyAtlas) + `prefer_observations` recall-time dedup scoped to top-2×budget (hindsight) + progressive wikilink expansion after fusion (ReMe)
+30. **Provenance & audit**: `fact_provenance` append-only table with triple-unique index + `supersedes_id`/`conflicts_with_id` lineage FKs + lineage BFS walker + hash-chained audit + session Merkle checkpoints + index-time credential redaction keeping text searchable ← intelligent-memory + R17 + deja-vu
+31. **Write gates**: `scoreRetain` 0.3 (refuse junk writes) + corroboration-gated promotion (≥2 independent days, machine-generated sources hard-excluded) + curator concept (agent appends evidence; deterministic promotion decides records) + two-tier promotion (cheap pending tier → explicit session-end flush) ← memos + hermes-dreaming + brethof + cognee
+32. **Recall hygiene**: re-injection suppression per session (6-turn LRU) + self-echo suppression via capture-side provenance (age-bounded) + `<memory-context>`/injected-block strip before capture + seen-chunk TTL + topic-overlap >0.6 prefetch skip + trivial-prompt gate ← holographic + mnemostack + tam + ReMe + icarus + agent-memory-es
+33. **Ranking upgrades**: soft-OR evidence fusion `P=1-(1-pv)(1-pl)` with fixed-bound cosine→prob and multiplicative priors (Compartment) + `low_discrimination()` conditional rerank (memobase) + semantic threshold gate BEFORE BM25/entity fusion (mem0) + watermark staleness measured from `last_memory_seen_at` (hindsight) + query-intent bias multipliers (memex8) + `effective_score = base × reinforcement × decay` (nexus) + RRF weight tuning + typed drop/keep reasons (jev)
+34. **Token-cost cuts**: L0/L1 generated abstract sidecars with ratio-batched refresh (OpenViking — reimplement, AGPL) + resident INDEX route-map (birkin) + tier budgets as named constants with provenance (EntropicMem/pastdotdev/nachos)
+35. **Observability**: `why_retrieved` deterministic reason tokens + recall→usage telemetry join (`usage_rate = used∩recalled/recalled`, feeds ROI) + `[DRAFT]` marking with separate confident-answer key + config-honesty AST audit (WIRED/DORMANT/UNREAD, build-failing) + storage-version compat tests + honest benchmark labels ← EntropicMem + icarus + chronicle + lancedb + R17
+36. **Constitution contract**: CURRENT.md-class rules injected first, exempt from trimming, no MCP write tool ← yantrikdb
+37. **Failure visibility**: `degraded − notes` fault signal (mnemostack); ground-moved reporting for anchors, silent when undeterminable (deja-vu); tiered retrieval ladder that labels loosened matches (deja-vu)
+38. **Semantic retrieval**: local embeddings (R21 spec branch) with engine fingerprint pinning, FTS5-floor/vector-upgrade degradation, brute-force cosine in SQLite BLOB — never an ANN daemon; embedder stamp `stale_embedder` flag ← R21 + OpenLtm + limbic + yantrikdb
+39. **Eval harness** (R27): recall-set grading (must/must-not return, abstention, noise as hard failure) + frozen benchmark corpus discipline + p50 latency beside scores + fixture promotion requires usage telemetry ← R27 + birkin + PrecisionMemBench/LongMemEval
+40. **fix-pair mining**: error→command→no-recurrence sequences from transcripts become negative-memory candidates ← deja-vu
+
+### Wave P2 — team, server & UI
+41. **Server mode**: MCP Streamable HTTP transport (Origin validation, session id, protocol version, SSE resumability) + per-tenant DB files + extend `sync/pool.ts` to HTTP + git/YAML-mirror distribution + Litestream sidecar for backups; solo users unchanged ← DB lane
+42. **Dashboard rehaul**: recall-debug per-factor breakdown, provenance/lineage graph, eval panel, lifecycle control tower (trust/decay/tombstone/restore), config-honesty panel, team mesh view; read-only inspector pattern (UI never writes) ← R32 + xraysight + lancedb-suite
+43. **Always-on memory implementation**: event-triggered consolidation on compaction/step-count + dual-trigger maintenance cadence (N turns AND wall-clock) + cron ownership-token reconciliation with embedded effective config + wake gates (P0-12) + circuit breakers (P0-17) ← Letta pattern + yantrikdb + cashew + dreaming + cognee
+44. **Hermes interop adapter**: ship a Hermes `MemoryProvider` backed by Muse MCP (catalog submission; the qdrant feature branch becomes a remote-vector-backend adapter behind the same Store interface, opt-in only)
+45. **Federation**: cross-store contradiction dedup handshake with fail-closed probes outside write locks (mnemosyne) for mesh mode
+46. **Team semantics**: observer/observed directional memory queries (honcho concept, reimplement — AGPL) + peer/namespace scoping + reserved slots per peer
+47. **Memory forking/branching** + git-worktree-analog overlays (R31 + memoria-style safety snapshots before governance)
+48. **Graph retrieval — GATED**: HRR/PPR/wikilink expansion only behind the P1 eval harness with graph-on/graph-off A/B (HippoRAG v1 regressed factual recall; holographic HRR is the closest prior)
+49. **Funded/shared memory pools** + sponsored storage model (Walrus delegation) — spec only, agency-network monetization
+50. **Memory marketplace**: transfer memories with permissioned grants (Walrus docs flag as future) — spec only
+
+### Explicitly REJECTED (with reasons — prevents re-litigating)
+- Qdrant/LanceDB/Zvec/Hydra/Metronix as default stores: daemon or dependency violations (ADR-001). Vector backends only as opt-in adapters.
+- Hermes §-delimited MEMORY.md format as our canonical format: our YAML mirror + SQLite is strictly better for this engine; interop via adapter only.
+- Multilingual stemming (holographic's 18 languages), CJK n-grams (dreaming): defer until i18n demand exists.
+- SaaS memory backends (penny, dexio, hicortex, cortexlayer, metronix, hydradb, pastdotdev, brethof, supermemory, xmemo, memanto-remote): opposite of charter; port mechanisms only.
+- AGPL/BSL/PolyForm/no-license code copies (honcho, sugar, loreconvo, limbic, stack-memory, kyssta): idea-only, reimplement.
+- Auto-delete anywhere: every destructive path becomes tombstone + restore (birkin: no delete verb in curation surfaces).
+- Full-file context injection: replaced by manifest TOC + budgets (P1-28).

package/.agents/research/research-brief-walrus-memory-architecture.md

@@ -0,0 +1,189 @@
+# Research Brief: Walrus Memory & Muse Memory Architecture Upgrade
+
+**Depth**: deep
+**Date**: 2026-10-14
+**Status**: COMPLETE
+**Lanes**: lib-1 (Walrus Memory product/architecture) · lib-2 (SOTA AI memory systems) · ora-1 (local gap audit, 30.8k LOC / 113 files)
+**Verification baseline (2026-10-14)**: `bun test` → 502 pass / 0 fail, 85 suites, 2224 expect() calls, 4.16s. Tree on `dev`, clean.
+
+---
+
+## Executive Summary
+
+Walrus Memory (MemWal) is a decentralized, Sui-anchored memory service: content-addressed encrypted blobs on Walrus storage, ownership + revocable delegate keys on a Sui contract, pgvector/HNSW relayer for search. Its genuinely transferable ideas for Muse Memory are (1) content-addressed ids as free dedup + idempotent sync, (2) availability/tamper-evidence proofs via hash-chained append-only records, (3) an explicit extend-before-expiry retention discipline. Its non-transferable parts: relayer + vector-DB-first architecture (violates ADR-001), one-blob-per-memory cost model (64 MB flat per-blob charge; 10k memories ≈ $14.7/mo), and a managed relayer that sees plaintext despite marketing claims.
+
+The SOTA scan (Mem0, Zep/Graphiti, Letta, Supermemory, Cognee, LangMem, A-MEM, HippoRAG, vendor-native) shows the field converging on three axes: **ADD-only append with temporal metadata**, **multi-signal hybrid retrieval fusion**, and **event-triggered background consolidation**. Muse Memory already has stronger lifecycle/invariant machinery than most of them (bi-temporal validity, contradiction engine, code anchors, ROI tracking) — but has two structural weaknesses: no real semantic retrieval (only lexical FTS5 + char-trigram hashed vectors), and the local audit found 10 concrete defects including a self-destructing query cache, a `Math.max` spread crash at 100k entries, an unguarded `/bin/sh -c` exec from memory content, silent FTS/row desync, and four advertised features that are dead code paths.
+
+Verdict: the highest-leverage work is not exotic architecture — it is (a) fixing the audit's P0 defects (3–60 LOC each), (b) adding embedding-backed hybrid retrieval + a retrieval-set eval harness, (c) hash-chained audit + memory lineage for verifiability, (d) wiring the four dead features. Full plan in the roadmap section below.
+
+---
+
+## Walrus Memory: What It Is
+Source: lib-1 lane (docs.wal.app, walrus.xyz, CCS '26 paper arXiv:2505.05370v4).
+
+- **Walrus Memory (MemWal)** — Mysten Labs / Walrus Foundation, Apache 2.0 repo `MystenLabs/MemWal`, beta since Jun 2026 (blog 03 Jun 2026). Stack: Sui contract `memwal:account` (ownership + delegate keys) · Rust relayer (REST: embed `text-embedding-3-small` 1536d → Seal-encrypt → Walrus blob → pgvector/HNSW) · TS+Python SDKs · MCP server (8 tools).
+- **Identity**: memory space = `owner address + namespace + app ID`. Access = onchain Ed25519 delegate keys, revocable; shared-access and service-delegation patterns.
+- **Walrus storage**: RedStuff (Twin-Code over RaptorQ), 4.5× erasure overhead, committee N=1000 shards, tolerates 1/3 faulty, Point-of-Availability certificate from 2f+1 signatures. **Epoch-bought, NOT permanent** — mainnet epoch = 2 weeks; data dies at `end_epoch` unless renewed.
+- **Costs**: $0.023/GB/mo on ENCODED size with a flat **64 MB per-blob metadata charge**. Quilts (batched small blobs) save ~400× but MemWal does not use them → 10k × 1 KB memories ≈ 640 GB billed.
+- **Verifiability (their headline)**: blob ID = content hash; the Sui `Blob` object (ID/size/namespace/end_epoch/owner) is public; `recall` returns `blob_id` + `created_at` per hit → "this decision cited these exact memory revisions". Caveat: `verify()` is roadmap, not shipped.
+
+### Ideas worth stealing for Muse Memory
+1. **Content-addressed memory IDs = free dedup + idempotent sync.** SyncPacket already SHA-256 fingerprints content; formalize `id = hash(content)` addressing so duplicate suppression across agents is structural, not heuristic.
+2. **Cryptographic delegation for the P2P mesh.** Our gossip sync has no identity/authorization layer — peers trust the filesystem. Walrus's delegate-key model (registered, revocable, per-scope) is the blueprint for a signed SyncPacket capability model.
+3. **Availability proof → hash-chained audit.** `audit.jsonl` is append-only but mutable and unverifiable. A per-record `prev_hash` chain plus a periodic session Merkle root gives tamper-evidence and third-party verifiability — the local analogue of Walrus's PoA, at zero dependencies.
+4. **Extend-before-expiry retention discipline.** Our archival lifecycle (cold→dormant→archived) needs an explicit, observable retention/renewal policy — never silent expiry (Walrus's documented failure mode; also Supermemory's forgetting taxonomy and the FSFM "forgetting as security control" paper).
+5. **Sponsored/marketplace memory pools.** Walrus's "publisher transfers Blob to a payer while agent keeps lifecycle control" is the primitive for agency-scale shared memory funding. Long-horizon; keep as roadmap item, not near-term.
+
+### Ideas NOT to copy
+- Relayer + vector-DB-first architecture (violates ADR-001 zero-daemon, local-first).
+- One-blob-per-memory cost model (their own biggest trap).
+- Managed relayer trust (they see plaintext despite marketing claims).
+- Download-then-rebuild-index restore (our YAML mirror already gives local determinism).
+
+---
+
+## Competitive / Ecosystem Landscape (AI Memory Systems)
+Source: lib-2 lane. Tooling note: websearch was HTTP-400 in that session; sources came via Brave HTML, arXiv API, HN Algolia, GitHub API, direct doc fetches. Gemini memory section unverified (404s).
+
+| System | Storage | Retrieval | Lifecycle | Novelty | Score for local-first portability |
+|---|---|---|---|---|---|
+| **Mem0 v3** | Vector + graph + SQL history | 4-signal fusion; temporal metadata at write, **no LLM call at read** | **ADD-only** (reversed v2's UPDATE/DELETE); hash dedup | `absence` as memory type; agent facts first-class | **High** |
+| **Zep/Graphiti** | Bi-temporal context graph (entities/facts/episodes) | semantic + keyword + graph, RRF | `invalid_at` windows, invalidate-not-delete | Episode-as-provenance | Medium (graph cost) |
+| **Letta (MemGPT)** | **Git repo of Markdown** (MemFS) | Deliberately none — file tools + progressive disclosure | "Dreaming" on compaction/step count; agent reviews before applying | Git-as-memory-substrate; sleeping on compaction | **Highest** |
+| **Supermemory** | Fact-based temporal graph (vector+FTS+graph) | `memories/chunks/hybrid` | UPDATES/EXTENDS/DERIVES typed relations; `isInference` down-weight + review queue | Inference flag + human approve/decline; MemoryBench evals | High (but server binary closed) |
+| **Cognee** | Relational + vector + graph | semantic/structural/hybrid | session `remember` → `improve()` feedback-weighted retrieval | Hot session / cold graph split with `_source` tags | **High** |
+| **LangMem** | Collection or Profile | similarity × importance × strength | hot-path vs background write as first-class axis | importance×recency/frequency formula | **High** |
+| **A-MEM** | Zettelkasten notes | LLM link discovery | **retroactive evolution** of prior notes' links/metadata | Memory edits its own history | Medium |
+| **HippoRAG v1/v2** | KG + PPR | single-step PPR beats iterative 10–30× cheaper | — | Graph helps sense-making, hurt factual recall (v1→v2) | Medium |
+| **ChatGPT memory** | saved list + rolling summary | — | "delete" is multi-surface and 30-day-delayed | — | Cautionary |
+| **Claude memory tool** | App-owned files | JIT file read | vendor defines grammar, app executes | `/memories` prefix + path guard | **Highest** |
+
+### Field convergence (the 3 axes)
+1. **ADD-only append + temporal metadata** (Mem0 v3 explicit reversal): storage grows, retrieval disambiguates; dedup goes to exact-hash only.
+2. **Multi-signal retrieval fusion** beats pure vector everywhere — and FTS5 + BM25 is free in SQLite.
+3. **Event-triggered consolidation** (Letta: dreaming on compaction; Supermemory: dynamic vs instant) is where quality comes from — and where inference cost hides.
+
+### Counter-consensus worth heeding
+HN "Agents don't need memory, they need documentation" (297 pts): memory is non-deterministic and costs tokens per retrieval; git-diffable docs never hallucinate. Independent eval (arXiv:2603.04814) shows long-context GPT-5-mini **beats** fact-memory on factual recall; memory only wins on cost after ~10 turns at 100 k context. Multi-hop ceiling: every major system under 55%. Implication for us: **local-first + git-diffable YAML + human-auditable diffs is the right bet; invest in retrieval quality and eval rigor, not in replacing the whole context.**
+
+### Top failure modes reported in the wild (directly relevant to our audit findings)
+1. Silent fact destruction via over-broad invalidation (Graphiti #1728: 41% of a production graph invalidated, no signal). → our contradiction/supersede engine must keep a resolution audit trail.
+2. Delete-that-doesn't-delete (ChatGPT: deletion scheduled 30 days out). → our optimizer regex deletes with no tombstone (audit bug B5).
+3. Concurrency corruption — TOCTOU dedup, racy vector writes (Mem0 #6515/#6243/#4892). → our `INSERT OR REPLACE` silent lost-update (audit bug B3).
+4. Corrupted writes unremovable from vector space. → argues for git/append-only substrates (we have YAML mirror — strengthen, don't weaken).
+5. Prompt-injection poisoning persisting across sessions. → write-time sanitization (we have Vibeguard — extend to content policy, not just secrets).
+6. Retrieval noise is invisible in LLM-judged evals. → grade the retrieval set (PrecisionMemBench style), treat noise as hard failure.
+
+---
+
+## Muse Memory Current Architecture Assessment
+Source: ora-1 lane (read-only; verified against source unless noted).
+
+### Strengths (verified)
+- Fail-fast secret scan on **every** write path incl. peer ingestion (`store.ts:307-313,427-437`, `sync/engine.ts:173-180`).
+- Path-traversal guard on ID→file mapping (`store.ts:130-138`).
+- Properly tuned SQLite config: WAL + busy_timeout=5000 + mmap + foreign_keys (`sqlite.ts:46-52`), dual bun/node drivers.
+- Lifecycle invariants enforced at choke point: `confirm()` allow-list (`store.ts:515`), `supersede()` guards (`store.ts:546-547`).
+- Bi-temporal modeling: `valid_from/valid_to` vs `created_at/updated_at`, decay on event time (`retrieval.ts:206`).
+- Atomic YAML mirror (tmp + rename) with structured degradation (`store.ts:324-332`).
+- Self-skepticism: `verifyStrictIntegrity` audits secrets, broken refs, wikilinks (`verify.ts:151-260`).
+- Structural code identity (line-independent fingerprints) and provider fallback chain.
+
+### Defects found (ranked; evidence in ora-1 report, file:line cited there)
+| # | Defect | Severity | Size |
+|---|---|---|---|
+| D1 | `list()` populates query cache then `setEntry` invalidates it → **0% cache hit rate on every listing** (`store.ts:281-283`, `cache.ts:124,212`) | Critical | 3 LOC |
+| D2 | `openStore()` runs full wiki recompile (O(C²) cross-link) + CURRENT.md rewrite **per MCP tool call with `dir`** (`store.ts:99-104`, `wiki/compiler.ts:187-203`, `governor.ts:430-486`, `mcp.ts:140,1566`) | Critical | ~30 LOC |
+| D3 | `scoreEntry()` does an uncached `stat` storm per anchored entry + `require()` in hot path (`retrieval.ts:199-204`) | Critical | ~15 LOC |
+| D4 | `queryContext` re-tokenizes full memory text on every query; O(N×L) regex (`retrieval.ts:113-122`, `ranking.ts:59,80`) | Critical | ~10 LOC |
+| D5 | FTS preflight unbounded then sliced to 15 (`ranking.ts:249`) | High | 1 LOC |
+| D6 | 3 untransacted auto-commits per write (`sqlite.ts:233-273`) | High | ~10 LOC |
+| D7 | Write amplification: row stores entry twice (`data` JSON + columns) (`sqlite.ts:246-263`) | High | schema migration |
+| D8 | `hybridSearch` recomputes whole-corpus IDF per query; **`Math.max(...arr)` RangeError crash at ~100k, swallowed into silent fallback** (`vector.ts:114-127,154,169`, `engine.ts:145`) | High + latent crash | ~40 LOC |
+| D9 | "tiered" tier 0 saves zero I/O — full store scan regardless (`retrieval/tiered.ts:37`) | Medium | ~10 LOC |
+| D10 | Subprocess spawn (`Bun.spawn codegraph`) per `muse_context` with active file, uncached; passes a file path to a `callers` subcommand (`ranking.ts:258-266`) | Medium | ~10 LOC |
+| D11 | Audit log unbounded; `getAuditTrail` reads entire file (`audit.ts:38,55`) | Medium | ~10 LOC |
+| D12 | Cache returns live object refs; read-path status mutation can poison cache on throw (`cache.ts:153`, `retrieval.ts:308-309`) | Low-Med | ~5 LOC |
+| D13 | Benchmark mislabels full-scan as "FTS5 BM25", hardcodes duplicate rate (`benchmark/suite.ts:145,100-110`) | Low | ~5 LOC |
+| B4 (security) | `verify.ts:25-27` executes `/bin/sh -c <command from memory content>` — the v2.2.1 injection hardening does **not** cover this path | **Security** | ~10 LOC |
+| B5 (data loss) | `optimize.ts:264-281` permanently regex-deletes non-confirmed memories (matches legit `expect(...).toBe` fix notes), no tombstone/undo (`store.ts:713-717`) | Data loss | ~40 LOC |
+| B6 | FTS insert in `try/catch {}` → silent permanent desync; repair only fires when FTS fully empty (`sqlite.ts:266-272,179`) | High | ~15 LOC |
+| B9 | 4 dead features presented as shipped: `dedup`/`checkConflict` never passed by any caller (`mcp.ts:1692`, `cli/lifecycle.ts:39`); `recordRetrievals` never called (`mcp.ts:55`); `maybeAutoOptimize`/`touchActivity` zero call sites (`optimize.ts:362,77`) | Product truth | ~20 LOC |
+| B3 | Concurrent same-id writes = silent last-writer-wins (`sqlite.ts:235`) | High | see roadmap |
+| Untested | `sqlite.ts`, `sessions.ts`, `compress.ts`, `plasticity.ts`, `claims.ts`, `snapshot.ts`, `harvester.ts`, `drift.ts`, `current.ts` have no dedicated tests; cache tested only at class level, never integrated (D1 hides there) | Quality | — |
+
+Scaling estimate (algorithmic, not measured): at 10k memories `get_context` ≈ 200 ms–1.5 s (D3+D4 dominate); at 100k, seconds + D8 crash.
+
+### Capability gaps (verified)
+- **No semantic retrieval**: `src/vector.ts` is a hashed char-**trigram** bag (FNV-1a, 256d) fused 50/50 with BM25 — lexical, not embedding semantics; `hybridSearch` returns null unless a manually-built `index.json` exists (`vector.ts:141-182`).
+- **No memory lineage walker**: `provenance.ts` is a source-URL ledger; lineage is one-hop only (`trace.ts:49`); migrated memories arrive with none.
+- **No forking/branching/merge**, no CAS/version check.
+- **No multi-tenant isolation** (free-text `project` label).
+- **No WORM/tamper-evident audit**: `audit.jsonl` mutable, no hash chain.
+- Contradiction resolution is advertised but unreachable from `memory_capture`.
+- No memory eval harness (nothing grades *which* memories come back).
+
+---
+
+## Upgrade Candidates (merged, ranked by impact ÷ effort)
+
+### Tier P0 — correctness first (patch v2.3.x/minor v2.4.0, ~200 LOC total, near-zero architectural risk)
+1. D1 fix: move `setQuery` after the `setEntry` loop.
+2. D3+D4: memoize runtime file verification (TTL'd map) + precompute token sets once at `save()`.
+3. D5: `{ limit: 50 }` on FTS preflight.
+4. D2: dirty-check gate `autoCompileWiki` + `syncConstraints` in `openStore` (stamp file on count/maxUpdatedAt).
+5. D6: single transaction around row+FTS writes (follow `optimize.ts:286` pattern).
+6. B4: remove `/bin/sh -c` — run parsed argv only, or drop auto-exec and require explicit user invocation.
+7. B6: broadened FTS backfill (`< 0` not `=== 0`) + parity check in `verifyStrictIntegrity`/doctor.
+8. B9 wiring: `dedup` default-on in `memory_capture` (cheap exact-fingerprint; `checkConflict` stays opt-in until contradiction scoring improves); call `recordRetrievals` on retrieval hits; wire or delete `maybeAutoOptimize`/`touchActivity`.
+9. B5: snapshot deleted entries into `audit.jsonl` details + `memory_restore` replay; or soft-delete with `deleted_at`.
+10. D8: `reduce` instead of spread `Math.max`; cache IDF/avgLen; drop redundant `list()` in `vector.ts:154`.
+11. D9: make tier 0 actually cheap (bounded manifest scan) or document it honestly.
+12. D12: return deep-enough copies from query cache or drop query cache.
+13. D10: cache provider availability + blast-radius results (and fix the file-path→`callers` mistake).
+14. D11: rotate audit.jsonl at ~50 MB; tail-read in `getAuditTrail`.
+15. D13: honest benchmark labels + measured duplicate rate.
+
+### Tier P1 — capability upgrades (v2.5.0)
+16. **Real semantic retrieval** (lib-2 axis 2): local embeddings (e.g. `@xenova/transformers` bge-base or hash-embed quantized fallback) + hybrid fusion with existing FTS5/BM25; background index build wired into the capture path (kills the `index.json` manual step). Keep zero-daemon: embed in-process, CPU.
+17. **Memory eval harness** (PrecisionMemBench + LongMemEval style, lib-2 §13.7): `memory eval` command asserting exact must-return / must-not-return memory IDs per fixture; noise as hard failure; **abstention** as a first-class metric. This is what would have caught D1 and D8 — unit tests never integrate the store.
+18. **Hash-chained audit + session Merkle checkpoint** (Walrus verifiability, local): `prev_hash` chain in `audit.jsonl`, periodic root stored in `.memory/checkpoints.jsonl`, `memory verify-chain` CLI. Tamper-evident without any chain dependency; makes P2P SyncPackets verifiable.
+19. **Memory lineage walker** (U9 + Mem0/Zep provenance): BFS over `supersedes ∪ superseded_by ∪ related ∪ evidence[].source`, depth-capped; `memory lineage <id>` CLI + MCP tool. "Why is this true now?" across generations.
+20. **Scoped invalidation discipline** (Graphiti #1728 lesson): supersede/conflict only when (entity, relation, target) align; keep a resolution trail — never silent `invalid_at`-style loss.
+21. **Inference down-weighting + review queue** (Supermemory): flag distilled/derived candidates `isInference`, down-rank until confirmed, review queue ordered by support count (`parentCount` analogue = `supporting_evidence.length`). We already have candidate→confirm gating — this makes it visible and ordered.
+22. **Compaction-triggered consolidation** (Letta): fire the existing distillation engine on compaction events and after N steps, not only timer; "review before applying" second pass for agent-authored candidates.
+23. **Access-frequency strength in ranking** (LangMem): add recently/frequently-accessed signal to the 11-dimension model — with D1/D12 fixed, this is honest telemetry.
+24. **CAS/versioned writes** (B3 + Mem0 TOCTOU lessons): `update_if_version` on memory ids so concurrent agents surface conflicts instead of silent lost updates; feeds a future merge UX.
+25. **retrieval-noise + hot/cold telemetry** (Cognee): tag each recall hit with `_source` (HOT.md / FTS / vector / distilled) — cheap, and it feeds both ranking and evals.
+26. **Docs honesty pass**: current.md bullet count of "shipped" claims vs actual wiring; fix the 4 dead-feature claims, benchmark labels.
+
+### Tier P2 — horizon (roadmap already; now evidence-backed)
+27. Multi-tenant/namespace isolation (RLS-style store scoping) — required for the agency multi-client framing; also the security boundary for injected per-client memories.
+28. CRDT convergence for the P2P mesh (replace last-writer-wins gossip merge; per-field merge + conflict surface).
+29. Memory forking/branching for parallel agent workstreams (git-worktree-analog per agent; merge via ADR-style reconcile).
+30. HippoRAG-style PPR retrieval — but **gated behind the eval harness** (v1 regressed factual recall; A/B graph-on/off before adopting).
+31. A-MEM Zettelkasten retro-link evolution — LLM cost high; defer.
+32. Optional durable-sync sink adapters (Walrus/S3/IPFS) for encrypted cross-machine backup — behind the hash-chain; local-first remains the default; sync-per-option, not a dependency.
+33. Funded/shared memory pools + sponsored storage (Walrus delegation) — the agency-network moneteering story; spec only.
+34. Autonomous memory optimizer, v2: heuristic pruning is D5-adjacent dangerous (regex deletion); replace with: candidate-scored proposals + human/agent confirm + rollback via audit replay.
+
+---
+
+## Proposed Roadmap Updates (applied to `.agents/context/roadmap.md`)
+- New research milestone R17 recorded (this brief + audit).
+- Roadmap restructured into P0 (v2.4.0 Patch: Correctness & Performance Hardening), P1 (v2.5.0: Semantic Retrieval, Verifiability & Evals), P2 (existing enterprise/mesh horizons + graph retrieval, durable sinks, funded pools).
+- Original 3 future items preserved (distributed telemetry, autonomous refactoring engine, RBAC enclaves) with the new evidence cross-referenced.
+
+## Risks and Open Questions
+1. ora-1 latency figures are algorithmic estimates, **not measurements** — confirm with the (now fixed-label) benchmark after P0 lands before promising scale numbers.
+2. Semantic embeddings add a runtime dependency + model weight download (~100–400 MB) — conflicts with zero-daemon portability unless lazy-loaded and optional (design carefully; P1 item 16 must keep a pure-FTS5 fallback).
+3. `checkConflict=true` by default is deferred: current Jaccard+regex scoring will false-positive at scale (ora-1 verified).
+4. Duplicate the D8 crash fix before any large-store migration path ships.
+5. lib-2's Gemini section is unverified; websearch was unavailable in that session — minor, no Gemini-specific roadmap item depends on it.
+6. lib-1 could not confirm MemWal's free-tier limits; the Walrus adapter is P2 regardless.
+7. The audit read `mcp.ts` selectively (~150 of 2,608 lines) — residual risk of additional per-request work in unexamined tool bodies; P0 item 2's dirty-check plus a `memory doctor` per-call timer will surface any remainder.
+
+## Sources
+**Walrus Memory (primary)**: product page walrus.xyz/products/walrus-memory · docs.wal.app (llms-full digest) · core-components / how-storage-works / memory-space / ownership-and-access / verifiable-memory / where-to-store-agent-data / api-reference / public-relayer / versioning / permanent-registry-design · repo github.com/MystenLabs/MemWal · blog "memwal-long-term-memory-for-ai-agents" + "introducing-walrus-console" · CCS '26 paper arXiv:2505.05370v4 · RedStuff docs (docs.wal.app/docs/system-overview/red-stuff.md, red-stuff-parameters.md, storage-costs.md, quilt.md) · Third-party: blocksandfiles 31 Mar 2026, dev.to Filecoin-vs-Arweave-vs-Walrus, tatum.io/blog/walrus-memory.
+**SOTA (primary/paper)**: Mem0 arXiv:2504.19413 + docs.mem0.ai migration v2→v3 + architecture.md · Zep/Graphiti arXiv:2501.13956 + repo (search_utils.py constants) + issue #1728 · Letta docs (configuration/memory, MemFS, context-constitution) + MemGPT arXiv:2310.08560 · Supermemory docs (llms.txt: searchMode, UPDATES/EXTENDS/DERIVES, isInference review queue, self-hosting, SMFS) + MemoryBench (MIT) repo · Cognee docs (architecture, data-flows) · LangMem conceptual guide + LangGraph memory docs · A-MEM arXiv:2502.12110 · HippoRAG arXiv:2405.14831 + HippoRAG 2 arXiv:2502.14802 · ChatGPT memory FAQ (help.openai.com 8590148) · Claude memory tool docs · Sleep-time compute arXiv:2504.13171 · SleepGate arXiv:2603.14517 · FSFM arXiv:2604.20300 · SSGM arXiv:2603.11768 · LoCoMo arXiv:2402.17753 · LongMemEval arXiv:2410.10813 · MemBench aclanthology 2025.findings-acl.989 · MemoryAgentBench (HUST-AI-HYZ) · independent cost eval arXiv:2603.04814 · agent-memory-bench (hamza-dev-tech).
+**Community signals**: HN "Agents don't need memory, they need documentation" (297 pts/173 comments); r/LocalLLaMA Feb 2026 compaction thread; r/ChatGPT memory-loss threads; Mem0 issues #6515, #6243, #4892, #2758; Graphiti issues #868, #1116; ETH Zurich LLM-generated-context-file finding (-3% quality, +20–23% cost).

package/.agents/research/retirement-audit-2026-10.md

@@ -0,0 +1,45 @@
+# Retirement & Hygiene Audit — 2026-10-14
+
+Two independent read-only lanes (surface inventory + judgment audit), reconciled. Baseline: 30,787 LOC `src/`, 12,450 LOC tests, 101 MCP tools (104 dispatch cases, 0 orphans), 165 npm downloads/month.
+
+## Headline
+
+There is almost nothing dead to delete. The cleanup is **drift**: hand-maintained name lists that no longer match the registered surface, and two write paths where disk shadows the database. The one true defect outranks every cleanup row: `verify.ts` executes memory-supplied strings through `/bin/sh` (RCE-class). Fix that first, then the free drift rows, then the deprecations.
+
+## Verdict table (risk-adjusted, safest first)
+
+| # | Item | Evidence | Verdict |
+|---|---|---|---|
+| 1 | 6-profile system: 7 phantom tool names silently dropped | `orchestrator/profiles.ts` (`memory_record_observation`, `memory_capture_negative`, `memory_conflict_detect`, `memory_wiki_page`, `memory_tree_index`, `memory_dedup`, `memory_audit_query` — none registered) | FIX registry (free), KEEP mechanism; default-profile change is a v2.5 decision (see below) |
+| 2 | `ALL_MEMORY_TOOLS` allowlist: 3 phantom names auto-approved, 61 real tools omitted | `connect.ts:9-50` (40 names) written into `settings.json` `allowedTools` at `:160` | RETIRE array; write nothing or `["*"]` |
+| 3 | `maybeAutoOptimize` | `optimize.ts:362`, 0 callers (superseded by dashboard/CLI optimize path) | RETIRE |
+| 4 | LSP intelligence tier | `intelligence/lsp.ts:16` `_lspActive = false`; only setters are internal → `isAvailable()` unreachable; 1413 LOC | RETIRE (keep the provider slot in the chain signature) |
+| 5 | 4 unused registry methods + `registerProvider` | `intelligence/registry.ts:68-117`, 0 external call sites (only `getBlastRadiusWithFallback` used) | RETIRE (~70 LOC + adapter impls) |
+| 6 | `musememory-comparison.html` at repo root | 63KB, not in npm `files`, research residue per identity rules | RETIRED in this change: moved to `docs/research/`, README link updated |
+| 7 | 3 dead governor exports | `governor.ts`: `registerAgentWorkstream`, `linkMemoriesToSession`, `isValidConstraintLine` — 0 refs | RETIRE |
+| 8 | 20 of 24 migrator providers → GenericAdapter | `migrator/detect.ts` reports hits for 20 providers with only 4 real parsers (`agentmemory`, `beads`, `letta`, `generic`); mis-imports silently | DEPRECATE the 20 (delete before adapters, never after — stale detectors mis-import data) |
+| 9 | YAML mirror read precedence | `store.ts:174-202` reads YAML first and re-imports disk into SQLite (`:193-196`): hand-edited YAML silently overwrites DB (same silent-LWW class as the concurrent-write bug) | KEEP the mirror (63 module imports route through it; largest blast radius in the repo), FLIP `get()` to DB-first (~6 lines) |
+| 10 | Dockerfile test-on-build | `Dockerfile:12-13` runs `bun test` + `tsc` at image build; npm-excluded anyway | RETIRE |
+| 11 | 20 dormant connect platforms | `agents/registry.ts` = 52 entries; `nullclaw`/`nanoclaw`/`picoclaw`/`ironclaw`/`zeroclaw`/`pool`/`ante`/`san`/`tau`/`waveloom`/`openharness`/`codewale` class rows never installed; detection already marks `installed=false` | DEPRECATE (freeze the list), and fix the "80+" README claim to the real count |
+| 12 | CLI `recall` vs MCP `search` vs `get_context` | three retrieval paths with different default limits | DEPRECATE `recall` as a separate path (keep as alias) |
+| 13 | `verify.ts` `/bin/sh -c` | `verify.ts:23` execs `entry.test_command` (memory content, MCP-writable by any connected agent) | FIX — outranks every row; lateral-movement primitive on every install |
+| 14 | Studio UI XSS + optimizer endpoint | `ui.ts:1510` injects `p.title`/`p.slug`, `:1557` injects `r.entry_id`/`r.actor` into innerHTML (unescaped, despite `escapeHtml` at `:1588`); `/api/optimize` (`ui.ts:362`) exposes the regex-deleting optimizer over HTTP; 47+ routes on 127.0.0.1:2222 | KEEP the surface, FIX the injection + gate the optimizer endpoint |
+| 15 | `daemon.ts` docs drift | README markets "WebSocket Hub"; implementation is SSE, opt-in via `memory daemon` | KEEP, fix README |
+| 16 | 12 "circular" MCP tools + 20 full-profile-only zero-test tools | asserted only in `test/mcp.test.ts` registration smoke, or not at all | FIX (hygiene): real dispatch tests or documented-untested |
+| 17 | CodeGraph/Graphify chain tiers | gate on `.codegraph/`/`.graphify/` existence; self-disabling | KEEP |
+| 18 | YAML mirror full delete | breaks bootstrap/store tests/README git-diff claim; buys one write/commit | KEEP (row 9 supersedes) |
+| 19 | All 101 MCP tools | 0 orphans; bloat is cost, not dead code | KEEP; tool-bloat reduction rides the R17b P2 dashboard/tool-packaging work |
+
+## Cheap evidence tests before acting on 8/11
+
+```bash
+grep -rn "GenericAdapter\|provFilter" src/migrator/engine.ts      # which providers actually parse
+memory detect-agents --json | jq '[.[]|select(.installed)]|.id'   # on 3+ machines over 90 days
+```
+
+## Notes
+
+- Rows 1-3 and 7 are free: pure list-vs-registry drift, no runtime path, no migration.
+- Row 13 is a security defect, not retirement. Ship before any cleanup lands.
+- Row 14 makes `ui.ts` the second-priority code fix after row 13.
+- Executed in this change: row 6 only (pure move). Everything else awaits principal go-ahead.