memshelf — Roadmap

Milestones are deliberately thin. M0 validates the pattern with zero new code; every later milestone must justify itself against what M0 already achieves.

M0 — Pattern validation, no code — complete (2026-07-13 → 2026-07-22)

Epic: #164 (closed).

Exit criteria met: recall test 5/5, ledger + recall-cost numbers written down (demo.md), and the annoyance log became the M1 backlog verbatim. Case B closed 2026-07-22 (33 episodes, zero loss; verdict episode on the shelf).

Prove the loop works with docshelf as-is plus conventions. Protocol, kit, and measurement methodology: docs/M0.md; the prompt-only skill and recall-rule snippet live in adapters/claude-code/.

Exit criteria: 5 known-answer recall questions answered correctly from a fresh session via INDEX navigation; ledger numbers written down; the annoyance log filled. That log is the M1 backlog.

M1 — memshelf-mcp thin server — complete (closed 2026-09-27)

Epic: #165 (closed). Closed by the owner on 2026-09-27: every scope item shipped (0.1.0, 2026-07-25, plugin with it), and the exit clause holds on the record. In the 14 days to 2026-09-27 all 37 derived-layer renders on main-memshelf were made by the shelf bot and none by hand, doctor on its main is clean, and five project shelves ran shelve → doctor → rebuild on 2026-09-26. The one manual fix in CHANGELOG 0.2.0 (#56, 2026-07-27) predates that window.

Only what M0 proved annoying, expected:

Exit criteria: dogfooded on two real projects for two weeks; a full shelve→compact→recall cycle survives without manual repair; doctor clean.

M2 — Policy, hygiene & the context advisor

Epic: #166 — the current period since 2026-09-27.

Exit criteria: a shelf with 100+ episodes keeps INDEX within its budget — INDEX_BASE_TOKENS + INDEX_TOKENS_PER_ENTRY × listed episodes, i.e. the price of a line stays flat as the shelf grows — and recall precision doesn’t degrade (re-run the M0 question set); the advisor’s shelve proposals are accepted (not overridden) most of the time in dogfood use.

Revised 2026-08-21. This used to read “100+ episodes and INDEX under ~10 KB”, and the two clauses contradicted each other. INDEX lists episodes, so its size is O(episodes) by construction; a fixed ceiling is therefore unreachable past some shelf size, and the only mechanism that lowers the number afterwards is rollup — which buys compliance by archiving live memory. Measured on the author’s 113-episode shelf: the structural floor, with every description deleted and the link de-duplicated, is ~3800 tokens (~15 KB), so “100+ episodes under 10 KB” was not merely tight but arithmetically impossible. The derived constant INDEX_BUDGET_TOKENS = 2500 inherited the contradiction and added a unit error — “~10 KB at chars/4” holds only if one character is one byte, and this shelf’s Cyrillic runs ~1.42 bytes per character, making the two clauses two different budgets (10 KB ≈ 1800 tokens; 2500 tokens ≈ 14 KB). The budget is now linear in shelf size, which puts the check on the quantity formatting can actually control. Rollups stay in M2, triggered by INDEX’s share of the context window (INDEX_CONTEXT_SHARE) rather than by a threshold that growth alone would breach.

M3 — Retrieval upgrades, reuse layer & second surface

Epic: #167.

Exit criteria: search-miss rate measurably better than grep baseline on the dogfood shelves (met, #17: 30 hand-written queries on the dogfood shelf — 10 Russian paraphrases, 10 English queries against Russian episodes, 10 short keyword queries — grep misses 29/30, the hybrid 14/30 at k=5 and 9/30 at k=10; MRR 0.03 → 0.43; no query where the hybrid lost a grep hit); one non-author user runs the chat-project flow from docs alone; one real “fork from episode” session succeeds end-to-end (met, #18).

Explicitly deferred