abcd Surfaces the Right Memory at the Right Moment

Press Release

abcd ships scope-aware memory retrieval so the project's accumulated knowledge reaches you exactly when it's relevant — and never floods your context when it isn't. Memory pages carry recall keywords. The same UserPromptSubmit hook that injects modular rules (itd-3) also scans each prompt against memory pages across two scopes — the workspace and the user's personal store — and injects only the matching pages. Injection is budget-aware: with a fresh context window abcd surfaces full pages; as the window depletes it falls back to one-line index entries, and stays at them to the end of the session. Memory stops being an all-or-nothing wall and becomes a just-in-time lookup.

"Our .abcd/memory/ had grown to 140 pages across two years," said Carol, tech lead. "Loading all of it was impossible and loading none of it meant agents kept relearning the same pitfalls. Now a prompt about the auth module pulls the three auth pages and nothing else — and when I'm deep in a long session it quietly drops to titles-only so it never crowds out the actual work."

Why This Matters

abcd's .abcd/memory/ (itd-36) is a strong storage model — typed pages, a curator, quotation budgets, contradiction tracking. But it has no retrieval model beyond /abcd:memory ask, an explicit user query. A working agent gets memory all-or-nothing: either the whole corpus is injected (overflow) or none is (relearning). itd-36 bounds ingest; nothing bounds retrieval or total surfaced size.

This intent closes that gap by reusing infrastructure abcd already has. itd-3's modular rules loader is abcd's in-plugin adoption of CARL's recall engine — a UserPromptSubmit hook with domain-keyed keyword recall, signature dedup, and force-refresh-every-N. CARL's same engine drives two payloads: procedural rules and a decision-logging memory layer. abcd adopted the rules half and skipped the memory half. itd-39 adopts the half abcd skipped — and adds CARL's context brackets (adaptive injection by remaining window) as the overflow control itd-36 lacks.

What's In Scope

• Memory recall frontmatter — every .abcd/memory/ page's source: frontmatter gains a recall: keyword list (the domain-keying CARL applies to rules, applied to memory pages).
• Hook extension — hooks/prompt_router_hook.py (itd-3) is extended from rules-only to rules + memory. Same recall scan, same signature dedup, same force-refresh-every-N. The hook reads two indexes: rules.json domains and memory-page recall: frontmatter.
• Context brackets — injection is gated by remaining context budget, after CARL's model: FRESH (≥70% window free) injects matched pages in full; MODERATE (40–70%) injects only highest-relevance pages; DEPLETED (<40%) injects matching index.md lines only (titles, not bodies). This is the bounded-retrieval counterpart to itd-36's bounded-ingest quotation budgets.
• Two-scope query — the hook queries the index.md of both memory scopes (<workspace>/.abcd/memory/ and ~/.abcd.noindex/memory/). On a recall-keyword conflict, the narrower scope wins (workspace > user). The agent never loads the union of both scopes — it loads keyword-matched, budget-bracketed pages only.
• abcd memory recall [keyword] CLI subcommand — diagnostic: shows which pages a given prompt/keyword would surface, and in which bracket. Bare-command-as-render discipline (per 02-constraints/04-naming.md).

What's Out of Scope

• Session-sticky recall — itd-3 establishes per-prompt independent recall (no cross-prompt chaining). itd-39 inherits that model. A "pin this memory for the rest of the task" mode is a deferred candidate.
• Writing to vendor memory — the hook injects from .abcd/memory/. It never reads or writes ~/.claude/.../memory/; that directory is a dev-sync harvest source only (see 02-adapters.md).
• Automatic scope routing of new pages — which scope a curated page lands in is a dev-sync / curator decision (see 07-memory.md scope-routing rule), not a retrieval-hook concern.
• A separate memory MCP server — consistent with itd-3, retrieval is hook + JSON/frontmatter only; no runtime memory-editing MCP in this intent.

Reconciliation with itd-3's global-rules rejection

itd-3 explicitly rejects a global ~/.abcd.noindex/rules.json — "a personal cross-repo rules file recreates the scaffolding-accumulates-outside-the-repo failure mode." itd-39 does place a memory scope at ~/.abcd.noindex/memory/. This is deliberate, not a contradiction:

• Rules are procedural and project-shaped. A rule that applies everywhere belongs in the plugin defaults, not a personal file — hence itd-3's per-repo-only stance.
• Memory is observational and inherently cross-project. A personal working preference ("I prefer X phrasing in commit messages") or a principle that improves abcd development itself is not project-scoped knowledge — it has no per-repo home by nature. Forcing it into a repo would lose it on the next project.

The failure mode itd-3 guards against is unbounded scaffolding outside the repo. itd-39's scopes are bounded by the two-scope .abcd/ namespace (see 05-internals/03-configuration.md) and surfaced by bounded retrieval — they do not accumulate silently into every session. The economics differ; the scopes are justified.

Acceptance Criteria

BDD format, per the itd-1 discipline.

• Given an abcd-installed workspace with a memory page declaring recall: [auth, login], when the user sends a prompt containing "auth", then that page is injected as system context within the turn and non-matching pages are not.
• Given a context window below 40% free, when a memory recall matches three pages, then only the matching index.md lines are injected (titles, not bodies), per the DEPLETED bracket.
• Given the same prompt repeated within a session, when dedup is enabled, then the matched memory injects once and skips on repeats until the force-refresh interval.
• Given a recall keyword that matches a page in both the workspace and user scope, when the hook resolves the match, then the workspace-scope page is injected and the user-scope page is suppressed (narrower scope wins).
• Given any prompt, when the hook runs, then ~/.claude/.../memory/ is never read or written by the retrieval path.

Scope Conditions

None stated.

SOTA

Surveyed on 2026-10-23; sources, evidence tiers and the local fit risks are in the memory-knowledge SOTA note.

• Harnesses recall on files, not prompt words. Claude Code's .claude/rules/ with a paths: glob loads "only when Claude works with matching files"; Cursor's "Apply to Specific Files" auto-attaches on a matching file in context and "Apply Intelligently" lets the agent pull a rule in by its description; Copilot's .github/instructions/*.instructions.md carries an applyTo glob (vendor docs). abcd's keyword-on-prompt recall is the outlier; a file trigger needs a tool hook the loader does not run, so it is a later seam, not a step.
• Lexical ranking is the strong baseline at this size. On a six-project benchmark an information-retrieval detector from a decade ago beat the deep-learning ones by 22.3% average RR@10 "for most projects" (Zhang et al., TOSEM; duplicate-report detection, so an analogy for note recall); the context-window note already records agentic search over RAG at this scale. The spec's BM25F with no embedding stands.
• The fill signal is documented. The status line payload carries session_id, transcript_path and context_window.used_percentage (input tokens only), which "may be null early in the session", while current_usage is null after /compact until the next API call (Claude Code status line docs); the spec's "unknown fill" row is the right default.
• Memory systems with evaluations consolidate on write. Mem0 (Chhikara et al., arXiv 2504.19413, 2025) judges each new fact against its ten nearest memories as ADD, UPDATE, DELETE or NOOP; the hard classes in LongMemEval (ICLR 2025) are knowledge updates and abstention, not lookup. The stale page recalled with confidence is the failure to design against.
• The benchmarks are contested. Zep's rebuttal of Mem0's LoCoMo numbers (75.14% corrected against 65.99% reported), Mem0's own table showing the full-context baseline (72.90) above Mem0 (66.88, graph 68.44), and Zep's note that LoCoMo conversations fit a modern context window and lack knowledge-update questions say the leaderboard settles nothing for abcd.
• Path 2: the native design the spec holds, with Mem0's write discipline carried by the ledger's existing match primitive as an advisory echo on memory add (see the notes intent), and the file-scoped trigger recorded as the seam. The independent fit-challenge is still owed before the build, and the questions below are kept for it.

Questions this pass raised for the fit-challenge before the build. They are kept here, not under Open Questions, so they do not hold a build the record already rules ready:

• Should a page's recall: list later gain an optional file glob, matched against the files a session touches, as every surveyed harness scopes rules? It needs a hook the loader does not run today; the question is whether to reserve the field now or add it when a tool hook exists.

Open Questions

None open; the three questions first left here are settled under Decisions (2026-10-11), and the technical questions the plan leaves open are in the bundle's spec.

Audit Notes

Empty. Populated by intent-fidelity-reviewer when intent moves to shipped/.

Decisions

• 2026-10-11, product thinker: "Build both together". Memory pages (this intent) and memory notes (itd-2610091918433290) share one recall and are planned as one bundle. Where this intent's criteria overlap the notes intent's (the brackets; never reading the host's memory files), both criteria stand and one mechanism serves both.
• 2026-10-11, technical facilitator, the first question first left here: "Share the brackets". Memory recall uses the rules loader's context brackets (itd-3); there are no thresholds tuned separately for memory.
• 2026-10-11, technical facilitator, the second question first left here: "A relevance ranking". When the context is short and only some matching titles fit, a relevance ranking chooses the ones that stay, not the raw count of matching recall words. The spec designs a simple ranking whose choice can be explained, cites its prior art, and adds no dependency unless the person signs off.
• 2026-10-11, technical facilitator, how recall ends: "never send nothing". Recall goes full, then one-line index entries, and stays at them to the end of the session; there is no bracket in which matched pages come back as nothing, because a compaction or a new session resets recall anyway, so the one-line entries cost little and a session never loses sight of a page that matches. The press release's earlier wording, "then to nothing", was accepted into the plan with this bundle on 2026-10-11 and changed the same day by this ruling. The DEPLETED bracket under What's In Scope already ends at index lines and is unchanged.
• 2026-10-11, technical facilitator, the diagnostic: the abcd memory recall [keyword] subcommand under What's In Scope is abcd rules --prompt "<text>", on the existing rules verb, showing the rules, notes and pages one prompt would bring back, in which bracket, with the ranking's reasons. Since the verb split, memory is the agents' notes command and the rules verb already renders what the loader injects.
• 2026-10-11, settled on the record, the third question first left here: release placement no longer waits. itd-36's storage model has shipped, and its store is now reached as library ingest, library ask and library lint (itd-2610090831227812).

References

• Deferred to by: itd-42 (coherence-aware grill) — itd-42's Tier 3 is index-level only; full-body cross-intent comparison at scale is this intent's selective-retrieval problem.

Grounds

• pursued: We expect the right page to reach an agent when it matters, without crowding the context. Shown wrong if matched pages are mostly irrelevant, or if recall crowds out the work.