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

---
name: L1 recall-fix focused session plan (H2 first, [HARDENING], branch+PR strategy)
description: 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.
type: project
originSessionId: a5411fd1-4a96-43e7-aa1a-1a50d8951a8f
permalink: 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.