aelfrice
aelfrice gives an AI coding agent a local memory: before the model reads each prompt, a hook adds your locked beliefs and the best-ranked matches to it. An agent forgets your corrections between sessions, so you repeat them.
- aelfrice stores your turns and commits as beliefs; a belief becomes ground truth only when you lock it with
/aelf:lock. - Retrieval uses an entity index and BM25 over local SQLite and needs no account, telemetry, embeddings, or LLM.
By default, aelfrice checks PyPI for updates and runs your claude CLI in the background to label new core beliefs, and /aelf:onboard classifies with your agent's model. See the privacy document.
Beliefs
A belief is one statement with its source, type, and Bayesian confidence score. Every 12 logged lines (about six prompts and replies), aelfrice stores each sentence of your prompts as a fact, correction, preference, or requirement. It skips noise, questions, and the model's replies.
/aelf:confirm and aelf feedback change a belief's confidence, as does praise such as "perfect" for an answer it informed. Complaints such as "that's wrong" count only with negative sentiment feedback on.
Installation
-
Install uv.
-
Install aelfrice:
uv tool install aelfrice
-
Connect aelfrice to your agent:
aelf setupOn Codex, run
aelf setup --host codexinstead, then trust the hooks with/hooks. Codex uses$aelf-*in place of/aelf:. -
In your agent, scan your project from its directory:
/aelf:onboard .
-
Lock your first belief:
/aelf:lock never push directly to main
aelfrice then runs without further commands. /aelf:doctor checks the install (aelf doctor --host codex on Codex). The installation guide covers every option.
Commands
| Command | Does | Use when |
|---|---|---|
/aelf:lock <text> |
Locks a belief as ground truth for every prompt. | Must always hold. |
/aelf:search <query> |
Lists matches, locks first. A hook also runs it on the agent's Grep, Glob, WebSearch, WebFetch, and Bash grep or rg calls and appends the results. |
Checking a topic. |
/aelf:locked |
Lists locked beliefs. | Reviewing locks. |
/aelf:onboard <path> |
Scans a project and stores what it learns. | New project. |
/aelf:status |
Shows counts of beliefs, locks, and feedback. | Health check. |
/aelf:doctor |
Checks hooks and store; exits nonzero on failure. | After setup, or no injection. |
/aelf:unlock <id> |
Removes a belief's lock. | Lock no longer applies. |
/aelf:confirm <id> |
Raises a belief's confidence without locking it. | Proved right, but not a rule to lock. |
/aelf:review |
Writes a keep, remove, or lock checklist, then applies your verdicts. | Weekly cleanup. |
/aelf:retire <id> |
Hides a belief from retrieval until /aelf:restore. |
Wrong or outdated. |
/aelf:wonder <topic> |
Stores research on a topic as speculative beliefs. | The store has a gap. |
/aelf:reason <query> |
Walks the graph and reports a verdict and suggested updates. | A structured answer. |
More commands
| Command | Does | Use when |
|---|---|---|
/aelf:setup |
Installs the hooks into your agent. | Install, or broken hooks. |
/aelf:show <id> |
Prints one belief in full with its origin and confidence. | Inspecting one belief. |
/aelf:core |
Lists locked, recurring, and high-confidence beliefs. | Seeing what the store relies on. |
/aelf:feed |
Shows the belief-write log. | Auditing recent writes. |
/aelf:tail |
Streams hook injections per prompt and session start. | Checking injections. |
/aelf:stale |
Lists old beliefs not retrieved recently. | Pruning. |
/aelf:restore <id> |
Brings back a retired belief. | Mistaken retire. |
/aelf:delete <id> |
Deletes a belief permanently. | Retire is not enough. |
/aelf:promote <id> |
Marks an agent-inferred belief as user-validated. | The agent got it right. |
/aelf:speculative |
Lists unlocked beliefs, most-supported first. | Auditing unlocked beliefs. |
/aelf:scope-out <text> |
Hides matching beliefs for this session. | Off-task this session. |
/aelf:category |
Binds belief groups to trigger keywords; injection is off by default. | Task-specific beliefs. |
/aelf:graph <id> |
Emits the graph around a belief as DOT or JSON. | Visualizing links. |
/aelf:introspect |
Shows beliefs by session or project, with confidence and grounding. | Judging captures. |
/aelf:rebuild |
Prints the context block the rebuilder would restore. | Debugging context after compaction. |
/aelf:audit-claude-memory |
Compares locked beliefs with your agent's MEMORY.md index. |
Keeping both consistent. |
/aelf:eval |
Runs the relevance-calibration harness on a --corpus. |
Measuring retrieval quality. |
/aelf:upgrade |
Upgrades to the latest release. | A new version is out. |
/aelf:uninstall |
Removes the hooks and keeps, deletes, or archives the store. uv tool uninstall aelfrice removes the package. |
Removing aelfrice. |
The command reference lists the terminal form of each command, such as aelf lock "...".
Belief types and edges
Every belief has one type. A rule-based classifier types transcript text; /aelf:onboard uses your agent's model by default. Text from /aelf:lock or the commit hook is factual. Locking does not change a belief's type.
| Type | Holds | Assigned when |
|---|---|---|
factual |
A statement about the project or world. | No other rule matches. |
requirement |
A rule that has to hold. | Contains "must", "required", or similar. |
correction |
A fix to something said earlier. | The correction detector matches it. |
preference |
How you like things done. | Contains "I prefer", "always use", or similar. |
speculative |
A phantom: a guess that isn't trusted yet. | /aelf:wonder writes it. |
Edges link a source belief to a target belief. Today, only TEMPORAL_NEXT and DERIVED_FROM are written for every conversation. The commit hook reads the agent's git commit messages and matches only unambiguous phrasings: "is supported by" counts, and "supports" doesn't.
| Edge | Meaning | Written by | Default |
|---|---|---|---|
TEMPORAL_NEXT |
Stored right after the target in the same session. | Transcript ingest, for each new belief; 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; commit hook ("is derived from", "is based on"). | Yes |
RELATES_TO |
Same topic as the target. | /aelf:wonder; commit hook ("relates to", "is related to"). |
When run, or on phrases |
SUPPORTS |
Evidence for the target. | Commit hook ("is supported by"). | Phrase only |
CITES |
Mentions the target. | Commit hook ("cites", "mentions"). | Phrases only |
IMPLEMENTS |
Code implementing the target. | Commit hook ("implements", "is an implementation of", "realizes", "fulfills"). | Phrases only |
TESTS |
Tests the target. | Commit hook ("is a test for", "is test of", "is tested by", "is covered by"). | Phrases only |
CONTRADICTS |
Conflicts with the target. | Ingest relationship detector; commit hook ("contradicts", "disagrees with"). | Detector: off unless [relationship_detector] auto_detect = true. Commit hook: phrases only |
SUPERSEDES |
Replaces the target. | aelf resolve (keeps each contradicting pair's winner); commit hook ("supersedes"). |
When run, or on phrase |
POTENTIALLY_STALE |
Flags an older target as possibly stale. | /aelf:doctor --detect-stale. |
When run |
RESOLVES |
A contradicting pair's winner resolves the loser. | aelf resolve, beside each SUPERSEDES edge (issue #1658). |
When run |
Issue #1653 tracks writing more edges automatically.
Documentation
1 maintainer
Metadata
1 maintainer
Release files for aelfrice 5.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aelfrice-5.2.0.tar.gz | 12.0 MB | With provenance | Details for aelfrice-5.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aelfrice-5.2.0-py3-none-any.whl | Python 3 | none | any | Details for aelfrice-5.2.0-py3-none-any.whl |
Total release size: 13.3 MB
Release files / aelfrice-5.2.0.tar.gz
| Download URL | aelfrice-5.2.0.tar.gz |
|---|---|
| Size | 12.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0d863f93543972607ddd6e23284365d95268cd1d07263a06ae0252fde1188c84
|
|
BLAKE2b-256 checksum How to use checksums |
c1b8ba728e472301437b60f1416493d2c8305e2820eebc193a28cf0d2047702c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.
Transparency logRelease files / aelfrice-5.2.0-py3-none-any.whl
| Download URL | aelfrice-5.2.0-py3-none-any.whl |
|---|---|
| Size | 1.3 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
de888c8956ba2d7a2b74c941a51847126a18b4218c1a7c9309027b091769119f
|
|
BLAKE2b-256 checksum How to use checksums |
65bca6dba4337cf8406726a6cbcde28d15db571201f84de578e4250224df4e3e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.
Transparency logSecurity for aelfrice 5.2.0
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.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for aelfrice-5.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 22, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
