Aletheia

Memory your coding agent can verify.

Every memory carries evidence from your code. Aletheia re-checks it on every recall,

points your agent at the exact lines, and keeps stale facts out of its context.

Quick start · How it works · Results · Reference

The problem

Coding agents forget everything between sessions, so they re-read the same files every time. Memory tools fix the forgetting, but they rank memories by similarity, and an outdated memory looks just as relevant as the fact that replaced it. The agent then builds on something that stopped being true weeks ago. A confidently wrong memory is worse than no memory.

How it works

• Memories carry evidence. Each memory is a claim plus anchors: a function that must still exist, a line that must still match, a file that must still be there.
• Evidence is checked on every recall. The checks are mechanical: no model calls, no embeddings, no network. A memory whose evidence broke is hidden from the agent, and a one-line note says so.
• Moved code is followed. When a Go declaration moves unchanged to another file, its memory comes back as [moved] with the new place instead of going stale.
• Recall points at lines. A pointer such as builtin_test.go:263 is computed from the files right now, so the agent opens the right lines instead of searching for them.
• Maps write themselves. When the agent stops, Aletheia reads the session transcript and records which files the task changed. The next task of the same kind starts there, and the agent spends no turns writing it down.
• Nothing is deleted. Replaced memories are superseded and long-stale ones archived by aletheia lethe (Lethe, the river of forgetting).

Quick start

1. Install it in whichever way suits you. Every option gives you the same single binary:

npm install -g @firatmio/aletheia                             # Node 18+, any OS

go install github.com/firatmio/aletheia/cmd/aletheia@latest # Go 1.24+ scoop bucket add firatmio https://github.com/firatmio/scoop-bucket; scoop install aletheia # Windows brew install --cask firatmio/tap/aletheia # macOS, Linux

Prebuilt archives for Linux, macOS and Windows are on the releases page.

2. Connect your agent.

*Claude Code, with the plugin (recommended).* It brings the MCP server and both hooks. /aletheia:setup then initializes the project:

/plugin marketplace add firatmio/aletheia

/plugin install aletheia@aletheia /aletheia:setup

*Claude Code, without the plugin.* Set up the project and add the two hooks yourself. Recall then happens on every prompt and costs the agent nothing:

cd your-project

aletheia init --agents --claude-hooks # .aletheia/, usage notes in CLAUDE.md and AGENTS.md, hooks in .claude/settings.json aletheia hook --dry-run # what an agent would get (add a prompt to try one); changes nothing

Run --claude-hooks yourself. Agents are usually not allowed to change their own hooks, and that is by design. Don't add these hooks if the plugin is installed: it brings the same two. init notices the plugin and says so. To edit the file by hand instead, use this:

{

"hooks": { "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "aletheia hook" }] }], "Stop": [{ "hooks": [{ "type": "command", "command": "aletheia hook" }] }] } }

*Any other agent.* Cursor, VS Code, Claude Desktop and Codex connect over MCP; agents without MCP use the CLI. See Other agents below. An MCP client configured with npx needs no install at all: {"command": "npx", "args": ["-y", "@firatmio/aletheia", "serve"]}.

An agent can also do the setup itself from the agent guide. It hands the hook step to you as that single command.

Memories live in .aletheia/memories/*.md as plain Markdown. Commit them and your team, and every agent, shares one memory that verifies itself on each machine.

Upgrading: npm update -g @firatmio/aletheia, scoop update aletheia or brew upgrade --cask aletheia. With Go, run the same go install again. Update the plugin with claude plugin update aletheia@aletheia.

• Which version runs: the hooks use the new binary right away. The MCP server keeps the old one until the agent restarts.
• With `go install` on Windows, a running agent keeps aletheia.exe open through the MCP server, so the install fails with "file in use". Quit the agent first, or move the old binary aside, which Windows allows for a running exe.

This works on every upgrade. It removes old copies that are no longer in use, and the random name never collides with one that is still running:

$bin = "$(go env GOPATH)\bin"

Remove-Item "$bin\aletheia-old*.exe" -ErrorAction SilentlyContinue Rename-Item "$bin\aletheia.exe" "aletheia-old-$(Get-Random).exe" go install github.com/firatmio/aletheia/cmd/aletheia@latest

Results

We measured with headless Claude Code (Opus 5.5) on real repositories. Each task ran with and without Aletheia, and the same hidden acceptance tests judged success.

Aletheia pays off where finding the right place is expensive, in mid-size and larger codebases, and most when the same kind of change comes back. Expect the mixed figure for everyday work. On a small package that an agent reads in one or two calls there is little to save. The method, the raw numbers and what did not work are in docs/dogfood-4.2.md.

Reference

Anchors

• Use symbol for claims about one declaration and contains for one thing in a file. Use file only when any change should trigger a re-check.
• Recall shows where symbol and contains evidence is right now, e.g. (store.go:15-21). Go declarations get their full range from go/parser. In other languages a symbol anchor finds the declaring line by its keyword (function, class, def, fn and the like); it is not sealed, so it cannot follow a move.
• Moved code. A Go symbol anchor is sealed with a fingerprint of the declaration (symbol:store.go::Store.Get@3f9a…). The fingerprint ignores comments and layout.
• Edits in place: they never stale the anchor. If the declaration is still in its file, the fingerprint is not even consulted.
• A moved declaration: if the declaration leaves its file, Aletheia searches the project for it. When exactly one declaration with that name has the same fingerprint, the memory comes back as [moved: old.go → new.go] with the new lines, and verify --reseal records the new path.
• Anything less certain stays stale and hidden: the code changed on the way, several copies match, or the claim names the old file.
• `contains` anchors in Go code: when one matches inside a single declaration, remember adds a sealed symbol anchor for that declaration. The contains anchor then moves with it, but only if its pattern still matches inside that declaration at the new place.
• In a contains pattern, a run of spaces matches any run of spaces or tabs, so reformatting does not stale it.
• Files named in a claim get an exists: anchor automatically.
• Leave paths to the anchors: say what the code does ("Tokens are issued by IssueToken"), not where it is. A claim that names its symbol's file stays stale when the code moves, and remember says so when you save one.
• remember warns when a contains anchor only matches comments, since a comment can stay while the code changes.
• A memory without anchors comes back as [?], ranked below verified facts, and expires after 90 days unless re-confirmed.

When a memory goes stale, re-check the claim, then:

aletheia verify 3f9a1c --reseal                                   # still true: refresh the evidence

aletheia remember "…new claim…" --anchor … --supersedes 3f9a1c # changed: replace it

--reseal refuses when a contains, exists or symbol anchor no longer holds, so a false claim cannot be quietly blessed.

Code map

aletheia map " " lists the files most relevant to a topic, each with its key declarations and their current lines:

optimizer/fold.go: fold.Visit 15-311, fold 10-13, toFloat 329-335

builtin/builtin.go: