Aletheia

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

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.

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

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

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.

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

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

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:

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.

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