<p align="center"><img src="docs/assets/01-hero-kulili.png" width="100%" alt="A figure of shimmering cloud rising from a dark sea, weaving threads of light into a constellation of beliefs"></p>

aelfrice

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

No cloud. No account. No telemetry.

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

aelfrice runs in the background and stops the amnesia. Write a rule once and every relevant prompt thereafter ships with that rule already attached, before the model sees your message. There is no rules file to maintain and nothing for the agent to skip: the matched beliefs are in the prompt itself.

Built for developers using AI coding agents. Hosts that expose a UserPromptSubmit hook get first-class support; any MCP host can use the included stdio server. Local-only by design — embeddings, vector RAG, and cloud sync are out of scope, and Philosophy explains why that trade-off is worth it.

Install

uv tool install aelfrice    # requires uv — https://docs.astral.sh/uv/
aelf setup                  # wire the UserPromptSubmit hook into your agent
aelf onboard .              # deterministic project scan (regex classifier). For LLM-quality with no API key, run /aelf:onboard in your agent.
aelf lock "never push directly to main; use scripts/publish.sh"

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

Using Codex CLI? aelf setup --host codex wires the same hook set into ~/.codex/hooks.json and ships the /aelf:* command bundle as $aelf-* agent skills (v4.1.0+) — see INSTALL § Codex host.

What you'll see

You type a message in your agent. aelfrice's hook fires before the model sees it and prepends matched beliefs as an <aelfrice-memory> block:

<aelfrice-memory>
The following are retrieved beliefs from the local memory store. ...
<belief id="a1f3c2d0" lock="user">never push directly to main; use scripts/publish.sh</belief>
<belief id="91e02d3c" lock="user">commits must be SSH-signed with ~/.ssh/id_ed25519</belief>
<belief id="77c01b2a">the publish script runs the release checks before tagging</belief>
</aelfrice-memory>

push the release

The model reads the whole thing as one message. Your rules arrive every relevant time, not when the agent decides to check a file.

What it does for you

Lock a rule once with aelf lock "..." and it comes back attached to every relevant prompt, in every future session. The reminding happens for you — and the model can't skip it, because the rule is already in the prompt when it starts reading rather than sitting in a file it may or may not consult.

There's also nothing to maintain. Passive capture logs and ingests every turn, and successful git commit messages too, so the memory grows while you work without you typing aelf at all.

And it all stays on your computer: one SQLite file, no cloud account, no telemetry. If you stop trusting aelfrice, aelf uninstall removes it in one command (--archive encrypts the DB to a file first).

Why not just a rules file?

A rules file is advice the agent may read; aelfrice is context the model has already read. And by Leonard Lin's bar, "a vector store with a similarity query" is not a memory system either — a memory system has to answer *who wrote this, when, via what i