Aletheia

io.github.firatmioPublished by GitHub account firatmiov0.1.1Updated Oct 31, 2026

Project memory for coding agents whose memories carry code evidence, re-checked on every recall.

The publisher's own server: 4words

VerifiedSTDIODesktop onlyKnowledge & Memory Developer Tools

Server details

Identifier: io.github.firatmio/aletheia
Transport: STDIO
Runtime: Desktop only
Trust: Verified
Published: Oct 24, 2026

Security note

MCP servers receive tool arguments from a conversation and may perform external actions. Review what a server can do before you enable it, and give it only the access it needs.

The registry verified the GitHub account firatmio for this listing. That does not show the account is the product's maker.

SourceWeft's checks cover whether the listing is complete and the endpoint answered; they do not review the server's code or what its tools do.

Add a badge to your README

Show readers this MCP server is listed on SourceWeft. The badge links to this page.

[![Listed on SourceWeft](https://sourceweft.com/badge/mcp/io.github.firatmio%2Faletheia.svg)](https://sourceweft.com/mcp/io.github.firatmio%2Faletheia?utm_source=readme&utm_medium=badge)

Overview

AI-generated overview

Aletheia gives coding agents a project memory whose claims carry code anchors, re-checked against the files on every recall so stale facts stay hidden.

What you can do: Recall project memories before exploring code, with each line marked verified, moved or unanchored and pointing at current file lines
Save durable facts with evidence anchors (symbol, contains, exists, file) in one or several calls
Read a single memory by id with the status of each anchor
Re-check anchors for all memories or one id, resealing a memory that still holds or superseding one that changed
When to use it: Useful for coding agents working in mid-size or larger repositories that keep re-reading the same files between sessions and need memories that do not silently go out of date. Less valuable on small packages an agent reads in one or two calls.
Requirements: Runs as a local stdio process, either from a global install of the npm package (Node 18+) or via npx, or as a Go binary. The project needs an .aletheia directory created by the init command, and the server is pointed at it with a directory argument or the ALETHEIA_DIR variable. No accounts, API keys or network access are needed.

Before you install

The remember tool writes memory files into the project's .aletheia directory, and the optional hooks read the prompt and session transcript on the machine, keeping a shortened copy of the prompt in .aletheia. Memories are treated as data, not instructions, but they are plain Markdown files that can be edited or committed, so review them before sharing.

Installation

In SourceWeft

Open Aletheia in the dashboard and add it to a workspace.
Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[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.

[Release] [npm] [MCP Registry: io.github.firatmio/aletheia] [License: Apache-2.0] [Go 1.24+] [Zero dependencies]

[Aletheia MCP server on Glama] [M8ven Score]

Quick start · How it works · Results · Reference

[A memory is saved with evidence and recalled as [ok] with its line. The file is moved and recall shows it as [moved] at its new place. The value is changed and recall hides the memory; verify says why: MaxDiscount changed.]

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

[On every prompt Aletheia adds verified memories and a code map with line pointers; the agent reads the exact lines; when it stops, Aletheia records which files the task changed.]

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:

bash

npm install -g @firatmio/aletheia                             # Node 18+, any OSgo install github.com/firatmio/aletheia/cmd/aletheia@latest   # Go 1.24+scoop bucket add firatmio https://github.com/firatmio/scoop-bucket; scoop install aletheia   # Windowsbrew install --cask firatmio/tap/aletheia                     # macOS, Linux

npm install -g @firatmio/aletheia                             # Node 18+, any OSgo install github.com/firatmio/aletheia/cmd/aletheia@latest   # Go 1.24+scoop bucket add firatmio https://github.com/firatmio/scoop-bucket; scoop install aletheia   # Windowsbrew 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:

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:

bash

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

cd your-projectaletheia init --agents --claude-hooks   # .aletheia/, usage notes in CLAUDE.md and AGENTS.md, hooks in .claude/settings.jsonaletheia 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:

json

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

{  "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:

powershell

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

$bin = "$(go env GOPATH)\bin"Remove-Item "$bin\aletheia-old*.exe" -ErrorAction SilentlyContinueRename-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.

Repository	Tasks	Cost	Also	Tasks passed
gohugoio/hugo, a large site generator (233k lines of Go)	14 tasks of five kinds, one run each	−15%: −22% on seven tasks of one kind, −7% on a mix	input tokens −27%, turns −21%	14/14, same as without
expr-lang/expr, a mid-size expression language	7 tasks, two runs	−9% in both runs	code read before the first edit −48%	14/14, same as without
go-chi/chi, a small, tidy router	7 small tasks, two runs	+5% and −5%: break-even		14/14, same as without

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

Anchor	Holds while	Example
`symbol:PATH::NAME`	the file still declares that function, method (`Type.Method`), type, var or const	`symbol:store.go::Store.Get`
`contains:PATH::REGEX`	the file still matches the regular expression	`contains:go.mod::^go 1\.23$`
`exists:PATH`	the path still exists	`exists:src/auth`
`file:PATH`	the file's content is unchanged (hash sealed when saved)	`file:go.mod`

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 <id> --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:

bash

aletheia verify 3f9a1c --reseal                                   # still true: refresh the evidencealetheia remember "…new claim…" --anchor … --supersedes 3f9a1c   # changed: replace it

aletheia verify 3f9a1c --reseal                                   # still true: refresh the evidencealetheia 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 "<topic>" 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-335builtin/builtin.go: Builtins 35-1081, Index 18

optimizer/fold.go: fold.Visit 15-311, fold 10-13, toFloat 329-335builtin/builtin.go: Builtins 35-1081, Index 18

Files are ranked first, as in Aider's repo map, by how well their path and declaration names match the topic. Hidden, dependency and generated files are skipped. For a question about building, testing or shipping, and for the overview without a topic, the map starts with the build files: build and CI: go.mod, Makefile, scripts/, .github/workflows/ci.yml. The hook sends a map with the first prompt of a session, sized to the project: none under 25 source files, then 300 or 600 tokens (--map-budget N overrides it).

Other agents: Claude Desktop, VS Code, Cursor, Codex, Aider

Aletheia speaks MCP over stdio with four tools (recall, remember, get, verify) and works as a plain CLI, so any agent that can run a shell command can use it.

json

{  "mcpServers": {    "aletheia": { "command": "aletheia", "args": ["serve", "--dir", "/absolute/path/to/your-project"] }  }}

{  "mcpServers": {    "aletheia": { "command": "aletheia", "args": ["serve", "--dir", "/absolute/path/to/your-project"] }  }}

Without a global install, use "command": "npx", "args": ["-y", "@firatmio/aletheia", "serve", "--dir", "…"]. The server finds .aletheia/ from --dir, or from the directory the client starts it in. In a project without one, the tools answer with how to set it up rather than failing, and start working as soon as aletheia init has run.

VS Code (.vscode/mcp.json): use "servers" instead of "mcpServers", and ${workspaceFolder} as the directory.
Claude Code: use the plugin from the quick start. It adds the hooks too, and they matter more than the tools, because Claude Code loads MCP tool descriptions on demand.
Agents without MCP (Aider, custom agents): aletheia init --agents writes a short block to AGENTS.md that teaches the agent to call the CLI. Codex reads AGENTS.md too, so it gets the same notes alongside the MCP tools. Add --json to any read command for machine-readable output.

A memory file

markdown

---id: "3f9a1c"claim: "Auth tokens are issued by IssueToken, HS256 with a 15 minute expiry"confidence: 0.8status: "active"source: "claude-code"created: "2026-10-21T09:12:44Z"updated: "2026-10-21T09:12:44Z"tags:  - "auth"anchors:  - "symbol:src/auth/jwt.go::IssueToken@7370a7fe3669256c"  - "contains:src/auth/jwt.go::jwt\\.SigningMethodHS256"---Refresh tokens are handled separately, by RefreshToken.

---id: "3f9a1c"claim: "Auth tokens are issued by IssueToken, HS256 with a 15 minute expiry"confidence: 0.8status: "active"source: "claude-code"created: "2026-10-21T09:12:44Z"updated: "2026-10-21T09:12:44Z"tags:  - "auth"anchors:  - "symbol:src/auth/jwt.go::IssueToken@7370a7fe3669256c"  - "contains:src/auth/jwt.go::jwt\\.SigningMethodHS256"---Refresh tokens are handled separately, by RefreshToken.

The @7370a7fe3669256c suffix is the sealed fingerprint that lets the memory follow IssueToken if it moves.

Edit memories by hand, review them in pull requests, grep them. They are just files.

CLI

text

aletheia init [dir] [--agents] [--claude-hooks]aletheia remember <claim> [--anchor SPEC]... [--body TEXT|-] [--tag T]... [--ttl 30d]                  [--confidence 0.8] [--supersedes ID]... [--source NAME] [--force]aletheia remember - [--source NAME] [--force]            # several at once: one JSON object per line on stdinaletheia recall [query] [--budget N] [--limit N] [--full] [--stale] [--tag T] [--session ID] [--json]aletheia get <id> [--json]aletheia verify [id] [--reseal] [--ttl 30d] [--json]   # exits 1 if anything is stale (CI-friendly)aletheia map [topic] [--budget 600]aletheia hook [--budget N] [--map-budget N] [--dry-run [prompt]]   # Claude Code hook; every command takes --helpaletheia lethe [--days 30] [--apply] [--json]            # archive superseded and long-stale memoriesaletheia stats [--json]aletheia serve [--dir DIR]                               # MCP server on stdioaletheia version

aletheia init [dir] [--agents] [--claude-hooks]aletheia remember <claim> [--anchor SPEC]... [--body TEXT|-] [--tag T]... [--ttl 30d]                  [--confidence 0.8] [--supersedes ID]... [--source NAME] [--force]aletheia remember - [--source NAME] [--force]            # several at once: one JSON object per line on stdinaletheia recall [query] [--budget N] [--limit N] [--full] [--stale] [--tag T] [--session ID] [--json]aletheia get <id> [--json]aletheia verify [id] [--reseal] [--ttl 30d] [--json]   # exits 1 if anything is stale (CI-friendly)aletheia map [topic] [--budget 600]aletheia hook [--budget N] [--map-budget N] [--dry-run [prompt]]   # Claude Code hook; every command takes --helpaletheia lethe [--days 30] [--apply] [--json]            # archive superseded and long-stale memoriesaletheia stats [--json]aletheia serve [--dir DIR]                               # MCP server on stdioaletheia version

Every command takes --help, and --dir DIR (or ALETHEIA_DIR) to point at a project from elsewhere.

remember exits with code 3 when the claim duplicates or closely matches an existing memory, and names it so the agent can --supersedes it instead.

remember - saves several memories in one call. Each stdin line is a JSON object with the MCP tool's keys, and each memory is saved on its own:

bash

aletheia remember - <<'EOF'{"claim": "Builtins are registered in builtin/registry.go", "anchors": ["symbol:builtin/registry.go::Builtins"]}{"claim": "go.mod targets Go 1.18", "anchors": ["contains:go.mod::^go 1\\.18$"], "tags": ["toolchain"]}EOF

aletheia remember - <<'EOF'{"claim": "Builtins are registered in builtin/registry.go", "anchors": ["symbol:builtin/registry.go::Builtins"]}{"claim": "go.mod targets Go 1.18", "anchors": ["contains:go.mod::^go 1\\.18$"], "tags": ["toolchain"]}EOF

It prints one result per line, in order. It exits 0 when all are saved, 3 when the only failures are conflicts, and 1 otherwise. A regex whose \\ became \ on the way through the shell (1\.18) is still accepted. The MCP remember tool takes the same objects as memories.

Safety

Never executes anything. Anchors only read files; there is no "run this command to verify" anchor.
Stays inside the project. Anchor paths are relative and cannot escape the root, including through symlinks.
Memories are data, not instructions. The MCP server tells agents so, and the CLAUDE.md / AGENTS.md block repeats it.
No network, no telemetry, no dependencies. A single static binary using only the Go standard library. The one program it starts is git check-ignore, during init, to see whether CLAUDE.md is ignored.
Privacy: Aletheia collects nothing. The hooks read the prompt and the session transcript on your machine, and the map memories keep a shortened copy of the prompt in .aletheia/. See the privacy policy.

Roadmap

Evidence-anchored memories, checked on every recall
Recall hook, live line pointers, code map, task maps from the Stop hook
Benchmark harness with paired runs on real repositories
Moved Go code followed by fingerprint ([moved])
Prebuilt binaries, npm, Homebrew and Scoop; a Claude Code plugin; listed in the MCP Registry
Sealed symbol anchors, and [moved], beyond Go: TypeScript/JavaScript and Python first
aletheia doctor: find anchors that keep going stale and suggest sturdier ones
Longer benchmarks with more repositories and repeated kinds of change
Global, cross-project memory for personal preferences

What changed in each release is in CHANGELOG.md.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md and the code of conduct. If Aletheia misled your agent, the "An agent was misled" issue form is the most useful report you can send. Report security problems privately, as SECURITY.md describes.

License

_{ἀ-λήθεια: truth, literally "un-forgetting"}

Source: README.md at commit b7e2be6

Tools

recall

Search project memory before exploring the codebase. Each line: id [ok|?] claim. [ok]=verified against the files now, [?]=unanchored hint, (file:12-40)=where it is now: read those lines. Stale memories are hidden (stale=true shows them).

Parameterstagfullquerystalebudgetsession

remember

Save a durable fact with evidence; several in one call: memories=[{claim,anchors,...}]. anchors: symbol:store.go::Store.Get (a declaration), contains:go.mod::go 1\.23 (regex on the line that proves the claim, not a comment or name), exists:src/auth, file:go.mod (content hash; any edit stales it, avoid on busy files). Anchors must hold now. Absence claims ("no auth"): no anchors, ttl 30d. supersedes: ids of outdated memories to replace. Never store secrets.

Parametersttlbodytagsclaimforceanchorsmemoriesconfidencesupersedes

get

Full memory by id with per-anchor status.

Parametersidrequired

verify

Re-check anchors: all memories, or one id. After confirming a stale memory still holds, call with id and reseal=true. If it no longer holds, use remember with supersedes.

Parametersidttlreseal

Version history

v0.1.1LatestOct 24, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

Reached in the last 30 days25 pts
Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
Tools listedRequired15 pts
DescriptionRequired15 pts
Logo10 pts
Documentation15 pts
License10 pts