From a0cde840de3c161d7fe4736454e3a839572caab1 Mon Sep 17 00:00:00 2001 From: rrs <276464689+robotrocketscience@users.noreply.github.com> Date: Wed, 13 May 2026 11:00:25 -0700 Subject: [PATCH 1/3] docs(readme): lead 'What it does' with the v3.0 four-lane stack MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The v3.0 release-prep PR (b3022b2) parked the four-lane reality behind an apology paragraph because the pre-push discretion grep flagged any rewrite of the introductory sentence (it contains 'Claude Code' and git's line-level diff put the unchanged phrase on a '+' line under a within-line edit). Now that v3.0 is shipped I can rewrite cleanly: drop 'in Claude Code' from the lead sentence (the same phrase still appears elsewhere in the README; it doesn't need to live on this one line), flip 'two-layer search' to 'four retrieval lanes in parallel and merges the result', expand the code block to L0/L1/L2/L2.5 with concrete lane descriptions (BM25 + posterior-weighted rerank, typed-edge BFS over named edge types, Plate-FFT structural bind/probe), and replace the apology paragraph with a one-liner that names the trim policy, the 2,400-token default budget, and the #718 stack-r1-r3 default flip with its bench numbers (+0.2851 NDCG@k absolute / +94.8% / p99 4.5 ms). ARCHITECTURE § Retrieval cross-link preserved. --- README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index b51c9d7bd..2751a3daa 100644 --- a/README.md +++ b/README.md @@ -55,14 +55,16 @@ That's it. Your next prompt that mentions "push" already has the rule attached. ## What it does -When you submit a prompt in Claude Code, aelfrice's `UserPromptSubmit` hook fires before the model sees your message. It runs a two-layer search: +When you submit a prompt, aelfrice's `UserPromptSubmit` hook fires before the model sees your message. It runs four retrieval lanes in parallel and merges the result: ``` -L0: locked beliefs -> rules you marked permanent (always returned) -L1: FTS5 keyword -> SQLite full-text search, BM25-ranked +L0: locked beliefs -> rules you marked permanent (always returned, never trimmed) +L1: FTS5 keyword -> SQLite full-text search, BM25 + posterior-weighted rerank +L2: graph walk -> typed-edge BFS from L1 seeds (SUPPORTS, CONTRADICTS, SUPERSEDES, DERIVED_FROM, ...) +L2.5: structural HRR -> Plate-FFT bind/probe against anchor text + structural markers ``` -(Since v3.0, two additional lanes run alongside L1 by default: an L2 graph walk over typed edges from L1 seeds, and an L2.5 structural HRR rerank against anchor text and structural markers. The two-layer phrasing above is the v1.0 baseline; the four-lane stack is the v3.0 default. See [ARCHITECTURE § Retrieval](docs/ARCHITECTURE.md#retrieval).) +L0 always ships; L1, L2, and L2.5 are budget-trimmed against the merged candidate set in score-descending order, with locked beliefs winning every overflow. Default token budget is 2,400. The default ranking stack flipped to `stack-r1-r3` (entity expansion + per-store IDF clipping) at v3.0; bench evidence on the labeled query-strategy corpus measured **+0.2851 absolute NDCG@k (+94.8%)** versus the v1.4 raw-BM25 baseline at p99 latency 4.5 ms. Full lane wiring (composition, latency budgets, federation peer DBs) is in [ARCHITECTURE § Retrieval](docs/ARCHITECTURE.md#retrieval). The matching beliefs come back as an `` block prepended to your prompt. The agent reads it as part of the prompt — it doesn't have to remember to check a file. From f26c7e2b34c184e53b1da8674e4afcbe6e6f5024 Mon Sep 17 00:00:00 2001 From: rrs <276464689+robotrocketscience@users.noreply.github.com> Date: Wed, 13 May 2026 11:02:27 -0700 Subject: [PATCH 2/3] docs(readme): drop 'no fuzzy semantic recall' tradeoff line MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two problems with the line as written: 1. It assumes the reader's default is a vector DB and frames aelfrice as giving something up in exchange. 'What you get for free' is the value-prop section; a one-line antifeature in the middle of it interrupts the pitch and answers a question new readers haven't asked yet. 2. It overstates the gap. The v1.7 HRR structural-query lane (default- on as of v2.1, #154) closed the vocabulary-gap-recovery case that embedding pitches usually rest on -- the #433 vocabulary-bridge campaign reframed 'vocabulary bridge' as 'typed-edge structural retrieval' and closed wontfix on that basis. 'No fuzzy semantic recall' is true at the embedding level but misleading at the capability level. The full nuance (free-form paraphrase / synonymy lives in the consuming agent per the v3.0 #605 ratification; embedding systems still beat aelfrice on multi-session aggregation) lives in PHILOSOPHY § Determinism and LIMITATIONS § No semantic similarity. Both are linked one section down in the README. The compressed one-liner here is noise, not signal. --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index 2751a3daa..155c102a1 100644 --- a/README.md +++ b/README.md @@ -159,8 +159,6 @@ Running in the background. No action required after `aelf setup`. - **Local-only.** SQLite at `/.git/aelfrice/memory.db`. No telemetry, no network calls, no accounts. Per-project isolation by construction. See [PRIVACY.md](docs/PRIVACY.md). - **Removable.** `aelf uninstall --archive backup.aenc` encrypts the DB to a file, then deletes it. Or `--purge` for a full wipe. -Tradeoff: no fuzzy semantic recall. See [PHILOSOPHY.md](docs/PHILOSOPHY.md). - --- ## Day-to-day surface From bc1146960c2635df28b8b94e84f0b59642662d7c Mon Sep 17 00:00:00 2001 From: rrs <276464689+robotrocketscience@users.noreply.github.com> Date: Wed, 13 May 2026 11:06:58 -0700 Subject: [PATCH 3/3] docs(readme): tag the L0/L1/L2/L2.5 fenced block as `text` (MD040) CodeRabbit flagged the new fenced block on PR #729 line 60 as missing a language tag (markdownlint MD040). The block carries pseudo-format output (lane name + arrow + description), so `text` is the right tag. Closes the unresolved review thread blocking merge-train per the #721 conversation-resolution pre-check. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 155c102a1..bea6eee5b 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,7 @@ That's it. Your next prompt that mentions "push" already has the rule attached. When you submit a prompt, aelfrice's `UserPromptSubmit` hook fires before the model sees your message. It runs four retrieval lanes in parallel and merges the result: -``` +```text L0: locked beliefs -> rules you marked permanent (always returned, never trimmed) L1: FTS5 keyword -> SQLite full-text search, BM25 + posterior-weighted rerank L2: graph walk -> typed-edge BFS from L1 seeds (SUPPORTS, CONTRADICTS, SUPERSEDES, DERIVED_FROM, ...)