From 4f3f9881a4e8b3d9a789d8ef1005cb6632565ddd Mon Sep 17 00:00:00 2001 From: rrs <276464689+robotrocketscience@users.noreply.github.com> Date: Fri, 8 May 2026 22:13:04 -0700 Subject: [PATCH 1/6] docs(readme): pain-forward tagline replacing generic memory framing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The 'Persistent memory for AI agents' line is the generic part — every memory project (Letta, Mem0, Zep, MemGPT) says some version of the same thing. The differentiated bits ('Set up once / Stays out of your way') were already strong; replace only the weak first sentence with one that names the actual user-visible outcome. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b1101c2d5..b09961f5c 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,10 @@ # aelfrice -> Persistent memory for AI agents. +> Your AI stops forgetting your rules. > Set up once. Stays out of your way. > -> _Local SQLite. Auditable. No GPU, no network._ +> _Local SQLite. No GPU, no network._ [![PyPI](https://img.shields.io/pypi/v/aelfrice.svg)](https://pypi.org/project/aelfrice/) [![Python](https://img.shields.io/pypi/pyversions/aelfrice.svg)](https://pypi.org/project/aelfrice/) From 99285eaead2d32072178f06350d926dd6f9b13f9 Mon Sep 17 00:00:00 2001 From: rrs <276464689+robotrocketscience@users.noreply.github.com> Date: Fri, 8 May 2026 22:13:23 -0700 Subject: [PATCH 2/6] docs(readme): merge determinism + privacy into 'What you get for free' MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three short H2s in a row (Determinism, Your data stays yours) read choppy and bury the framing. Collapse into one section that opens with 'Running in the background. No action required after aelf setup.' — the actual benefit framing. Dropped: explicit fastmcp dep disclosure (covered by pyproject.toml), 'No GPU, no vector DB' bullet (subsumed by 'no embeddings'). Per-project isolation folded into Local-only as a corollary. --- README.md | 18 +++++------------- 1 file changed, 5 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index b09961f5c..9e83cfd90 100644 --- a/README.md +++ b/README.md @@ -98,23 +98,15 @@ aelfrice replaces the chain with a mechanism. The hook injects matched beliefs * --- -## Determinism +## What you get for free -Same store + same query gives the same beliefs. The retrieval path is stdlib + SQLite — no embeddings, no learned re-rankers, no LLM — so every result traces back to a specific belief and the user action that wrote it. +Running in the background. No action required after `aelf setup`. -Tradeoff: no fuzzy semantic recall. See [PHILOSOPHY.md](docs/PHILOSOPHY.md). - ---- - -## Your data stays yours - -- **100% local.** SQLite at `/.git/aelfrice/memory.db`. No network calls in the retrieval path. -- **No telemetry.** No accounts, no signup, no phone-home. -- **No GPU, no vector DB.** Stdlib + SQLite. The optional `[mcp]` extra adds `fastmcp`. That's it. -- **Per-project isolation.** Beliefs from project A cannot leak into project B (they live in different `.git/` directories). +- **Determinism.** Stdlib + SQLite. No embeddings, no learned re-rankers, no LLM in the retrieval path. Every result traces to the action that wrote it. +- **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. -[docs/PRIVACY.md](docs/PRIVACY.md) for verifiable specifics. +Tradeoff: no fuzzy semantic recall. See [PHILOSOPHY.md](docs/PHILOSOPHY.md). --- From ae8e9630dfe0190db2ac48ec48015d1c17e1a2cf Mon Sep 17 00:00:00 2001 From: rrs <276464689+robotrocketscience@users.noreply.github.com> Date: Fri, 8 May 2026 22:13:37 -0700 Subject: [PATCH 3/6] docs(readme): drop reproducibility section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The reproducibility badge at the top of the file already advertises the bench harness and links to docs/v2_reproducibility_harness.md. The prose section was landing-page space spent on docs content — issue numbers, schema versions, cron-branch names — none of which a first-time discoverer needs to decide whether to install. The badge stays. The detail doc stays. Only the README prose is cut. --- README.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/README.md b/README.md index 9e83cfd90..ec593698b 100644 --- a/README.md +++ b/README.md @@ -129,16 +129,6 @@ The same operations are also available as MCP tools and `/aelf:*` slash commands --- -## Reproducibility - -`aelf bench all --canonical --out benchmarks/results/v2.0.0.json` reproduces every published headline number on a fresh clone within documented tolerance bands. The dispatcher subprocesses each academic-suite adapter (MAB, LoCoMo, LongMemEval, StructMemEval, AMA-Bench) at the canonical headline cut — full per the 2026-05-06 ratification on [#437](https://github.com/robotrocketscience/aelfrice/issues/437) — and merges the per-adapter results into one schema-v2 JSON. - -The `Bench Canonical` nightly cron runs the same harness daily on `main` and pushes the cron entry to a dedicated `bench-canonical-results` branch. Drift outside the per-metric tolerance band fails the workflow; drift inside the band emits a notice. The badge above flips to red on a band-busting regression and stays red until acknowledged. - -Detail: [docs/v2_reproducibility_harness.md](docs/v2_reproducibility_harness.md). - ---- - ## Roadmap | Version | Status | Theme | From c5a3e90016b24f70453993db4e1699ca621dc4f8 Mon Sep 17 00:00:00 2001 From: rrs <276464689+robotrocketscience@users.noreply.github.com> Date: Fri, 8 May 2026 22:14:02 -0700 Subject: [PATCH 4/6] docs(readme): collapse roadmap table to Status section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The 13-row roadmap table was wall-of-issue-numbers — #232, #148, #280, #321, etc. — and inside-baseball theme summaries that rewarded contributors but punished first-time discoverers. The full per-version detail already lives at docs/ROADMAP.md and was already linked from the trailer line. Replace with a 7-line Status section: latest shipped version (v1.7, named features), next planned (v2.0, theme), and links out to docs/ROADMAP.md + docs/LIMITATIONS.md for everyone who needs more. No issue numbers in landing copy. --- README.md | 24 +++++++----------------- 1 file changed, 7 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index ec593698b..dca258e26 100644 --- a/README.md +++ b/README.md @@ -129,24 +129,14 @@ The same operations are also available as MCP tools and `/aelf:*` slash commands --- -## Roadmap +## Status -| Version | Status | Theme | -|---|---|---| -| v1.0.x | shipped | core memory, CLI, MCP, hook wiring, install routing | -| v1.1.0 | shipped | per-project DBs (`.git/aelfrice/`), `aelf migrate`, `edges`→`threads` rename, `aelf health` rewrite | -| v1.2.0 | shipped | auto-capture pipeline (transcript-ingest, commit-ingest, SessionStart), `agent_inferred → user_validated` promotion, triple extractor, `--batch` JSONL ingest, CLI consolidation, `INEDIBLE` per-file opt-out | -| v1.2.x | planned | search-tool `PreToolUse` hook — memory-first context on Grep/Glob | -| v1.3 | shipped | retrieval wave — entity index (L2.5), BFS multi-hop (L3), LLM-Haiku onboard classifier (opt-in), partial Bayesian-weighted ranking | -| v1.4 | shipped | context rebuilder — PreCompact retrieval-curated continuation (augment mode); manual + threshold trigger; continuation-fidelity scorer (exact-match) | -| v1.5 | shipped | retrieval plumbing — composition plumbing + per-lane telemetry (#232), BM25F anchor text (#148), search-tool Bash matcher (#155), v3 federation version-vector schema (#204), v1.4 dynamic-trigger re-park (#188) | -| v1.5.x | shipped | default-on host-driven LLM onboard classifier (#238, in v1.5.1) | -| v1.6 | shipped | hardening + observability — hook-hardening framing-tag contract + audit log (#280, #297, #314), `aelf tail` (#321, #322), belief retention class (#290), rebuild diagnostic log (#288), posterior-ranking eval harness + heat-kernel composition (#151, #306, #310; default-flip still gated), deferred-feedback sweeper (#191, #256), v2.0 corpus public scaffold + bench-gate (#307, #311, #319, #320), `replay_full_equality` probe (#262, #304), `session_id` propagation (#192), reachable-install detection (#345) | -| v1.7 | shipped | graph signal wave + structural retrieval lane — signed Laplacian + eigenbasis (#149), heat kernel authority (#150), Plate FFT HRR primitives (#216), HRR bind/probe (#152), `uri_baki` post-rank adjuster retest (#153). BM25F anchor-text retrieval (#148) **default-on** at v1.7.0 per #154 bench evidence (+0.6650 NDCG@k uplift on the v0.1 retrieve_uplift fixture under Porter stemming). Heat-kernel authority (`use_heat_kernel`) and HRR structural (`use_hrr_structural`) are wired and ship behind opt-in `[retrieval]` flags in `.aelfrice.toml` — they stay default-OFF until the composition tracker (#154) bench gate flips them. Signed-Laplacian (`use_signed_laplacian`) and posterior-ranking (`use_posterior_ranking`) are still placeholder flags pending wiring. | -| v2.0 | planned | feature parity with the original research line + benchmark reproducibility. v2.0's component issues land incrementally across v1.5–v1.7; final v2.0 tag is the reproducibility cut. | -| v2.1 | planned | post-calibration retrieval-pipeline wave — view-flip (#265), bench-gated cluster (#197 dedup, #433 HRR vocab bridge, #434 type-aware compression, #435 doc/semantic linker, #436 intentional clustering), operator-gated query understanding (#291) + close-the-loop relevance (#365), and gate-commit follow-ups (smoke-fixture license (#311), badge cron-rewrite, dispatcher 3-state (#479), gate-list CLI (#475)). Tracker: [#474](https://github.com/robotrocketscience/aelfrice/issues/474). | - -Per-version detail: [docs/ROADMAP.md](docs/ROADMAP.md). Open issues: [docs/LIMITATIONS.md](docs/LIMITATIONS.md). +Latest stable: **v1.7** — graph-signal retrieval lane (signed Laplacian, heat-kernel authority, Plate FFT HRR primitives), BM25F anchor-text retrieval default-on. + +Next: **v2.0** — research-line parity + benchmark reproducibility cut. + +Per-version detail: [docs/ROADMAP.md](docs/ROADMAP.md). +Open issues / known limits: [docs/LIMITATIONS.md](docs/LIMITATIONS.md). --- From dcadc13f6503cf003aa5bc52d8c39cd7bc3e32dc Mon Sep 17 00:00:00 2001 From: rrs <276464689+robotrocketscience@users.noreply.github.com> Date: Fri, 8 May 2026 22:14:36 -0700 Subject: [PATCH 5/6] gate: README discoverer-rewrite ready for review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Four atomic docs commits redrafting README for first-time-discoverer audience. Cut from 190 → 162 lines (-28). Tagline rewrite, three-section merge, reproducibility prose dropped, full roadmap table → 7-line Status. Verification: - Line count: 162 (was 190); 4 atomic commits + this gate - Diff stat: +12 / -40, single file (README.md) - All H2 anchors still resolve to existing doc links (PHILOSOPHY.md, PRIVACY.md, ROADMAP.md, LIMITATIONS.md, COMMANDS.md, MCP.md, SLASH_COMMANDS.md) — no broken internal references introduced - Hero image, badges, install snippet, "What it does" example block, "Why files don't solve this" comparison, "Day-to-day surface", Documentation index, Citation block all unchanged - Tagline: Option B (pain-forward) per user pick - Branch: docs/readme-discoverer-rewrite, branched from current HEAD (clean off recent main) Blockers (require user decision before next phase): - [user] Approve diff and authorize push to github remote, OR - [user] Request adjustments to any of the four atomic commits before push - [user] Confirm whether to open PR vs merge-locally on main Open questions: - Tagline keeps "Auditable" out of subline-3 (per literal Option B pitch). Adding it back is a 1-line amendment if preferred. - "What it remembers" table (lock/onboard/feedback rows) was kept as separate H2 since it's API surface, not abstract benefit. Confirm this is the intended split. Rollback: - git reset --hard main (drops all 4 docs commits + this gate; branch is local-only, never pushed) From d5d321653eef11b41fd7472878a9075f5e6174e0 Mon Sep 17 00:00:00 2001 From: rrs <276464689+robotrocketscience@users.noreply.github.com> Date: Fri, 8 May 2026 22:16:00 -0700 Subject: [PATCH 6/6] docs(readme): restore Auditable anchor to tagline subline Original tagline had three anchors (Local SQLite, Auditable, No GPU/no network). Earlier rewrite dropped 'Auditable' to match the literal Option B pitch; restoring it because it names a real differentiator vs. embedding-based memory systems that the body alone doesn't adequately surface in 30-second-skim mode. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index dca258e26..e98ccc6e4 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ > Your AI stops forgetting your rules. > Set up once. Stays out of your way. > -> _Local SQLite. No GPU, no network._ +> _Local SQLite. Auditable. No GPU, no network._ [![PyPI](https://img.shields.io/pypi/v/aelfrice.svg)](https://pypi.org/project/aelfrice/) [![Python](https://img.shields.io/pypi/pyversions/aelfrice.svg)](https://pypi.org/project/aelfrice/)