aletheia-mem

<p align="center"><img src="https://raw.githubusercontent.com/mohamed-ashraf-elsaed/aletheia-mem/main/docs/assets/logo.png" alt="Aletheia: a network brain with a stack of memory layers" width="280"></p> <h1 align="center">Aletheia</h1> <p align="center"><strong>A free, local memory and rules hub for AI coding tools.</strong><br>One store on your machine. Any tool reads it over MCP, REST or the CLI.<br>Persistent memory for Claude Code, Codex CLI, Cursor, Gemini CLI, Windsurf and OpenCode: a local, tool-neutral alternative to claude-mem.</p> <div align="center">

<a href="https://alternativeto.net/software/aletheia-mem/about/?utm_source=badge&utm_medium=referral"><img src="https://alternativeto.net/static/badges/badge-compact-color.svg" alt="Aletheia Memory on AlternativeTo" height="44"></a>

Listed in the official MCP Registry, Glama, mcpservers.org, TensorBlock awesome-mcp-servers and AlternativeTo.

</div>

Install and run. Bun 1.1 or newer is required; the CLI runs on Bun, not Node.

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

<p align="center"><img src="https://raw.githubusercontent.com/mohamed-ashraf-elsaed/aletheia-mem/main/docs/screenshots/home-projects-light.webp" alt="The Home page: your projects, your rules and how to start, in plain words (demo data)" width="48%"> <img src="https://raw.githubusercontent.com/mohamed-ashraf-elsaed/aletheia-mem/main/docs/screenshots/home-project-light.webp" alt="One project on the Home page: what Aletheia knows, with a Hide button, and the rules for it (demo data)" width="48%"></p> <p align="center"><a href="https://aletheia.mohamedashrafelsaed.com/">Docs site</a> · <a href="https://mohamedashrafelsaed.com/projects/aletheia/">Project page</a> · <a href="https://github.com/mohamed-ashraf-elsaed/aletheia-mem/blob/main/docs/06-frontend.md">Frontend guide</a> · <a href="https://github.com/mohamed-ashraf-elsaed/aletheia-mem/blob/main/CHANGELOG.md">Changelog</a> · <a href="https://github.com/mohamed-ashraf-elsaed/aletheia-mem/issues">Issues</a></p>

Status: alpha. The memory engine and the installers work in tests. The real Claude Code, Command Code, Codex CLI and OpenCode listed the generated MCP config. Hooks have run in real sessions of Claude Code (two days of use), Command Code (one short session) and Codex CLI (one interactive session), all on the author's machine and one user, with secrets redacted and no leaks found by the checker. No hook has run inside Cursor, Gemini CLI, Windsurf or OpenCode yet, and answer accuracy is not measured. CI runs the test suite on Linux, macOS and Windows. On Windows, two hook checks (Windsurf and Gemini CLI) are skipped and no real tool was tried there, so Windows is tested in CI only.

<!-- claims:begin -->

1,533 tests — 0 failures (run bun test).

<!-- claims:end -->

English · 中文 · Español · Português (Brasil) · 日本語 · Deutsch · Français · 한국어 · हिन्दी · العربية · Русский. Machine translations live in docs/i18n/; English is canonical. No translation has had native review.

What it is

Aletheia is a free, local memory and rules hub for AI coding tools. One SQLite store is read by any tool over MCP, REST or the CLI, and your rules are written into each tool's own instruction file. It is built to give Claude Code, Codex CLI, Cursor, Gemini CLI, Windsurf and OpenCode one shared, persistent memory; the sections below say which of them has been checked on a real install.

Every coding agent forgets between sessions, and each one remembers differently. Aletheia keeps the memory and the rules once, on your machine, and lets each tool read them in the format it already understands. There is no account, no telemetry and no network call unless you configure a model provider. It listens on loopback only.

Install in three commands

git clone https://github.com/mohamed-ashraf-elsaed/aletheia-mem
cd aletheia-mem
bun bin/aletheia-server.mjs

Open http://127.0.0.1:37790. Needs Bun 1.1 or newer. To install the published package instead, run npm install -g aletheia-mem, then start it with aletheia-server. There are no runtime dependencies to install.

The first screen has five tabs: Home (start here: pick a project and see what Aletheia knows about it, its rules and its connected tools, in plain words), Activity (Aletheia's own view of the requests and sessions your tools worked on), Knowledge (search, edit, pin, hide, export), Rules (write once and sync) and Connections (installer status and audit).

How capture works

aletheia install claude-code --write
aletheia install cursor --write
aletheia install --list          # capability level and verification per tool

Without --write the command is a dry run. It prints every file it would change and writes nothing. Each changed file gets a timestamped backup. Hooks call the installed aletheia command, redact secrets and <private> blocks before storing, spool to disk if the database is unavailable, and always exit 0 so they never block the host. Compression is queued, not run inside the hook. Details and the exact hook list per host: docs/25.

Which tools it connects to

Aletheia does not depend on any one tool. It speaks MCP (stdio and HTTP), a plain REST API and a CLI, and it writes the instruction file each tool already reads. What has and has not been checked:

| Check | Result | |---|---| | MCP server against the official MCP SDK client | Passes (protocol versions 2025-11-25 to 2024-11-05) | | Config formats for Claude Code, Command Code, Cursor, Codex CLI, Gemini CLI, Windsurf, OpenCode | Written from official docs fetched 2026-10-26 and tested against fixtures. The real CLI listed the aletheia MCP server for Claude Code, Command Code, Codex CLI and OpenCode on 2026-10-27; Cursor, Gemini CLI and Windsurf are Not tested on a real install. | | Claude Desktop MCP config | Documented and merge-tested against a fixture; not opened in the app | | Rules files: CLAUDE.md, AGENTS.md, GEMINI.md, .cursor/rules/*.mdc, .windsurf/rules/*.md, Copilot, Aider | Written and tested in temp folders (docs/verification/rules-targets.md) | | Any of the above on a real install of that tool | MCP config was read back by the real CLI for Claude Code, Command Code, Codex CLI and OpenCode on 2026-10-27. Hooks ran in real sessions of Claude Code (two days of use), Command Code (one short session) and Codex CLI (one interactive session), all on the author's machine and one user (prompts and tool events captured, secrets redacted, no leaks). No hook ran inside Cursor, Gemini CLI, Windsurf or OpenCode. | | Automatic capture through a tool's hooks | Built for Claude Code, Command Code, Cursor, Codex CLI, Gemini CLI and Windsurf. Each installed hook command is exercised end to end in a temp HOME with a recorded payload. Hooks ran 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. OpenCode is MCP+rules. |

<!-- gen:tools -->

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

<!-- /gen:tools -->

Measured numbers

On LoCoMo, claude-mem 15.2.0 as shipped vs this project. These are retrieval numbers, not answer accuracy.

<!-- gen:bench -->

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