aelfrice MCP server
Commit Nov 15, 2026Provides AI coding agents with a local Bayesian memory that learns from user feedback and project context to maintain persistent beliefs.
Also known as robotrocketscience/aelfrice
- Stars
- 9
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- MIT
What is aelfrice MCP?
aelfrice provides AI coding agents with a local Bayesian memory that learns from user feedback and project context to maintain persistent beliefs.
Summary generated from the project's README
About aelfrice MCP server
aelfrice provides AI coding agents with a local Bayesian memory system designed to maintain persistent knowledge across different sessions. It functions by storing sentences from user prompts as beliefs, which include facts, preferences, requirements, or corrections. This memory is stored locally using a SQLite database, meaning it requires no external accounts, telemetry, or LLM API keys for its retrieval process.
Developers can use the tool with the Claude CLI or Codex to ensure agents do not forget specific project rules or user corrections. The system uses an entity index and BM25 for retrieval, automatically injecting relevant context into the agent's prompt window. Users can manage these beliefs using specific commands like /aelf:lock to establish ground truth or /aelf:onboard to scan existing project documentation and docstrings. This setup allows an agent to learn from commit messages and user feedback, building a confidence score for every stored statement.
What you can do with it
- 1Enforce permanent coding rulesA developer can ensure an agent always follows a specific constraint by locking a belief as ground truth.
- 2Onboard new projects quicklyYou can instruct the agent to scan a directory to ingest existing documentation and project context.
- 3Maintain context from commit historyThe system can automatically learn project changes by reading phrases in git commit messages.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablerobotrocketscience/aelfrice is public and reachablegithub.com/robotrocketscience/aelfrice ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-15github.com/robotrocketscience/aelfrice ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubaelfrice
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. A belief is one statement that aelfrice has stored.
- aelfrice stores sentences from your prompts as beliefs. After each commit, it also stores the words on each side of a phrase such as "X supersedes Y" in the commit message. A message with no such phrase adds nothing.
/aelf:onboardadds your docs, docstrings, and recent commit subjects. - By default, 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
Each belief records 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, with code blocks removed. A sentence keeps its inline code and URLs, so you can search for a command or a link, but they don't affect whether aelfrice stores the sentence or which type it gets. It skips noise, hedged ideas such as "maybe we could", sentences that end in a question mark, sentences under 10 characters once their inline code and URLs are removed, and the model's replies. So a search can't find Use `widget.py`!. A URL with a query string or an @, inline code with an = or a credential word such as token: or bearer, and either one with a known key shape or a long random string, stay removed. That isn't a general secret scanner: see the privacy document.
/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
aelfrice works with the claude CLI and Codex. You install it once on each machine, then onboard each project.
Install on your machine
Run these commands in a terminal, from any folder:
-
Install uv.
-
Install aelfrice:
uv tool install aelfriceIf uv warns that a folder isn't on your
PATH, runuv tool update-shell, then open a new terminal. -
Connect aelfrice to your agent:
aelf setupThis adds the hooks and
/aelf:commands for every project on the machine. On Codex, runaelf setup --host codexinstead, then trust the hooks with/hooks. Codex uses$aelf-*in place of/aelf:.
To have your agent run these steps, paste this prompt into it, then exit and start a new session:
Install aelfrice from github.com/robotrocketscience/aelfrice for all my projects, following its README, and verify the install with aelf doctor.
Onboard a project
-
Start your agent in the project's folder. If the agent was already open before setup, exit it first so that it loads the new commands.
cd ~/projects/my-app claude -
In the agent, scan the project. The
.means the current folder./aelf:onboard .On Codex, run
$aelf-onboard .instead. The command asks which model to use and shows what each costs, then shows the estimated time before it starts. Choose the low-cost model, which is the default and the one the command recommends. The scan uses your agent's existing plan and needs no API key. To scan without a model, add--no-subagents. -
Lock your first belief:
/aelf:lock never push directly to main
aelfrice then runs without further commands. To check the install, run /aelf:doctor (aelf doctor --host codex on Codex). The installation guide covers every option.
Each git repository keeps its own store, in its .git folder. Folders outside git share one store at ~/.aelfrice/memory.db. On the claude CLI, aelf setup adds the git hook that reads commit messages only to the repository you run it in, so run aelf setup once in each project where you want that. Codex doesn't get this hook.
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 the store in use, the rule that chose it, and counts of beliefs, threads, locks, feedback, and phantoms. | 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. |
| 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 message of each new commit and matches a fixed list of phrasings: "is supported by" counts, and "supports" doesn't. A phrasing counts only in lowercase, so "supersedes" counts, and "SUPERSEDES" doesn't. It also needs a word on each side of it on the same line. A side made only of function words stores nothing for that match: determiners, pronouns, relative words, quantifiers, conjunctions, prepositions, auxiliaries and modals, negators, and adverbs such as "also" and "just". A word of two or more letters in all capitals, such as "IT" or "WHO", counts as a name, so it stores. A capitalized word that matches one of these, such as the code names "None" and "Any" or the name "Will", counts as a function word, so it doesn't store. A word with a hyphen or underscore inside it, such as "one-shot" or "all_of", counts as one word and stores. A side can't start after an apostrophe, so "it's" doesn't store "s". On a match, aelfrice stores up to six words from each side, from that line only, as a belief, with an edge between them. Those words might not form a complete phrase, such as "the old", and a phrase that wraps to the next line is cut at the line break. The edge also keeps about 80 characters of the message, which can include other lines. From a message with no match, aelfrice stores nothing.
| 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
aelfrice MCP questions
How does aelfrice store information?
It stores sentences from your prompts as beliefs, including specific phrases from commit messages like 'X supersedes Y', and can onboard documentation and docstrings.
Does aelfrice require an internet connection or external API for retrieval?
No, retrieval uses an entity index and BM25 over a local SQLite database and requires no account, telemetry, embeddings, or LLM.
How can I make a belief a permanent rule?
You can turn a belief into ground truth by locking it using the /aelf:lock command.