Skip to content

docs(readme): redraft for first-time discoverer (190 → 162 lines) #508

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
robotrocketscience merged 6 commits into from
May 9, 2026
Merged

docs(readme): redraft for first-time discoverer (190 → 162 lines) #508

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4f3f988
docs(readme): pain-forward tagline replacing generic memory framing
robotrocketscience May 9, 2026
99285ea
docs(readme): merge determinism + privacy into 'What you get for free'
robotrocketscience May 9, 2026
ae8e963
docs(readme): drop reproducibility section
robotrocketscience May 9, 2026
c5a3e90
docs(readme): collapse roadmap table to Status section
robotrocketscience May 9, 2026
dcadc13
gate: README discoverer-rewrite ready for review
robotrocketscience May 9, 2026
d5d3216
docs(readme): restore Auditable anchor to tagline subline
robotrocketscience May 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 11 additions & 39 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

# 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._
Expand Down Expand Up @@ -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`.

@coderabbitai coderabbitai Bot May 9, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Line 103 overstates “no action required” after setup.

“No action required after aelf setup” conflicts with nearby first-run flow (aelf onboard ., optional aelf lock ...). Consider softening to “no recurring action required after setup/onboarding.”

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` at line 103, Update the sentence that currently reads "No action
required after `aelf setup`" to a softened phrase that reflects the first-run
onboarding steps; replace that exact string with something like "No recurring
action required after setup/onboarding" or "No recurring action required after
`aelf setup` (initial onboarding like `aelf onboard .` or `aelf lock ...` may
still be needed)" so the README no longer implies absolute no further steps
while preserving the intended meaning.


Tradeoff: no fuzzy semantic recall. See [PHILOSOPHY.md](docs/PHILOSOPHY.md).

---

## Your data stays yours

- **100% local.** SQLite at `<repo>/.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 `<repo>/.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).

---

Expand All @@ -137,34 +129,14 @@ The same operations are also available as MCP tools and `/aelf:*` slash commands

---

## Reproducibility
## Status

`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.
Latest stable: **v1.7** — graph-signal retrieval lane (signed Laplacian, heat-kernel authority, Plate FFT HRR primitives), BM25F anchor-text retrieval default-on.

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.
Next: **v2.0** — research-line parity + benchmark reproducibility cut.

Detail: [docs/v2_reproducibility_harness.md](docs/v2_reproducibility_harness.md).

---

## Roadmap

| 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).
Per-version detail: [docs/ROADMAP.md](docs/ROADMAP.md).
Open issues / known limits: [docs/LIMITATIONS.md](docs/LIMITATIONS.md).

---

Expand Down
Loading