ἀλήθεια · a-lethe · "un-forgetting"

One memory for every AI coding tool.

Aletheia (aletheia-mem) is a free, local memory and rules hub for Claude Code, Codex CLI, Cursor, Gemini CLI and other AI coding tools. They read and write one SQLite store over MCP, REST or a CLI. Write your rules once and sync them into each tool's own instruction file. Export everything and move on whenever you like.

Quick start Read the docs View on GitHub

What it does

A small local server, a CLI and an MCP server over one SQLite file. No account, no telemetry, loopback only.

Memory

Search, filter, pin, edit and delete. Observations, summaries, prompts and notes, with full-text search and optional local embeddings. Hooks capture sessions in Claude Code, Command Code, Codex CLI, Cursor, Gemini CLI and Windsurf.

Rules, written once

Sync one rule set into CLAUDE.md, AGENTS.md, GEMINI.md, Cursor, Windsurf, Copilot and Aider files. A managed block, so your own text is never touched. Preview and backup first.

Connect tools

Detect installed tools and write the MCP config for each, with a preview and a backup before any write.

Easy to leave

Export a versioned bundle or Markdown. Import a bundle, or import from claude-mem (read-only, repeatable). Importing twice does not duplicate.

Private by default

Secrets and <private> blocks are removed before anything is stored. Optional LLM features are off until you choose a provider.

A dashboard in plain words

Home shows, per project, what Aletheia knows, which rules apply and which tools are connected, with hints and examples. Activity, Knowledge, Rules and Connections go deeper.

Measured, not claimed

Retrieval on LoCoMo (1,536 questions with gold evidence) against claude-mem 15.2.0 as shipped. Retrieval only: answer accuracy is not measured yet.

Run	Questions	Recall@5	MRR	ms/query
claude-mem 15.2.0 (as shipped), raw turns — measured-by-us	1,536	36.0%	0.285	p50 1,699 ms, p95 2,824 ms (idle, 40 queries)
Raw turns, all 10 conversations	1,536	57.4%	0.497	3.72
Dataset facts, all 10	1,536	64.8%	0.591	5.53
Dataset facts, 3 conversations	383	67.4%	0.620	5.80
Dataset facts, 3 conversations, + rerank	383	73.9%	0.686	251.16
Dataset facts, all 10, + rerank	1,536	72.3%	0.680	646.19
Our rule-extracted facts, all 10	1,536	57.7%	0.492	4.94

Retrieval only: Recall@5 asks whether the gold evidence is in the top five results. It is not answer accuracy. Every row is measured-by-us on the same LoCoMo questions; no vendor-claimed benchmark number is in this table. Generated from bench/results/2026-10-26/ (bench/claude-mem-baseline.mjs, raw-turns.json (hybrid), dataset-facts.json (hybrid+facts), dataset-facts-3-rerank.json (hybrid+facts), dataset-facts-3-rerank.json (hybrid+facts+rerank), dataset-facts-rerank.json (hybrid+facts+rerank), our-facts-rules.json (hybrid+facts)); re-run with bun scripts/compare-bench.mjs.

Read this before comparing. Recall@5 is retrieval, not answer accuracy. The gap is real but not 2× when both sides see the same extracted facts. At 50,000 synthetic rows, keyword search p95 is 32.7 ms project-scoped and 58.6 ms across all projects (measured-by-us, Linux). A seeded gate on 50,000 rows holds recall@5 at 0.90 with p95 about 7.8 ms (bun bench/gate.mjs). Method, baselines and the raw result files are in bench/results.

Which tools it connects to

Aletheia is tool-neutral by design: open MCP protocol, a plain REST API, a CLI, and each tool's own instruction file. This is what has actually been checked.

Tool	Level	Verification	Hook events installed
claude-code	full	MCP connection 2.1.312 on 2026-10-27; hooks ran in real sessions over two days of use; one user on one machine	SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd
command-code	full	MCP connection 1.88.1 on 2026-10-27; hooks ran in one short session; one user on one machine	SessionStart, PostToolUse, Stop
cursor	full	config written from docs, not tested on a real install	sessionStart, beforeSubmitPrompt, postToolUse, afterAgentResponse, stop, sessionEnd
codex	full	MCP connection 0.165.0 on 2026-10-29; hooks ran in one interactive session (reviewed once with /hooks); one user on one machine	SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd
gemini-cli	full	config written from docs, not tested on a real install	SessionStart, BeforeAgent, AfterTool, AfterAgent, SessionEnd
windsurf	full	config written from docs, not tested on a real install	pre_user_prompt, post_run_command, post_write_code, post_cascade_response
opencode	mcp+rules	MCP connection 1.18.33 on 2026-10-27; hooks not run	none (MCP and rules only)

Generated from src/hub/install.mjs via aletheia install --list. A row says MCP connection when the real CLI listed the server. Hooks have run in real sessions of Claude Code (two days of use), Command Code (one short session) and Codex CLI (one interactive session), one user on one machine; Cursor, Gemini CLI, Windsurf and OpenCode hooks have not run.

Documentation

Guides for each tool, concepts, a full CLI, MCP and REST reference, and honest comparisons.

Introduction

What Aletheia is, how it works and what it does not do.

Claude Code memory

Install the hooks, MCP entry and rules block, and check them.

Tools overview

Codex, Cursor, Gemini CLI, Windsurf, OpenCode and what is verified for each.

Aletheia vs claude-mem

A fair comparison with measured numbers and where claude-mem is ahead.

Migrate from claude-mem

Import your memory read-only and run both side by side.

CLI and MCP reference

Every command, every MCP tool, every setting.

Quick start

Needs Bun 1.1 or newer. No runtime dependencies.

npm install -g aletheia-mem
aletheia-server                       # http://127.0.0.1:37790

aletheia install claude-code          # dry run: prints every file it would change
aletheia install claude-code --write  # MCP entry, hooks and rules block, with backups
aletheia save "Deploys need Node 20.19.6" --project my-app --pin
aletheia search "node version"
aletheia rules add "Run the tests before saying a task is done"
aletheia import claude-mem            # optional: bring claude-mem memory in (read-only)

Full reference: Quickstart · Docs · README

FAQ

What is Aletheia?

Aletheia (npm package aletheia-mem) is a free, local memory and rules hub for AI coding tools. Hooks in tools such as Claude Code capture what happened, secrets are removed, and one SQLite file on your machine keeps it. Any tool reads it over MCP, REST or a command line.

How do I give Claude Code persistent memory with Aletheia?

Install the package, start the server, then run aletheia install claude-code --write. That writes the MCP server entry, the hooks and the rules block. Hooks have run in real Claude Code sessions over two days of use, one user on one machine.

Is it really free?

Yes. Apache-2.0, no account, no hosted tier, no telemetry. Optional LLM features call the model you configure, and only then.

How is it different from claude-mem?

Both are open source. claude-mem is much larger, with more features and a far bigger community. Aletheia is smaller and tool-neutral: one store for any tool, rules sync to each tool's instruction file, and import from claude-mem.

Does it replace claude-mem?

No. It runs beside it on its own port and never writes to claude-mem's database.

Where is my data?

In ~/.aletheia/hub.db on your machine. Nothing leaves it unless you turn on an LLM provider or share an export.

Can Claude Code, Codex and Cursor share one memory?

Yes, by design: they all read the same local store through MCP, REST or the CLI. Real-tool checks so far cover Claude Code, Command Code and Codex CLI on one machine; Cursor, Gemini CLI and Windsurf are config written from docs, not tested on a real install.

Does it work with my tool?

If your tool speaks MCP or reads an instruction file, probably. Configs are written from documentation and fixture-tested. Only some have been tested on a real install; the tools table on this page says which.