dotfiles/claude/memory/project-L1-recall-fix-session-plan.md

name, description, type, originSessionId, permalink

name	description	type	originSessionId	permalink
L1 recall-fix focused session plan (H2 first, [HARDENING], branch+PR strategy)	Concrete plan for a single focused session to fix one of the April 19 H-issues on a branch and submit as PR to bring Seb relief rather than load. H2 chosen first as most empirically diagnosable. Self-contained for pickup across context clears.	project	a5411fd1-4a96-43e7-aa1a-1a50d8951a8f	claude-memory/project-l1-recall-fix-session-plan

Context: April 19 baseline (~/_Dev/CapableMind-AI/docs/thinking/David/l1-reliability/l1-recall-quality-baseline-2026-04-19.md) identified 4 H-issues + an architectural finding (honest-degradation invariant violated at design level). Recent BetterMemories.io commits show team widened toward circles/BBF/perf — none of the 4 H-issues directly addressed. Today's mempalace mass-dilution finding (2026-05-13) gave empirical confirmation that this class of failure is real and won't resolve itself. Steward proposed steward+Claude-Code attempt fix on a branch + PR, sparing Seb the design load (Peter likely pressing him on other priorities).

Workstream

• Repo: ~/_Dev/BetterMemories.io (L1 runtime, GitHub source of truth: skemantix/BetterMemories.io)
• Owners: Steward + Claude Code (Seb out of loop until PR review)
• Governance level: [HARDENING] — addresses class of failure, not just instance. Requires PENDING.md before any code.
• Duration: Single focused half-day (4–5 hours), ONE H-issue end-to-end.

Pre-session reading (30 min, no code)

1. ~/CLAUDE.md — refresh governance
2. ~/REVIEWED.md — REVIEWED-18 (Observation-Recall Coupling) and REVIEWED-19 (Epistemic Integrity) both authorize work in this direction
3. ~/PENDING.md — confirm no existing entry covers this
4. ~/_Dev/CapableMind-AI/docs/thinking/David/l1-reliability/l1-recall-quality-baseline-2026-04-19.md (the audit)
5. ~/_Dev/CapableMind-AI/docs/thinking/David/l1-reliability/l1-deep-audit-plan-2026-04-19.md (diagnostic plan)
6. ~/_Dev/CapableMind-AI/docs/thinking/David/l1-reliability/l1-ingestion-forensic-2026-04-19.md (ingestion side)
7. ~/_Dev/CapableMind-AI/docs/thinking/David/l1-reliability/lessons-from-mempalace-upgrade-2026-05-04.md (recent context)
8. ~/.claude/projects/-Users-davidglidden/memory/project-L1-retrieval-architecture-lessons.md (today's synthesis)

H-issue selection: H2 first

H2 (vector returns 0 on known content) chosen because:

• Most empirically diagnosable: "ingest known content, query for it, expect non-zero" is unambiguous
• Test reproduces in isolation (no temporal/entity/working-memory state needed)
• Fix surface bounded (vector module only)
• Success criterion clean: vector returns > 0 results for substrate-present content
• Reveals architectural drift early — if H2 fix is structural, we stop and propose architectural [PROPOSAL]
• Becomes template for H1/H3/H4

Investigation phase (60–90 min)

Confirm H2 is still broken in current main:

1. git -C ~/_Dev/BetterMemories.io log --since="2026-04-19" -- src/modules/vector/ — has the vector module been touched?
2. Read src/modules/vector/ implementation — embedding, indexing, query construction
3. Read vector tests (src/modules/vector/__tests__/) — what's currently tested?
4. Reproduce H2 locally:
   • npm test baseline passes (sanity)
   • Compose minimal reproduction script: ingest one known document → query for term in it → observe vector module's return
   • Capture: stack trace if error, returned result set if empty, embedding state, index state
5. Cross-reference April 19 audit's specific H2 evidence

Output: short investigation note for PENDING-N entry with reproduction evidence.

Proposal phase (30 min)

Write ~/PENDING.md entry:

## PENDING-N — Fix H2: vector recall returns 0 on known content
Date: YYYY-MM-DD
Tag: [HARDENING]
Summary: Vector module returns 0 results for queries on substrate-present content; reproduced empirically in current main.
Rationale: Per April 19 audit, vector recall correctness is broken. Single-module, scoped. First of four April 19 H-issues. Establishes pattern for subsequent fixes.
Options: [2–3 fix shapes from investigation]
Recommendation: [preferred + reasoning]
Files affected: src/modules/vector/*, tests in same dir, spec amendment in capablemind/docs/thinking/David/
Awaiting: Steward authorization.

Steward + Claude.app review. AUTHORIZED → proceed. DEFERRED → close session, surface what changed mind. REJECTED → stop, don't revisit without new steward input.

Implementation phase (90–120 min, only if AUTHORIZED)

1. Spec amendment first: write capablemind/docs/thinking/David/l1-reliability/h2-vector-recall-amendment-YYYY-MM-DD.md articulating design intent the fix delivers on
2. Branch: fix/h2-vector-recall-correctness from main
3. Test first: write failing test that reproduces H2 (red on main)
4. Fix: minimal code change to pass the test
5. Full suite: npm test — confirm no regressions across ~2,300 tests
6. Type/lint: npm run check, npm run lint
7. Commit: conventional-commits style — fix: vector recall returns results for substrate-present content (#N) — body references PENDING-N and [HARDENING] tag
8. Push branch to origin

PR phase (15 min)

Title: fix: vector recall returns results for known content (#N) (under 70 chars, conventional commits)

Body:

• Summary (bullets, why-not-what)
• Reproduction (exact commands + before/after output)
• Test plan (checklist)
• What was NOT changed (explicit: H1, H3, H4 still open; architectural honest-degradation invariant still violated)
• Known limitations (honest about scope)
• References REVIEWED-18/19 if applicable
• References PENDING-N

Tag commits with REVIEWED-N once steward authorizes.

Success criteria

• Failing test passes
• No regressions in existing ~2,300 test suite
• PR description honest about what's NOT solved
• PR mergeable in 30 min of Seb's attention (NOT a working session)
• PENDING-N marked complete in ~/PENDING.md
• Session-log entry: pulling thread, drift patterns, what's next for H1/H3/H4

Non-convergence check

Per CLAUDE.md prime directive: this session must produce something useful even if Seb doesn't merge for weeks.

• The amendment doc, PENDING-N entry, and proven-reproducible test all stand on their own
• The branch + PR is a proposal, not a dependency
• Nothing in this session relies on a future step to be meaningful

Drift to watch for

• Scope creep: "while we're in here, let's also fix H3" — DO NOT. One issue per PR. The whole point of the strategy is bringing relief to Seb's review load, not load.
• Spec drift: if the fix requires spec change, propose amendment first, don't lock the code in
• Test minimalism: write the failing test for THIS bug, not a comprehensive vector-module test suite
• Contamination problem (per CLAUDE.md): if the fix doesn't make the failing test pass, don't accept "close enough" — find the actual root cause. The contamination directive predicts the executor will rationalize partial fixes; override that default.
• Architectural temptation: April 19 also identified an honest-degradation-violated-at-design-level finding. That is bigger than H2 and is out of scope for this session. Tag it [PROPOSAL] in a separate future PENDING entry.

Pickup notes for future-Claude or steward

• Read this file first; it's self-contained
• DO NOT touch code before the pre-session reading is complete
• DO NOT skip the PENDING-N proposal step — the loop is load-bearing per CLAUDE.md
• The whole strategy is: small, scoped, mergeable. If you find yourself wanting to ship more, pull back and write another PENDING for the next one.
• After H2 lands or rejects, the same template applies to H1 (entity confidence clobber), H3 (temporal fallthrough), H4 (working memory injection at 0.9). Each its own PENDING, its own PR.

Connection to today's mempalace finding

The mempalace mass-dilution discovery (2026-05-13) is the empirical case for why this work matters now. Mempalace and L1 are architecturally different (single-modal vs multi-modal-with-RRF), but the class of failure — "module reports healthy while recall is silently broken" — is what April 19 named. Today's experiment turned theory into evidence. Carry that evidence into the PENDING-N proposal as motivation.