aelfrice 2.0.1

Persistent memory for AI agents. Set up once. Stays out of your way. Local SQLite, auditable, no GPU, no network.

aelfrice

Your AI stops forgetting your rules. Set up once. Stays out of your way.

Local SQLite. Auditable. No GPU, no network.

You correct your agent. "Got it," it says. Next session, same mistake.

aelfrice runs in the background and stops the forgetting. You write a rule once and it gets attached to every prompt thereafter — no cross-references for the agent to skip, no markdown files to maintain, nothing to remember to do.

pipx install aelfrice    # or: uv tool install aelfrice
aelf setup               # wire the hook into your agent
aelf onboard .           # scan the current project and ingest beliefs

Then add your first rule and restart your agent:

aelf lock "never push directly to main; use scripts/publish.sh"

That's it. Your next prompt that mentions "push" already has the rule attached. From here on out aelfrice is invisible — no command to remember to run, no file to keep updated.

The aelf lock line above is an example — substitute your own rule. Skip it entirely if you'd rather start with onboarded beliefs only and add locks as you go.

---

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:

L0: locked beliefs   -> rules you marked permanent (always returned)
L1: FTS5 keyword     -> SQLite full-text search, BM25-ranked

The matching beliefs come back as an <aelfrice-memory> block prepended to your prompt. The agent reads it as part of the prompt — it doesn't have to remember to check a file.

<aelfrice-memory>
[locked] never push directly to main; use scripts/publish.sh
[locked] commits must be SSH-signed with ~/.ssh/id_rrs
         the publish script runs gitleaks before tagging
</aelfrice-memory>

push the release

Default budget is 2,400 tokens per prompt. Locked beliefs are the always-injected pool — every lock ships on every prompt, in full, regardless of relevance score. Lock count is your baseline-context budget knob: if you've locked 200 things, every session opens with all 200, by your design. The non-locked pool (FTS/L1) is BM25-ranked and truncated to fit.

---

What it remembers

You run	It stores
aelf lock "never commit .env files"	Permanent rule. Returned on every retrieval.
aelf onboard .	Walks the project — git log, README headings, code structure — and ingests structural facts.
aelf feedback <id> used	Bayesian feedback. Strengthens the belief's posterior.
aelf feedback <id> harmful	Weakens it. After enough independent harmfuls, locks auto-demote.

Each belief carries a (α, β) Beta-Bernoulli posterior. α / (α+β) is the confidence. Locks short-circuit decay; everything else fades over time so stale beliefs eventually drop out of retrieval.

aelf stats
# beliefs:    142   locked: 8   threads: 67
# feedback:   31    avg_confidence: 0.71

---

Why files don't solve this

The standard workaround for "agent keeps forgetting" is more files: STATE.md, DECISIONS.md, a CLAUDE.md with cross-references to runbooks. Every cross-reference is a bet that the agent will read the file, find the right section, and follow what it says.

The failure modes are predictable. The agent reads the rule and runs git push anyway. Cross-references break silently after compaction. State files rot the moment you forget to update them. Each new failure mode begets another file.

aelfrice replaces the chain with a mechanism. The hook injects matched beliefs as part of your prompt, before the agent sees it. Nothing voluntary. Nothing the agent can skip.

Manual approach	What breaks	aelfrice
Rules in CLAUDE.md	Agent reads them, doesn't follow them	Injected per-prompt, not per-session
Cross-references	Agent skips or reads the wrong section	Matched beliefs injected directly
Hand-maintained state files	One missed update breaks the chain	State is the SQLite DB; no manual sync

---

What you get for free

Running in the background. No action required after aelf setup.

• 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.
• 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.

---

Day-to-day surface

After aelf setup you should rarely type aelf again. The day-to-day commands are six:

aelf onboard .                      # once per project — scan and ingest
aelf lock "never push to main"      # add a permanent rule
aelf locked                          # see what rules are active
aelf search "push to main"           # check what the agent will see
aelf status                          # quick health summary
aelf setup / aelf doctor            # initial install + verification

Everything else (deeper diagnostics, archive/uninstall, migration tools, hook entry-points called by Claude Code itself) is callable but not something you reach for in normal use. aelf --help shows the everyday surface; aelf --help --advanced lists the rest. Full reference: COMMANDS.

The same operations are also available as MCP tools and /aelf:* slash commands — same library underneath. See MCP and SLASH_COMMANDS.

---

Status

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. Open issues / known limits: docs/LIMITATIONS.md.

---

Documentation

• Getting started: Install · Quickstart
• Reference: Commands · MCP · Slash commands · Config
• Background: Architecture · Philosophy · Privacy · Limitations
• Development: Releasing · Changelog · Contributing · Security

Citation

@software{aelfrice2026,
  author = {robotrocketscience},
  title  = {aelfrice: deterministic Bayesian memory for AI coding agents},
  year   = {2026},
  url    = {https://github.com/robotrocketscience/aelfrice},
  license = {MIT}
}

MIT