musememory 2.2.1 → 3.0.0

package/.agents/artifacts/bench-graph-baseline.md

@@ -0,0 +1,139 @@
+# Graph baseline — Workstream C, measurement pass
+
+**Date**: 2026-10-01
+**Harness**: `scripts/bench-graph.ts` (`bun run bench:graph`), raw run data in
+`.agents/artifacts/bench-graph-baseline.json`
+**Scope**: measurement only — no source file was edited to produce these numbers.
+
+## Method
+
+The harness boots the real `startUiServer()` in-process on a throwaway port against a
+synthetic store, seeds memories through the public `propose()` API (one structural link
+each), then measures the server over `fetch` and the client over Playwright.
+
+- Sizes 100 / 1,000 / 10,000 memories; seeds are cached under `/tmp/muse-bench-graph/<n>`
+  and reused on later runs (`--fresh` re-seeds).
+- Server numbers are the median of 5 warm calls; the first (cold) call is in parentheses.
+- Client numbers are the **median of 3 chromium repeats** by first graph paint, with the
+  spread shown — a single sample is not a baseline, chromium startup jitter is
+  non-monotonic (one run at 100 memories measured 1,965 ms where two others measured
+  ~200 ms, with no corresponding long task).
+- First graph paint is probed from page pixels (`drawImage` → `getImageData` on a 32×18
+  downscale of `#graphCanvas`), so it cannot be faked by a blocked main thread.
+- The Google Fonts CDN is blocked by default (`--cdn-fonts` to allow it) so the client
+  numbers measure the dashboard rather than an unreachable network dependency. See F6.
+
+## Server-side
+
+| memories | store | /api/memories | /api/snapshot | /api/stats | /api/search |
+| ---: | ---: | ---: | ---: | ---: | ---: |
+| 100 | 100 | 0.8 ms / 90.0 KB | 1.0 ms / 90.1 KB | 0.7 ms / 0.2 KB | 4.3 ms / 22.5 KB |
+| 1,000 | 1,000 | 6.5 ms / 905.6 KB | 5.5 ms / 905.7 KB | 7.7 ms / 0.3 KB | 31.0 ms / 22.7 KB |
+| 10,000 | 10,000 | 81.2 ms / 9,105.5 KB | 73.1 ms / 9,105.5 KB | 53.8 ms / 0.3 KB | 339.1 ms / 22.8 KB |
+
+Payload growth is linear at ~0.9 KB per memory. `/api/stats` costs 53.8 ms to return a
+0.3 KB body because the handler iterates every memory in JS to build `typeCounts`.
+
+## Client-side
+
+| memories | first graph paint | DOM nodes | graph nodes | graph edges | long tasks | interaction |
+| ---: | ---: | ---: | ---: | ---: | --- | --- |
+| 100 | 213 ms (197–1,965 over 3 runs) | 1,714 | 100 | 198 | 1 / 68 ms (max 68 ms) | 59.9 fps, 0/55 frames >33 ms |
+| 1,000 | **268 ms** (260–310) | 11,614 | 1,000 | 1,998 | 2 / 191 ms (max 116 ms) | **loop dead — 0 repaints** |
+| 10,000 | **2,028 ms** (2,021–2,087) | **110,614** | 10,000 | 19,998 | 3 / 1,874 ms (max 1,689 ms) | **loop dead — 0 repaints** |
+
+DOM node count is linear at ~11 nodes per memory. Graph node/edge counts match the store.
+
+## Findings
+
+### F1 — the graph canvas dies permanently at ≥1k memories (critical)
+
+```
+IndexSizeError: Failed to execute 'arc' on 'CanvasRenderingContext2D':
+The radius provided (-81.1292) is negative.
+```
+
+`drawGraph` computes `radius = (6 + min(10, degree * 2)) * p.scale`, and `project()`
+returns `scale = (fov / (fov + z2 + 400)) * zoom`. Any node pushed past the camera plane
+(`z2 < -1000`) makes the denominator negative, so the radius goes negative and `arc()`
+throws. With 100 nodes the layout stays inside ±260; at 1k+ the repulsion term
+(`2400 * alpha / dist²`) spreads nodes far enough to cross that plane.
+
+The throw escapes `tick()` **before** `requestAnimationFrame(tick)` is called, which is on
+the last line of the function — so the render loop never reschedules itself. The canvas
+then shows a single frozen frame forever: no pan, no zoom, no redraw on filter change.
+
+Reproduced **3/3 runs at 1,000 and 3/3 at 10,000, 0/3 at 100.** The harness reports this as
+`interaction: loop dead (0 repaints)`; the 0-frame measurement is the defect, not a harness
+gap.
+
+### F2 — the force simulation is O(n²) in a single task
+
+`simulateStep()` iterates every node pair per frame. At 10,000 nodes that is ~50 M pairs
+per frame and 232 frames before `simAlpha` decays to the 0.03 stop threshold. The measured
+single long task is **1,689 ms at t+338 ms**, and it is what pushes first paint to 2 s.
+
+### F3 — `/api/snapshot` and `/api/memories` are the same 9.1 MB payload
+
+Both return `9,105.5 KB` at 10k memories, and the dashboard's `loadData()` fetches the full
+set while other panels fetch snapshots — roughly 18 MB per load at 10k, with the same data
+serialized twice.
+
+### F4 — `/api/stats` computes in JS what SQL should aggregate
+
+53.8 ms for a 0.3 KB response at 10k; the handler loops all memories for `typeCounts`,
+`confirmedCount`, and `linksCount`.
+
+### F5 — `/api/search` scales worse than the store
+
+339.1 ms at 10k (31.0 ms at 1k) with a fixed 22.8 KB response — the retrieval path, not the
+payload, is the cost.
+
+### F6 — the local dashboard depends on Google's font CDN
+
+`src/ui.ts:664-666` injects a render-blocking stylesheet from `fonts.googleapis.com`, and
+the CSP whitelists both Google font hosts. For a product positioned as local-first with
+zero cloud dependencies this is an external network call on every dashboard load, a privacy
+leak, and a latency source outside our control: in this environment the request never
+resolves, which produced a spurious multi-second load stall in early runs.
+
+### F7 — the render loop never idles
+
+`tick()` calls `requestAnimationFrame(tick)` unconditionally, so the dashboard keeps
+requesting frames forever even with the graph tab idle and `simAlpha` fully decayed.
+
+## Verdict on the plan's hypotheses
+
+| # | Hypothesis | Verdict | Evidence |
+| --- | --- | --- | --- |
+| 1 | Provider index re-read per request | **Refuted for the graph view** | The graph's data source is `/api/memories` → SQLite list + L0 cache, 0.8–6.5 ms warm. `loadGraphSymbolIndex()` lives on the retrieval path, not the dashboard path. |
+| 2 | Client re-fetches everything and fully re-renders per poll | **Half confirmed** | No polling exists (`setInterval` appears twice in `src/`, both in `cli/upgrade.ts`); but every load does re-fetch the full set and rebuild the entire graph — 11,614 DOM nodes at 1k. |
+| 3 | Layout/edges computed on the server per request | **Refuted** | No `/api/graph` route exists; layout is client-side (`initGraph` + `simulateStep`). |
+| 4 | No virtualization; DOM grows linearly | **Confirmed** | 1,714 → 11,614 → 110,614 nodes, exactly linear at ~11 per memory. |
+
+## Acceptance targets vs baseline
+
+| Target | Baseline | Status |
+| --- | --- | --- |
+| First graph paint ≤ 150 ms @1k | 268 ms | 1.8× over |
+| Incremental update ≤ 50 ms | not measurable — no revision/delta API | blocked on step 2–3 |
+| Steady-state ≥ 55 fps pan/zoom @2k | 0 fps — loop dead at ≥1k | fails harder than the target |
+| No full re-fetch when revision unchanged | not measurable — no `/api/graph` route | blocked on step 2 |
+
+## Fix order, with the baseline as the gate
+
+1. **F1 first** — clamp `scale` to a positive minimum in `project()` (and guard `radius`)
+   so a node behind the camera can never throw. This is a correctness fix, not a perf fix:
+   without it nothing else is observable at scale. Test: deterministic seed that pushes a
+   node past the camera plane, asserting `drawGraph` does not throw and the loop survives.
+2. **F2** — replace per-frame O(n²) with a decaying Barnes–Hut or grid-bucketed repulsion,
+   or run the layout once to convergence off the render path and stop. Gate on the 1.69 s
+   long task disappearing at 10k.
+3. **F3/F4** — one graph payload route returning only the fields the canvas needs (id,
+   title, type, status, project, updated_at, degree, links), a SQL `GROUP BY` for stats,
+   and an ETag/revision short-circuit. This is also where the `≤50 ms` and
+   `no full re-fetch` targets become measurable.
+4. **F7 + item 4 of the plan** — stop the loop when idle and when the tab is hidden;
+   add node caps above a threshold, and stop emitting a DOM row per memory (11 nodes each).
+5. **F6** — self-host the two font families (the website already ships self-hosted Inter and
+   IBM Plex Mono) or fall back to a system stack; drop both hosts from the CSP.

package/.agents/artifacts/brief-dayos-inspired-site-redo.md

@@ -0,0 +1,89 @@
+# Brief — Muse Memory site redo (Dayos-inspired) + copy-mode landing pass
+
+**Status**: ready to execute (analysis complete, not yet built)
+**Reference**: https://www.dayos.com/ (fetched 2026-10-01)
+**Skills to load**: `content` (`references/copy.md`, copy mode) · `animate` (motion discipline) · `webdev` (frontend mode)
+**Non-negotiables**: all claims verifiable (sub-2ms FTS5, <50µs L0, 80+ platforms, 24+ migrator formats, 69 MCP tools/6 profiles, 527 tests/88 files, 0 daemons, 45+ credential shapes, MIT); WCAG 2.2 AA; one primary action (`npx musememory connect`).
+
+---
+
+## 1. What the reference actually does (observed structure)
+
+| # | Device | How Dayos uses it | Muse adaptation |
+|---|---|---|---|
+| 1 | **Oversized stacked display headline** | "Born From / The AI era. / Not Bolted / Onto It." — three-line statement, huge, tight tracking, asymmetric break | "Your agent / forgets. / Muse / doesn't." |
+| 2 | **Marquee statement band** | "WE'RE REVOLUTIONIZING THE WAY GOOD WORK GETS DONE." repeated across the band | "MEMORY THAT VERIFIES ITSELF · LOCAL-FIRST · ZERO DAEMONS ·" scrolling band |
+| 3 | **Numbered triptych** | `AI. / GAP. / CLOSED.` — big label + 1–2 sentence body each | `CAPTURE. / VERIFY. / RECALL.` (the real pipeline) |
+| 4 | **Negation ladder** | "You don't need to replace your ERP. / …vendor AI… / …another consulting firm… / You need AI that operates across all of them" | "You don't need another vector store. / You don't need an embedding API key. / You don't need a cloud round-trip at query time. / You need memory that verifies itself before it is stored." |
+| 5 | **INTRODUCING X block** | Eyebrow in caps + two substantive paragraphs (mechanism + compounding benefit) | "INTRODUCING MUSE MEMORY" + mechanism (FTS5 + 11-dim ranking + write-time gate) + compounding (lifecycle, forgetting, distillation) |
+| 6 | **Named capability trio** | Answers / Actions / Experts — three one-line-defined blocks | Retrieve / Verify / Govern |
+| 7 | **Card + "More details →" grid** | repeated across use cases and departments | capabilities grid (per pillar) + "Read the docs →" per card |
+| 8 | **Logo strip (marquee)** | Oracle, SAP, Workday, ServiceNow, Coupa, Jira, Anaplan, Slack | Claude Code, Cursor, Codex, Windsurf, Gemini CLI, OpenCode, Hermes, OpenClaw, Zed, Aider + "+70 more" |
+| 9 | **Stat/proof band** | 70% / 30% / 2 weeks — concrete numbers inline | sub-2ms · <50µs · 0 daemons · 527 tests |
+| 10 | **4-column footer** | Platform / Solutions / Resources / Company + contact + address + socials + legal | Product / Capabilities / Docs / Project + contact + MIT licence + GitHub/npm |
+| 11 | **"Back to top"** + repeated CTA at page end | | keep |
+
+**Voice notes**: short declaratives, second person, zero hype adjectives, concrete numbers, statement-caps section headers reused as marquees. Copy devices worth stealing structurally (not verbatim): the negation ladder and the numbered triptych.
+
+**Token ideas to adopt**: high-contrast dark canvas, one accent pair, oversized display type with tight tracking, uppercase micro-labels with wide tracking, hairline rules between major bands, generous vertical rhythm, marquee bands as section dividers.
+
+---
+
+## 2. Target page architecture (single landing page)
+
+1. **Nav** — brand, 4 links, single CTA (`Install in one command`).
+2. **Hero** — stacked 3-line statement + one-paragraph mechanism line + terminal chip (`npx musememory connect`) + dual CTA. *Copy mode: AIDA attention + interest.*
+3. **Marquee band** — "MEMORY THAT VERIFIES ITSELF · LOCAL-FIRST · ZERO DAEMONS · MCP-NATIVE".
+4. **Triptych** — CAPTURE / VERIFY / RECALL, each with one real detail (Vibeguard scan; live-filesystem citation check; sub-2ms fused recall).
+5. **Negation ladder** — the four "You don't need…" lines + the pivot line. *Strongest new copy block; keep it literal and true.*
+6. **INTRODUCING MUSE MEMORY** — mechanism paragraph + compounding paragraph (76→0 lifecycle, archival ladder with rehydration, distiller).
+7. **Proof band** — sub-2ms · <50µs · 0 daemons · 527 tests/88 files · 24+ formats · 69 tools.
+8. **Capability trio** — Retrieve / Verify / Govern.
+9. **Capability cards + links** — the six pillars as cards with "Read the docs →" (pairs with existing editorial band treatment; choose one, don't mix).
+10. **Live pipeline** — the existing 4-step flow (capture → verify → consolidate → recall).
+11. **Platform marquee** — 8 named + "+70 more".
+12. **Showreel** — existing HyperFrames composition (keep; caption already accurate).
+13. **Comparison** — existing 10-row table (keep; methodology note stays).
+14. **FAQ** — existing answer-first FAQ + JSON-LD (keep; add 2 keyword-bearing questions).
+15. **Final CTA**.
+16. **Footer** — 4 link columns + licence + contact.
+
+---
+
+## 3. Copy-mode requirements per section
+
+- Formula: hero = **AIDA**; negation ladder = **PAS** agitation turned into positioning; FAQ = answer-first AEO (18-token standalone sentences); CTA = First-Person/RAD with friction-killers ("no API key, no account, MIT").
+- SEO/AEO targets: `agent memory`, `AI agent memory`, `persistent memory for AI coding agents`, `MCP memory server`, `local-first memory`, `self-verifying memory`, `Claude Code memory`, `Cursor memory`.
+- Keep **one** primary action; secondary links only to docs/GitHub.
+- Banned: seamless, robust, cutting-edge, elevate, empower, revolutionary, unlock, supercharge. No exclamation marks.
+- Every number on the page must trace to a repo fact; the 11-defect table in `session-report-2026-10-01-memory-gaps-and-website.md` lists the traps already hit (stale stats, unsupported metrics).
+
+---
+
+## 4. Assets & mockups to produce
+
+- `public/brand/og.png` (1200×630) — refresh to the new hero statement.
+- Hero device mockup: terminal window (already a real component style) + optional CLI screenshot rendered from the built site.
+- Marquee strips: text-based (CSS), no image assets needed.
+- Platform logo strip: text wordmarks (no third-party logos — avoid trademark issues; wordmarks in mono type).
+- Icon set: 6 small inline SVGs for the capability cards (stroke, 1.5px, currentColor) — no icon dependency.
+- Showreel: existing `public/showreel.mp4` (1280×720 h264 10s) — optionally a 9:16 vertical cut.
+
+---
+
+## 5. Execution checklist (next session)
+
+1. Load `content` copy mode; write all section copy to the brief's structure **before** touching layout.
+2. Rebuild `index.astro` to the architecture above; move shared chrome to `global.css`; keep tokens; adapt the editorial band CSS already in place (do not keep both band and card treatments for the same content).
+3. Implement marquee + triptych + negation ladder with the existing one-IntersectionObserver motion runtime (`src/scripts/motion.ts`) — no new JS deps; respect `prefers-reduced-motion`.
+4. Regenerate brand assets; update OG/Twitter meta + JSON-LD (FAQPage + SoftwareApplication).
+5. Gates: `bun run site:build` · `bun scripts/audit-a11y.ts` · `bun scripts/audit-visual.ts` (both must stay green — the visual audit now also verifies natural reveals) · `bun test` · `bun run typecheck`.
+6. If the showreel composition changes, `bun run site:showreel` and commit the refreshed video + `.showreel-hash` (CI fails the deploy on drift).
+7. Update `.agents/context/current.md` capability 38/39 and commit with Why/What/Verification.
+
+## 6. Known constraints carried forward
+
+- HyperFrames **skill bundle stays uninstalled** (safe-skills hard-blocked twice); the CLI devDependency is used for renders.
+- The audit servers resolve directory routes GitHub-Pages style; keep that when touching them.
+- Do not animate framework-owned `.clip` elements in the showreel composition.
+- `.reveal` opacity is owned by `global.css`; the runtime lives in `src/scripts/motion.ts` (raw JS only, injected by `Base.astro`).

package/.agents/artifacts/handoff-20261015-143202.md

@@ -0,0 +1,109 @@
+# Agent Handoff Packet — 2026-10-15T14:32:02Z
+
+> **Triage Path**: **Bounded** (targeted engine hardening on `dev`; strictly scoped migrations & gate checks; no architectural overhaul).  
+> **Council Governor**: **Sol (Product Architect & Full-Stack Automator)**  
+> **Target Branch**: `dev` @ `ee7c40f`  
+> **Worktree Lease**: Shared checkout `musememory`; acquire/check `.agents/artifacts/WORKTREE-LEASE.md` before git mutations.
+
+---
+
+## 1. Assumptions & Evidence Base
+
+- **A1 [Verified]**: `dev` is currently clean at commit `ee7c40f` with 649/649 tests passing, `tsc --noEmit` clean, and `bun run build` succeeding.
+- **A2 [Verified]**: `src/migrate.ts` provides the canonical additive migration framework (`PRAGMA user_version`), currently at schema version 2 (`T-030` tombstones). Version 3 is reserved for the outbox table.
+- **A3 [Verified]**: Reusing stale `feat/*` spec branches (`feat/multi-writer-merge`, `feat/poisoning-trust-tiers`) as git bases was explicitly ruled out due to ~8k lines of drift; they serve as read-only design references.
+- **A4 [Verified]**: Zero external daemons invariant remains strictly enforced: outbox queue and admission gates run completely in-process within SQLite (`memory.db`) transactions.
+
+---
+
+## 2. Six-Area Specification
+
+### A. Objective
+Implement the persistent write outbox state machine (`T-041`) and write admission/corroboration gates (`T-104`/`T-105`) to prevent unverified junk writes and provide resilient queued persistence.
+
+### B. Commands
+```bash
+# Verify baseline
+bun test < /dev/null
+bunx tsc --noEmit
+bun run build
+
+# Targeted test suites for new functionality
+bun test test/outbox.test.ts
+bun test test/write_gates.test.ts
+```
+
+### C. Structure (Target Scope)
+- `src/migrate.ts` — Add migration version 3 (`outbox` table with status enum, payload JSON, timestamps, retry counts).
+- `src/store.ts` — Implement outbox enqueue, dequeue/transition handlers (`pending` → `processing` → `sent` / `held` / `failed`), and write-time `scoreRetain` gate (refusing entries with salience/score < 0.3).
+- `src/promotion.ts` — Implement corroboration gate requiring ≥2 distinct observation dates and excluding machine-generated sources before candidate promotion.
+- `src/types.ts` — Export `OutboxRecord`, `OutboxStatus`, and gate outcome types.
+- `test/outbox.test.ts` — Unit tests for outbox lifecycle, crash recovery, and state transitions.
+- `test/write_gates.test.ts` — Unit tests for `scoreRetain` < 0.3 refusal and multi-day promotion gating.
+
+### D. Style & Engineering Invariants
+- Fail fast on secret detection or schema violations.
+- Single-transaction writes for all SQLite mutations.
+- Strict additive migrations only (`ALTER TABLE ... ADD COLUMN` or `CREATE TABLE IF NOT EXISTS`).
+- Zero background daemon requirement: processing operates synchronously or via opportunistic in-process event drains.
+
+### E. Testing Strategy (RED-First)
+1. Write failing tests in `test/outbox.test.ts` verifying outbox creation and state transitions.
+2. Write failing tests in `test/write_gates.test.ts` verifying refusal of entries with retain score < 0.3 and refusal of promotion without 2 independent days of corroboration.
+3. Implement `v3` schema migration in `src/migrate.ts`.
+4. Implement store integration in `src/store.ts` and `src/promotion.ts` until all tests turn green.
+
+### F. Three-Tier Boundaries (Hard Constraints)
+- `[MUST NOT]`: Do not introduce background HTTP/WebSocket listening servers or persistent daemon processes.
+- `[MUST NOT]`: Do not modify existing `memories` table columns destructively; all schema changes must be additive via `src/migrate.ts`.
+- `[MUST NOT]`: Do not bypass Vibeguard credential scanning on any outbox payload.
+- `[MUST NOT]`: Do not re-base onto or merge directly from stale `feat/*` branches.
+
+---
+
+## 3. Interfaces (Consumes & Produces)
+
+- `src/migrate.ts`:
+  - Consumes: `SqliteDatabase` connection.
+  - Produces: Migration version 3 creating table `outbox (id TEXT PRIMARY KEY, memory_id TEXT, status TEXT, payload TEXT, attempts INTEGER, last_error TEXT, created_at TEXT, updated_at TEXT)`.
+- `src/store.ts`:
+  - Consumes: `MemoryEntry` propose requests, retain score evaluator.
+  - Produces: Rejection if `scoreRetain < 0.3`; outbox persistence record; single-transaction memory commit.
+- `src/promotion.ts`:
+  - Consumes: `candidate` memory ID, provenance history, observation timestamps.
+  - Produces: Promotion decision (`confirmed` vs rejected/held) enforcing ≥2 calendar days of human/non-synthetic corroboration.
+- `test/outbox.test.ts` & `test/write_gates.test.ts`:
+  - Consumes: In-memory/temp SQLite stores.
+  - Produces: Deterministic pass/fail assertions.
+
+---
+
+## 4. Ruled-Out Paths (Do Not Re-Attempt)
+
+1. **Reusing Stale `feat/*` Spec Branches**: Attempting to merge or rebase `feat/multi-writer-merge` or `feat/poisoning-trust-tiers` causes ~8k lines of merge conflicts. Use fresh branches off `dev`.
+2. **Exact-Match Flag Denylists**: In command parsing, exact flag denylists failed against `--flag=value` variations; use structural dash rejection.
+3. **Daemon-Centric Background Flushing**: Requiring a running background daemon violates the foundational Zero External Daemons invariant (ADR-001).
+
+---
+
+## 5. Decisions Made (Locked)
+
+- **One Branch Per Ticket**: Clean feature branches squashed to `dev` with passing gates.
+- **Single-Transaction SQLite Writes**: Protect store consistency against concurrent process crashes.
+- **Additive Migrations Only**: `PRAGMA user_version` tracking with forward migrations in `src/migrate.ts`.
+
+---
+
+## 6. Success Criteria
+
+- [ ] `test/outbox.test.ts` passes with full lifecycle coverage (`pending` → `processing` → `sent` / `held` / `failed`).
+- [ ] `test/write_gates.test.ts` passes: `scoreRetain < 0.3` is rejected; promotion requires ≥2 independent days of non-machine evidence.
+- [ ] `bun test < /dev/null` passes with 649+ green tests.
+- [ ] `bunx tsc --noEmit` exits with 0 errors.
+- [ ] `bun run build` generates clean bundle in `dist/`.
+
+---
+
+## 7. If Blocked
+
+If SQLite transaction contention or table locking occurs during migration v3 execution, verify `PRAGMA busy_timeout = 5000` is active and ensure connections are not held open across async yields. Document anomalies in `.agents/artifacts/dead-letter-<timestamp>.md` and escalate to the Principal.

package/.agents/artifacts/plan-competitor-adaptation-dashboard-graph.md

@@ -0,0 +1,99 @@
+# Plan — competitor adaptation, dashboard refactor, instant graph
+
+**Status**: planned, not started. Reconnaissance done (file/line facts below are verified).
+**Scope**: three workstreams. Run them in order — A informs C, and B is independent.
+
+---
+
+## Reconnaissance (verified this session)
+
+| Fact | Evidence |
+|---|---|
+| Graph engine is small and provider-backed | `src/graph.ts` ≈ 322 lines; `detectProvider` → `codegraph` \| `graphify` \| `none`; `indexGraph()` walks provider dirs, `loadGraphSymbolIndex()` reads `.memory/graph-symbols.json` |
+| Symbol index is a flat JSON cache, file-read per call | `graph.ts:108–218` — `JSON.parse(readFileSync(...))` in loops over candidates → files → symbols |
+| Graph intelligence adapters exist | `src/intelligence/adapters/{codegraph,graphify}.ts` |
+| Vector path is thin | `src/vector.ts` = 182 lines |
+| **Dashboard is a monolith** | `src/ui.ts` = **2,475 lines**, serving inline HTML/CSS/JS, CSP `'unsafe-inline'`; `startUiServer()`; `/api/export-html` produces a standalone graph HTML |
+| Tests that constrain refactors | `test/graph.test.ts`, `test/graph_ast.test.ts`, `test/ui.test.ts`, `test/optimize.test.ts`, `test/governor.test.ts` |
+| UI server contract | `startUiServer({ port?, memoryDir, store })` → `{ port, close }` (`src/ui.ts:31–37`); node `createServer`, CSP `'unsafe-inline'` |
+| **No `/api/graph` route exists** | 30+ routes enumerated (`/api/memories`, `/api/stats`, `/api/snapshot`, `/api/search`, `/api/wiki`, `/api/cognition/*`, `/api/mesh/*`, `/api/uplink`, …). The graph is therefore rendered client-side from `/api/snapshot` and/or `/api/memories` — **that is the poll/re-render path to instrument** |
+
+### C-recon (verified 2026-10-01, second pass)
+
+1. Candidate endpoints to time first: `/api/snapshot`, `/api/memories`, `/api/stats`, `/api/search` (POST). Graph payload has no dedicated route.
+2. Harness should bootstrap the real server in-process: `startUiServer({ port, memoryDir, store })` on a throwaway port, then drive `fetch` for server-side timings and Playwright for client-side metrics — no source edits, so nothing has to be reverted.
+3. Client metrics to capture generically (no component internals needed): document load, DOM node count, canvas/SVG node count, long tasks via `PerformanceObserver`, and rAF frame deltas while dispatching pointer/wheel events at the graph.
+4. Run the harness against three store sizes (100 / 1k / 10k memories) to get the scaling curve — the shape of that curve is what will confirm or kill the “re-fetch + full re-render” hypothesis.
+
+**Latency hypotheses to verify before changing anything** (do not assume):
+1. Provider index re-read per request instead of a memoized, mtime-invalidated index.
+2. Client graph view likely re-fetches the whole memory set per poll and re-renders the full SVG/graph (no diffing, no ETag/version short-circuit).
+3. Layout/edge computation possibly done on the server per request.
+4. No virtualization for large graphs; DOM node count grows linearly with memories.
+
+---
+
+## Workstream A — competitor mechanism deep-dive (adaptation shortlist)
+
+**Method**: `deep-research` skill, depth *wide*. Study mechanisms from **primary sources in the repos**, not blog summaries. For each candidate, require: (a) the exact mechanism, (b) its measured cost claim and how it was measured, (c) what Muse already has (we shipped write-time citation verification, the recall freshness gate, and the hook pack — do not re-propose those), (d) a concrete adaptation with an acceptance test.
+
+**Targets to study** (carry-over from the 86-system study plus new angles):
+- deja-vu — 0.7–0.8 ms lookup path (what indexing makes it possible)
+- Kage — write-time citation verification (already shipped; study the *rest* of its model)
+- Memvid — single-file memory container and its I/O pattern
+- OpenViking — L0/L1/L2 tiering (compare with the existing L0 cache + archival ladder)
+- agentmemory — 12 lifecycle hooks (we shipped 3; what are the other 9?)
+- hindsight — observations vs mental models (does Muse's distiller produce equivalent abstractions?)
+- Wax — 6.1 ms p95 under load; what its load profile reveals
+- Vestige — signed-log exact-handle retrieval
+- **New angles worth a look**: incremental code-index maintenance (tie into Workstream C), hybrid lexical+dense retrieval ranking, MCP resource *subscriptions* (push vs poll), time-decay + negative-memory scoring, and graph-native recall (edges as a retrieval signal rather than a visualization only).
+
+**Deliverable**: `.agents/context/deep-research-memory-adaptation-2026-10.md` — scored gap table (impact × effort), top-3 ranked adaptations, each with acceptance criteria and the tests it must extend. No implementation in this workstream.
+
+---
+
+## Workstream B — dashboard refactor (designscope) with polished, mobile-first UI
+
+**Problem**: `src/ui.ts` is a 2,475-line monolith with inline everything; not structured for responsive design, tokens, or states.
+
+**Approach** (`designscope` for the system, `webdev` frontend mode to implement):
+1. **Extract** the current dashboard's implicit design system (palette, spacing, type scale, component inventory) and reconcile with `.agents/brand/design.md` + tokens under `.agents/brand/tokens` — one token source, no parallel literals.
+2. **Split** `ui.ts` into: server/routes (thin), static assets (`ui/` HTML, CSS, JS), and view templates — keeping the existing behaviours (`/api/*`, `/api/export-html`, harvest actions) byte-compatible in contract; add contract tests before moving code.
+3. **Rebuild the layout mobile-first**: fluid type, container queries, logical properties, safe-area insets; graph + tables + filters usable at 375 px (drawer for filters, non-scrolling data tables, 24 px minimum targets).
+4. **States**: loading, empty, error, success for every panel; skeletons over spinners; optimistic actions with rollback.
+5. **A11y**: WCAG 2.2 AA — focus order, landmarks, labels for icon-only controls, `prefers-reduced-motion` respected.
+6. **Gate**: add `scripts/audit-dashboard.ts` mirroring `apps/website/scripts/audit-visual.ts` (375/768/1280, overflow, tap targets, console errors, plus axe on the dashboard routes) and keep it green.
+
+**Acceptance**: no behaviour regressions (all `test/ui.test.ts` cases pass), dashboard usable and non-overflowing at 375 px, audit script green, no new runtime dependency.
+
+---
+
+## Workstream C — make the graph instant
+
+**Measure first** (budget: one session of profiling, no code changes):
+1. Instrument `/api/*` graph routes with timing (server-side) and add a client-side long-task/`performance.mark` capture.
+2. Record baselines: index load, payload bytes, JSON parse time, render time, frame time during pan/zoom, at 100 / 1k / 10k memories.
+3. Confirm or discard the hypotheses above with numbers.
+
+**Then fix, in this order** (each guarded by a test):
+1. **Memoized, mtime-invalidated index** — load `.memory/graph-symbols.json` once per process keyed by mtime+size; invalidate on `indexGraph` write. (Hypothesis 1.)
+2. **Version/ETag short-circuit** — a store revision counter; `/api/graph` returns `304`-equivalent empty payload when unchanged. (Hypothesis 2.)
+3. **Incremental payloads** — send deltas (add/remove/update) after the initial snapshot instead of the full set per poll.
+4. **Client-side layout + render diffing** — compute layout in the browser, reuse nodes across frames, batch DOM writes; no layout thrash (read/write separation).
+5. **Budget guards** — cap rendered nodes above a threshold (aggregate clusters), virtualize lists.
+
+**Acceptance criteria** (target, to be confirmed against the measured baseline):
+- First graph paint ≤ 150 ms at 1k memories; incremental update ≤ 50 ms.
+- Steady-state pan/zoom ≥ 55 fps with 2k nodes (Chrome, mid-tier laptop).
+- No full re-fetch when the store revision is unchanged.
+- Regression tests: `test/graph.test.ts` + `test/graph_ast.test.ts` extended with a latency/`no-full-refetch` assertion.
+
+---
+
+## Sequencing & handoff notes
+
+1. **A** (research, no code) — 1 session.
+2. **C** (profile → fix) — 1–2 sessions; A's findings on incremental indexing feed step C2/C3.
+3. **B** (designscope refactor) — 1–2 sessions; independent, can run in parallel if a second agent is available (use `dispatching-parallel-agents`, but note `src/ui.ts` and `src/graph.ts` are the shared-file collision risk — hold the worktree lease).
+
+Carried-forward constraints from this session: engine gate is `bun test` (527 pass / 88 files) + `tsc --noEmit`; HyperFrames skill bundle stays uninstalled (CLI only); audit servers resolve directory routes GitHub-Pages style; `.reveal` opacity is owned by `global.css` with the runtime in `src/scripts/motion.ts`.

package/.agents/artifacts/session-report-2026-10-01-memory-gaps-and-website.md

@@ -0,0 +1,94 @@
+# Session Report — Muse Memory: Agent-Memory Gaps, Website & Showreel
+
+**Date**: 2026-10-01 · **Repo**: `harshsinghmp/musememory` · **Branch**: `main`
+**Scope**: deep research → gap-driven engine features → professional website → motion-designed showreel
+
+---
+
+## 1. Objective
+
+Close the highest-value gaps between Muse Memory and the state of the art in agent memory (from a first-party study of 86 systems), then present the product through a professional, accessible, SEO/AEO-optimized website with a designed showreel — all independently verified.
+
+---
+
+## 2. Research foundation
+
+- **`deep-research-memory-mechanisms-2026-09.md`** — 86-system comparison; deep dives into deja-vu (0.7–0.8 ms lookup), Wax (6.1 ms p95), Vestige, Kage (write-time citation verification, 0% stale-served), agentmemory (12 lifecycle hooks), hindsight, Memvid, OpenViking, gbrain, engram, claude-mem.
+- **Gap analysis (§14) scorecard** — Muse: speed 15/16, observability 8/8, **hands-free 4/10**, **trust 7/10**. Three gaps chosen for implementation: GAP-1 (write-time verification), GAP-2 (lifecycle hooks), GAP-3 (recall freshness gate).
+
+## 3. Engine features shipped (GAP-1/2/3)
+
+| Feature | Module | Behaviour |
+|---|---|---|
+| Write-time citation verification | `src/anchors/verify-write.ts` | Every code anchor is checked against the live filesystem before a write is admitted; hallucinated citations are rejected under the default `fail_fast` policy; decisions audited with existing ops |
+| Recall-time freshness gate | `src/orchestrator/freshness.ts` | Drifted/orphaned-anchor memories are **withheld from `muse_context` by default** and reported via `withheld_memories` + `freshness_notice`; `include_drifted: true` opts in with provenance warnings; memoized per `(path, symbol, mtime)` |
+| Claude Code lifecycle hook pack | `src/hooks/pack.ts` | `SessionStart` injects constraints + top memories before the first turn; `PostToolUse` captures Vibeguard-scanned observations; `Stop` distills candidates. Idempotent install, preserves user hooks, every handler fail-open |
+| Surface wiring | `src/cli*`, `src/mcp.ts` | `memory hooks install/uninstall/…`, `connect --with-hooks`, `include_drifted` on `muse_context` |
+
+**Tests**: `test/verify-write.test.ts` (9), `test/freshness.test.ts` (6), `test/hooks.test.ts` (10) → **527 tests / 88 files, fully offline**.
+
+## 4. Website (Astro 7 · static · GitHub Pages `/musememory`)
+
+Four pages — home, docs, compare, 404 — with brand assets (banner 1280×640, OG 1200×630, Twitter card), zero-JS-dependency motion runtime, and a hash-gated CI pipeline.
+
+**Copy pass (content/copy mode)**: named reader (developer evaluating agent memory), one action (`npx musememory connect`), AIDA→AIDCA structure, FAQ written as 18-token standalone quotables, **FAQPage + SoftwareApplication JSON-LD** for AEO, anti-puffery scrub. All claims traceable: sub-2ms FTS5 recall, <50µs L0 cache, 80+ platforms, 24+ migrator formats, 69 MCP tools/6 profiles, 527 tests, 0 daemons, 45+ credential shapes.
+
+**Layout (this pass)**: capabilities rebuilt as **editorial bands** — oversized numbered indices, hairline rules, alternating asymmetric columns, responsive collapse; section copy tuned to search intent ("AI agent memory", "persistent memory for AI coding agents", MCP, local-first).
+
+## 5. Defects found and fixed
+
+| # | Defect | Impact | Fix |
+|---|---|---|---|
+| 1 | Stale stats on site (498 tests / 86 files, "0% stale-served") | Unverifiable claims | Corrected to 527/88; unsupported stat removed |
+| 2 | `BASE_URL` cross-page links missing slash (`/musememorydocs`) | Broken nav on the deploy | 10 links + 3 anchors base-corrected |
+| 3 | Duplicated OG/Twitter meta block | Invalid head markup | Deduped |
+| 4 | 404 page hardcoded `/` + `/musememory/docs` | Broken links under base path | Base-aware |
+| 5 | Compare page had no `h1` | Heading hierarchy | Promoted |
+| 6 | **Motion runtime silently dead** — `initMotion()` returned `<style>+<script>` markup injected *inside* the layout's `<script>` | **Whole sections rendered invisible** (`.reveal{opacity:0}` with no runtime) | `initMotion()` returns raw JS only; reveal CSS lives in `global.css` |
+| 7 | Audit harness served 404.html for `/docs` and `/compare` | Earlier a11y runs measured the wrong page (phantom passes) | Servers resolve directory routes GitHub-Pages style |
+| 8 | Prose links colour-only | WCAG 1.4.1 violation | Underlined; caught only after #7 was fixed |
+| 9 | `/docs` horizontal overflow (409px @375, 30px @768) | Mobile page scroll | `.docs-body { min-width: 0 }` |
+| 10 | Decorative orbs overflowed phones (199px) | Layout overflow | Hidden ≤640px + `html { overflow-x: clip }` |
+| 11 | Visual/a11y audits force-revealed elements before measuring | Masked defect #6 | Audit now checks **natural reveals first** (with instant-scroll sweep) |
+
+**Lesson recorded**: any audit that mutates the page before measuring can only confirm its own assumptions — reveal/motion checks must run before, not after, a freeze step.
+
+## 6. Showreel redesign
+
+**Decision**: the HyperFrames *skill bundle* was **hard-blocked twice by safe-skills** (prompt-injection ×18; then credential-file-access ×9 in `media-use`). Sources reviewed (`SKILL.md`, `prefs.mjs`) read as false-positive-prone but unreviewed at scale — so the skill bundle is **not installed**. Instead: the `hyperframes` npm CLI (devDependency) + public docs; vendor-generated agent instruction files were deleted from the scaffold.
+
+**Composition** (`apps/website/showreel-hf/index.html`, 1080p master → 1280×720 web): four scenes in 10s — hook ("Your agent forgets. / Muse doesn't."), live terminal type-on (`npx musememory connect`, 1.9ms fused recall), benchmark stat cards with count-up motion (`<50µs`, `1.9ms`, `0`), logo-sting CTA hold. Brand tokens, self-hosted Inter + IBM Plex Mono, one GSAP timeline; **every number on screen is a measured benchmark**.
+
+**Contracts learned the hard way**: never animate framework-owned `.clip` elements (visibility is framework-managed — animate inner wrappers); the occlusion inspector must be satisfied with a pseudo-element scrim rather than an opaque overlay.
+
+**Pipeline**: `bun run site:showreel` → master render → 1280×720 H.264 → poster → ffprobe assertions. CI hash-gates composition + fonts + script and **fails the deploy on drift**; a manual dispatch can rebuild in CI.
+
+## 7. Verification evidence
+
+| Gate | Result |
+|---|---|
+| Engine tests | **527 pass / 0 fail** (88 files, offline) |
+| Typecheck | `tsc --noEmit` clean |
+| Site build | 4 pages |
+| WCAG 2.2 AA audit | 24/24 token pairs, axe-core **0 issues** on 4 real pages |
+| Visual review | **9/9** viewports (375/768/1280 × 3 pages) incl. natural-reveal checks |
+| HyperFrames `check` | **0 errors**, motion clean, layout clean, **19/19 WCAG AA** |
+| Showreel render | ffprobe: 1280×720 h264, 10.00 s, 738 KB |
+
+## 8. Commits (pushed to `main`)
+
+| Commit | Summary |
+|---|---|
+| `faeaaff` | `feat(memory)`: write-time citation verification, freshness gate, hook pack |
+| `18db5f2` | `feat(website)`: site + verified copy + audit tooling |
+| `6ff1598` | `feat(website)`: HyperFrames showreel composition |
+| `0aa8500` | `feat(website)`: editorial capability bands + reveal-integrity audit check |
+
+Deploy: `d938ac2..0aa8500` pushed; GitHub Pages redeploy carries the motion-runtime fix that restored the previously invisible sections.
+
+## 9. Remaining work
+
+1. **Full SEO/AEO copy-mode pass** across hero, flow, benchmarks, trust, FAQ, comparison (capabilities section was tuned this session; the rest carry the earlier pass).
+2. **Editorial consistency**: extend the band language to the flow / benchmarks / trust / comparison sections so the page reads as one system.
+3. **Showreel variants**: 9:16 vertical cut for social.
+4. Optional: promote the browser-driven audit scripts into the PR CI gate (currently local-only gates).

package/.agents/artifacts/wave-3-sdd-ledger.md

@@ -0,0 +1,18 @@
+# SDD ledger — Wave 3: Retrieval Quality, Ranking & Token Economics
+Plan: Wave 3 In-Line Retrieval
+Branch: feat/wave-3-retrieval-ranking
+Base Commit: c2ac959
+
+## Task List
+- [x] Task 1: Scale Safety & Performance Core (T-035, T-036, T-037)
+- [x] Task 2: FTS5 Query Injection Safety & Compound Token Splitting (T-060, T-061, T-312)
+- [x] Task 3: Relevance Gating & Soft-OR Evidence Fusion (T-070, T-114)
+- [x] Task 4: Conditional Reranking, Watermark Staleness & Reason Tokens (T-115, T-117, T-126)
+- [x] Task 5: Integration, Negative Lesson Priority Knapsack & Full Gate Verification
+
+## Progress Log
+- Task 1: complete (commit d21768b, T-035 iterative safeMax, T-036 in-memory IDF caching, T-037 countMemories scan elimination; 5/5 tests pass).
+- Task 2: complete (commit 1cef9ba, T-060 safe FTS5 escaping, T-061 compound token expansion, T-312 error observability; 7/7 tests pass).
+- Task 3: complete (commit be7b70d, T-070 relevance gate, T-114 Soft-OR evidence fusion; 6/6 tests pass).
+- Task 4: complete (commit ba7041b, T-115 conditional rerank, T-117 watermark staleness, T-126 why_retrieved reason tokens; 4/4 tests pass).
+- Task 5: complete (integration test suite test/wave3_retrieval_integration.test.ts 4/4 pass, knapsack packing prioritization for negative anti-pattern lessons, full test suite 730/730 pass, tsc clean, build clean, doctor clean).

package/.agents/artifacts/wave-4-sdd-ledger.md

@@ -0,0 +1,18 @@
+# SDD ledger — Wave 4: Compaction, Ephemeral Observations & Distillation
+Plan: Wave 4 In-Line Cognition
+Branch: feat/wave-4-compaction-distillation
+Base Commit: 90a6d3f
+
+## Task List
+- [x] Task 1: Observation Hardening & Distillation Protection (T-305, T-306)
+- [x] Task 2: Compaction Checkpoint Invariants & Extraction Hooks (T-045, T-047)
+- [x] Task 3: Persisted Digest Deduplication Set (T-046)
+- [x] Task 4: Honest Dual-Measure Token Accounting & Refuse-Incomplete Digest (T-053, T-054)
+- [x] Task 5: Context-Pack Compaction, Manifest TOC & Truncation Hierarchy (T-091, T-092, T-093, T-094)
+
+## Progress Log
+- Task 1: complete (T-305 capDistillationBody prevents raw log memory bloat; T-306 atomic write and budget-based log rotation; 6/6 tests pass).
+- Task 2: complete (T-047 validateCompactionInvariants never-empty contract; T-045 on_pre_compress hook and extractInvariantsPreCompress; 7/7 tests pass).
+- Task 3: complete (T-046 persisted SHA-256 digest dedup store in .memory/digest_dedup.json preventing duplicate memory extraction on repeated runs; 4/4 tests pass).
+- Task 4: complete (T-053 dualMeasureTokens accounting with standard + pessimistic model; T-054 validateDigestIntegrity and refuse-incomplete CURRENT.md contract; 5/5 tests pass).
+- Task 5: complete (T-091 formatCompactContextPack, T-092 context_manifest never-drop TOC, T-093 Pin > Provenance > Recency > Salience truncation hierarchy with [N omitted - budget M] marker, T-094 reserved tokens for USER.md; 4/4 tests pass, full suite 756/756 pass, tsc clean, build clean, doctor clean).

package/.agents/context/architecture.md

@@ -68,6 +68,7 @@ musememory/
 │   ├── mcp.ts              # Model Context Protocol stdio server (69 tools with profiles)
 │   ├── mesh/               # Multi-repo & monorepo workspace discovery, query resolver, contracts
 │   ├── orchestrator/       # Flagship muse_context fusion, bidirectional lookups, MCP profiles
+│   ├── paths.ts            # Strict path containment (resolveWithin) & intentional-external opt-out (resolveExternal)
 │   ├── promotion/          # 3-tier promotion ladder, 5x success rule, archival lifecycle
 │   ├── quality/            # Deduplication, semantic contradiction engine, utility & ROI
 │   ├── retrieval/          # 11-dimension multi-factor scoring & token knapsack packing