A figure of shimmering cloud rising from a dark sea, weaving threads of light into a constellation of beliefs

aelfrice

aelfrice gives an AI coding agent a local memory: the rules you lock, and the beliefs that match what you ask, reach the model before it reads your message.

Problem. An agent forgets your corrections between sessions, so you repeat them.
Method. Before the model reads each prompt, a hook adds every rule you locked and the beliefs that best match the prompt, from an entity index and BM25 full-text search over a local SQLite store.
Provenance. Every belief records where it came from and carries a Bayesian confidence that moves when you confirm it with /aelf:confirm, rate it with aelf feedback, or praise an answer it informed; a lock pins it as ground truth.
Scope. aelfrice captures your turns and commits as you work, and retrieval runs on your machine with no account, telemetry, embeddings, or LLM. By default it also checks PyPI for updates, and /aelf:onboard classifies with your agent's model (privacy).

How a conversation becomes beliefs. A belief is one statement stored with its source, a type, and a confidence score. About every six prompts (12 logged lines, counting the replies), aelfrice splits your prompts into sentences, drops noise and questions, and stores the rest as facts, corrections, preferences, or requirements. The model's replies to you are skipped. When a later prompt matches stored beliefs, the best matches are ranked and added to it. They're beliefs, not facts: /aelf:confirm and aelf feedback move each one's confidence, and so does a short reply such as "perfect". A complaint such as "that's wrong" counts only if you turn on negative sentiment feedback. Only a lock makes a belief ground truth.

Install

Install uv.
Install aelfrice:
```
uv tool install aelfrice
```
Connect it to your agent:
```
aelf setup
```
If your agent is the Codex CLI, run aelf setup --host codex instead, then run /hooks in Codex to trust the new hooks. Codex uses $aelf-* skills where this page says /aelf:.
In your agent, from your project directory, scan the project:
```
/aelf:onboard .
```
Lock your first rule:
```
/aelf:lock never push directly to main
```

From then on, aelfrice runs by itself. To check the install, run /aelf:doctor (aelf doctor --host codex on Codex). The installation guide covers every option.

An illustrative schematic of the retrieval lanes of aelfrice over a belief graph: locked beliefs pinned at the query, keyword seeds from full-text search spreading outward, an optional typed-edge graph walk, and a structural lane for marker queries.

Commands

Command	What it does	When to use it
`/aelf:lock <text>`	Locks a statement as ground truth that every prompt carries.	You want a rule the agent never forgets.
`/aelf:search <query>`	Shows what the store returns for a query, locked rules first; a hook also runs it on the agent's own searches (Grep, Glob, WebSearch, WebFetch, and `grep` or `rg` in Bash) and returns the results next to the tool's output.	You want to check what memory holds on a topic.
`/aelf:locked`	Lists your locked rules.	You want to review the rules in force.
`/aelf:onboard <path>`	Scans a project and stores what it learns.	You start using aelfrice on a project.
`/aelf:status`	Shows counts of beliefs, locks, and feedback.	You want a quick health summary.
`/aelf:doctor`	Checks the hooks and the store, and exits nonzero on a failure.	You finish setup, or memory seems silent.
`/aelf:unlock <id>`	Removes the lock from a belief.	A rule no longer applies.
`/aelf:confirm <id>`	Raises a belief's confidence without locking it.	A belief proved right, but it isn't a rule.
`/aelf:review`	Writes a keep, remove, or lock checklist, then applies your verdicts.	You do a weekly cleanup.
`/aelf:retire <id>`	Removes a belief from retrieval, reversibly.	A belief is wrong or outdated.
`/aelf:wonder <topic>`	Researches a topic and stores the findings as speculative beliefs.	You want memory to fill a gap.
`/aelf:reason <query>`	Walks the belief graph and reports a verdict and suggested updates.	You want a structured answer from memory.

The other 19 commands

Command	What it does	When to use it
`/aelf:setup`	Installs the aelfrice hooks into your agent.	You install aelfrice, or repair its hooks.
`/aelf:show <id>`	Prints one belief in full with its origin and confidence.	You want the whole of one belief.
`/aelf:core`	Lists the load-bearing beliefs: locks, repeated ones, and high-confidence ones.	You want to see what anchors your memory.
`/aelf:feed`	Shows the log of belief writes.	You want to see what aelfrice recorded.
`/aelf:tail`	Streams what the hooks injected on each prompt and session start.	You want to see what the agent was actually told.
`/aelf:stale`	Lists old beliefs that haven't been retrieved recently.	You prune memory that went cold.
`/aelf:restore <id>`	Brings a retired belief back.	You retired something by mistake.
`/aelf:delete <id>`	Deletes a belief permanently.	A belief must be gone for good.
`/aelf:promote <id>`	Marks an agent-inferred belief as validated by you.	You confirm what the agent worked out.
`/aelf:speculative`	Lists unlocked beliefs, the most-supported first.	You want to audit what isn't locked.
`/aelf:scope-out <text>`	Hides matching beliefs for the rest of this session.	A belief is noise for the task at hand.
`/aelf:category`	Groups rules and binds them to trigger keywords; injection is off by default.	A set of rules applies to one kind of task.
`/aelf:graph <id>`	Emits the belief graph around a belief as DOT or JSON.	You want to visualize connections.
`/aelf:introspect`	Shows beliefs by session or project with their confidence and grounding.	You want to judge what was captured.
`/aelf:rebuild`	Prints the context block the rebuilder would restore.	You're debugging context after compaction.
`/aelf:audit-claude-memory`	Compares locked beliefs with the `MEMORY.md` index your agent keeps.	You keep both and want them consistent.
`/aelf:eval`	Runs the relevance-calibration harness on a corpus you pass with `--corpus`.	You're measuring retrieval quality.
`/aelf:upgrade`	Upgrades aelfrice to the latest release.	A new version is out.
`/aelf:uninstall`	Removes the hooks, and keeps, deletes, or archives the store as you choose; `uv tool uninstall aelfrice` then removes the package.	You stop using aelfrice.

Each command has a terminal form, such as aelf lock "...". The command reference documents all of them.

Belief types and edges

Every belief has one type. Transcript text gets its type from a rule-based classifier, and /aelf:onboard uses your agent's model by default. New text from aelf lock or the commit hook is stored as factual, and /aelf:wonder stores speculative. Locked is a flag on top of the type, not a type of its own.

Type	What it holds	How a belief gets it
`factual`	A statement about the project or the world.	The default, when no other rule matches.
`requirement`	A rule that has to hold.	It contains a word such as "must" or "required".
`correction`	A fix to something said earlier.	The correction detector matches it.
`preference`	How you like things done.	It contains a phrase such as "I prefer" or "always use".
`speculative`	A guess that isn't trusted yet, called a phantom.	`/aelf:wonder` writes it.

Edges link beliefs, from a source to a target. Only the first two are written for every conversation today. The others need a command, an opt-in setting, or a specific phrase in a commit message. The commit hook reads a message when the agent runs git commit, and it matches only unambiguous phrasings: "is supported by" counts, but "supports" doesn't.

Edge	Meaning	Written by	On by default
`TEMPORAL_NEXT`	Stored right after the target, in the same session.	Transcript ingest, for each new belief; the commit hook ("comes after", "is after", "succeeds").	Yes
`DERIVED_FROM`	Follows from the target: the previous turn, or an earlier clause in the same turn.	Transcript ingest; the commit hook ("is derived from", "is based on").	Yes
`RELATES_TO`	About the same topic as the target.	`/aelf:wonder`; the commit hook ("relates to", "is related to").	When you run it, or on those phrases
`SUPPORTS`	Evidence for the target.	The commit hook ("is supported by").	On that phrase only
`CITES`	Mentions the target.	The commit hook ("cites", "mentions").	On those phrases only
`IMPLEMENTS`	Code that implements the target.	The commit hook ("implements", "is an implementation of", "realizes", "fulfills").	On those phrases only
`TESTS`	A test of the target.	The commit hook ("is a test for", "is test of", "is tested by", "is covered by").	On those phrases only
`CONTRADICTS`	Conflicts with the target.	The relationship detector at ingest; the commit hook ("contradicts", "disagrees with").	Detector: no, set `[relationship_detector] auto_detect = true`. Commit hook: on those phrases
`SUPERSEDES`	Replaces the target.	`aelf resolve`, which keeps the winner of each contradicting pair; the commit hook ("supersedes").	When you run it, or on that phrase
`POTENTIALLY_STALE`	Marks the target, an older belief, as possibly out of date.	`aelf doctor --detect-stale`.	When you run it
`RESOLVES`	A phantom answers the target.	Nothing writes it yet (#1658).	No

Work to write more of these edges automatically is tracked in #1653.

A pen-and-ink figure holding a sword, with ranks of armored figures branching above and behind him like a tree

Learn more

Quickstart · Architecture · Configuration · Philosophy · Comparison · Privacy · Limitations · Changelog · Contributing

MIT license

Metadata

Release files for aelfrice 5.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aelfrice 5.1.0
File	Size	Uploaded
aelfrice-5.1.0.tar.gz	11.7 MB	Oct 7, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for aelfrice 5.1.0
File	Interpreter	ABI	Platform	Reset
aelfrice-5.1.0-py3-none-any.whl 1.3 MB Oct 7, 2026	Python 3	none	any	Details

Total release size: 13.0 MB

Release files / aelfrice-5.1.0.tar.gz

Download URL	aelfrice-5.1.0.tar.gz
Size	11.7 MB
Tags	Source
SHA-256 checksum How to use checksums	`d9d39c416a4a804edbb12697beb6eccf9c94225090e6defc7fe5d8fb7c2dc658`
BLAKE2b-256 checksum How to use checksums	`3173f4b03526d716982d9a16de01e48ebde4a3f7f2303a3c971da89b0301b9dd`
Upload date	Oct 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/robotrocketscience/aelfrice
Publishing commit: github.com/robotrocketscience/aelfrice/tree/7e8135dc5d38e39c6bc5e9c538f6cbbdabf0fff7

Workflow

Publishing configuration: github.com/robotrocketscience/aelfrice/blob/7e8135dc5d38e39c6bc5e9c538f6cbbdabf0fff7/.github/workflows/publish.yml
Publishing logs: github.com/robotrocketscience/aelfrice/actions/runs/37651435806/attempts/1

Artifact

Subject: aelfrice-5.1.0.tar.gz
SHA-256 checksum: d9d39c416a4a804edbb12697beb6eccf9c94225090e6defc7fe5d8fb7c2dc658 Verifying attestations

Release files / aelfrice-5.1.0-py3-none-any.whl

Download URL	aelfrice-5.1.0-py3-none-any.whl
Size	1.3 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`485a6ee1970e77d554e3ee44c64c5fd8283103ea3ac43621b13876a69d38f48b`
BLAKE2b-256 checksum How to use checksums	`36a518804a7678eab51f9b56945a7dc53ab0cfbfc17a876118d4174ca371921c`
Upload date	Oct 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/robotrocketscience/aelfrice
Publishing commit: github.com/robotrocketscience/aelfrice/tree/7e8135dc5d38e39c6bc5e9c538f6cbbdabf0fff7

Workflow

Publishing configuration: github.com/robotrocketscience/aelfrice/blob/7e8135dc5d38e39c6bc5e9c538f6cbbdabf0fff7/.github/workflows/publish.yml
Publishing logs: github.com/robotrocketscience/aelfrice/actions/runs/37651435806/attempts/1

Artifact

Subject: aelfrice-5.1.0-py3-none-any.whl
SHA-256 checksum: 485a6ee1970e77d554e3ee44c64c5fd8283103ea3ac43621b13876a69d38f48b Verifying attestations