Aletheia documentation

Aletheia (aletheia-mem) is a free, local memory and rules hub for AI coding tools. These 49 pages cover installing it, connecting Claude Code, Codex CLI, Cursor, Gemini CLI, Windsurf and OpenCode, how memory and rules work, the CLI, MCP and REST reference, and how it compares with claude-mem and other memory tools. The Markdown in docs/ is canonical.

Search the docs

AI tools can read llms.txt or llms-full.txt. Every page also has a plain Markdown copy at the same address ending in .md.

Get started

Introduction to Aletheia, a local memory hub for AI coding tools — Aletheia (aletheia-mem) is a free, local memory and rules hub that gives AI coding tools persistent memory over MCP, REST and a CLI.
Install Aletheia with npm, git or Docker — Install Aletheia (aletheia-mem) with npm, git or Docker, start the server on port 37790, set up auto-start, update it and remove it. Needs Bun 1.1+.
Quickstart: save, search and recall a memory with Aletheia — A ten-minute path through Aletheia (aletheia-mem): start the server, save and search memories, print session context, add a rule, preview the installer.
How Aletheia works: capture, redact, store, compress, recall — How Aletheia (aletheia-mem) turns hook events into memory: capture, redaction, SQLite storage, queued fact extraction and session-start context.
The Aletheia dashboard: five tabs for memory, rules and tools — A tour of the Aletheia (aletheia-mem) dashboard: what Home, Activity, Knowledge, Rules and Connections show, and what you can change in each.
Aletheia FAQ: memory, privacy, tools and limits — Short answers about Aletheia (aletheia-mem): cost, data location, privacy, which tools it connects to, deleting memory, offline use and its alpha status.

Concepts

Aletheia memory model: memories, facts, episodes and rules — What Aletheia stores in hub.db: memory kinds and types, facts, episodes, entities, rules, project and global scope, pin, dismiss and importance.
Rules: write standing instructions once and sync them to every tool — How Aletheia rules work: scopes, enabled, stale, confirm and retire, the managed block in each tool file, preview, diff, lint, sync and import.
Search: keyword, project scope and optional semantic search — How Aletheia search works: FTS5 keyword search, project scope and --scope all, --explain, optional semantic search, ranking and the agent search pattern.
Session-start context: what a new AI session receives — What the Aletheia session-start block holds: the day-grouped index, legend, fetch hint, token estimate, the context.facts setting and how to shrink it.
Privacy and redaction in Aletheia — What Aletheia stores and where, which secrets it redacts and which it misses, how private blocks work, what can leave your machine, and how to erase data.
33. Facts — Facts are the atomic, declarative pieces of memory that sit under summaries, search and the session-start context. They are extracted from captured memory, never from a model's ...
Aletheia glossary: terms used in the documentation — Plain definitions of the terms used in the Aletheia docs: memory, observation, fact, episode, rule, hook, host, hub, spool, redaction, FTS5, MCP and more.

Connect your tools

Connect AI coding tools to Aletheia: overview and verification status — Which AI coding tools Aletheia connects to, what full and mcp+rules mean, how the dry run works, and what was tested on a real install.
Claude Code memory with Aletheia — Install Aletheia memory in Claude Code: the MCP entry, five hooks and CLAUDE.md rules block it writes, how to verify it, and what was tested.
Command Code memory with Aletheia — Install Aletheia memory in Command Code: the MCP entry, three hooks and AGENTS.md rules block it writes, what it cannot capture, and what was tested.
Codex CLI memory with Aletheia — Install Aletheia memory in Codex CLI: the config.toml MCP entry, five hooks and AGENTS.md rules block it writes, the /hooks review, and what was tested.
Cursor memory with Aletheia — Install Aletheia memory in Cursor: the mcp.json entry, six hooks in hooks.json and the .mdc rules file, with the status that none of it ran in Cursor.
Gemini CLI memory with Aletheia — Install Aletheia memory in Gemini CLI: the settings.json MCP entry and five hooks, the GEMINI.md rules block, and the status that no hook ran.
Windsurf memory with Aletheia — Install Aletheia memory in Windsurf (now documented as Devin Desktop): the MCP entry, four Cascade hooks and rules files, with the status that no hook ran.
OpenCode memory with Aletheia — Connect OpenCode to Aletheia: the opencode.json MCP entry and AGENTS.md rules block it writes, why no hooks are installed, and what was tested.
Claude Desktop and the aletheia MCP server — Claude Desktop speaks MCP over stdio. Aletheia's server is bin/mcp.mjs; one JSON entry under mcpServers is all it needs. No hook and no rules file exist for Claude Desktop, so t...
GitHub Copilot, Aider and any MCP client with Aletheia — Use Aletheia with GitHub Copilot and Aider rules files, any MCP client over stdio, the REST API with curl, and the CLI in scripts and cron.
25. Installers and automatic capture — Status: implemented and validated 2026-10-26. This page records what each installer writes, which hook fields it reads, and what is verified on this machine. Five more hosts and...

Guides

Migrate from claude-mem to Aletheia — Import your claude-mem observations, summaries and prompts into Aletheia, run both side by side, switch the Claude Code hook and roll back.
Write your AI coding rules once and sync them to every tool — Add rules once in Aletheia, preview the change, lint them, and write them into CLAUDE.md, AGENTS.md and other tool files with a backup.
Back up, export and move Aletheia memory between machines — Export Aletheia memory and rules as JSONL or Markdown, copy hub.db safely with its WAL files, import on another machine, and erase with a receipt.
Run Aletheia as a background service (systemd, launchd, Docker) — Generate a systemd user unit or a macOS launchd plist for the Aletheia server, set CPU and memory limits, read logs, upgrade, or run it in Docker.
Model providers: none, Claude CLI, OpenAI-compatible and Ollama — Choose how Aletheia extracts facts: rule-based with no model, the Claude CLI, an OpenAI-compatible API or Ollama, plus env vars and privacy notes.
Troubleshooting Aletheia: port in use, MCP closed, no memories and more — Fix common Aletheia problems: EADDRINUSE, MCP CONNECTION_CLOSED, an old dashboard, E404 on install, missing memories, locked or corrupt database.
29. Aletheia Sync — Status: implemented, 2026-10-26. This page describes the code that exists.
30. The private remote MCP endpoint — Status: implemented, 2026-10-26. This page describes the code that exists and is tested by test/remote-mcp.test.mjs.
31. Team mode — Status: implemented and tested, 2026-10-26. This page describes what the code does. It does not claim SSO, SCIM, compliance certificates or an SLA; none of those are built.
32. Requests, goals, story and economics — Status: implemented, 2026-10-27. This page describes the code that exists: src/hub/requests.mjs, goals-rollup.mjs, artifacts.mjs, story.mjs, economics.mjs, rule-suggest.mjs, rul...

Reference

Aletheia CLI reference: every aletheia command and flag — Every aletheia command and flag with a synopsis and a real example: capture, search, rules, install, sync, team, service, erase and alerts.
MCP tools reference: the 13 Aletheia MCP tools and their inputs — The 13 tools the Aletheia MCP server lists, with input schemas, read or write access, example calls and results, plus stdio and HTTP setup.
Aletheia configuration reference: environment variables, settings and data directory — Every Aletheia environment variable with its default, the runtime settings and where they are stored, and the files in the data directory.
Aletheia hooks reference: events, payloads, redaction and fail-open behavior — How Aletheia hooks work: events per host, payload fields read, redaction, fail-open exit 0, the spool, timeouts, and how to test or remove a hook.
3. HTTP API — Base: http://127.0.0.1:<port>. All JSON responses carry Cache-Control: no-store. Pages carry Content-Security-Policy: frame-ancestors 'none' and X-Frame-Options: DENY.

Compare

claude-mem alternative: Aletheia compared with claude-mem — A fair, sourced comparison of Aletheia and claude-mem: where claude-mem is ahead, where Aletheia differs, measured LoCoMo retrieval numbers.
Memory tools compared: Aletheia, Mem0, Zep and Graphiti, Supermemory, Basic Memory — Aletheia compared with Mem0, Zep and Graphiti, Supermemory and Basic Memory on licence, local use, MCP and hosting, each fact sourced and dated.
Claude Code memory options: CLAUDE.md, auto memory, MCP servers and Aletheia — How persistent memory works in Claude Code: CLAUDE.md files, auto memory, MCP servers, plugins and hooks, and where Aletheia fits beside them.

Project

Aletheia benchmarks: how to reproduce every published number — The five benchmark commands behind every Aletheia number, what each one measures, the results with dates, what is not measured and the negative results.
Aletheia status and limits: alpha, what is verified and what is not — Aletheia is alpha. This page lists what tests cover, what ran on real tools, what is unverified, platform status and how to report from a real install.
Dependencies — Aletheia has no required runtime dependencies. It uses the Bun standard library and Bun's built-in SQLite binding only. The audit that enforces this is scripts/audit-deps.mjs:

Internals

1. Architecture — claude-mem is a memory plugin for coding agents. Its worker (scripts/worker-service.cjs, a 4.2 MB Bun bundle) records every prompt, tool call, observation and session summary in...
2. Data model — Opened with readonly: true, PRAGMA queryonly = ON, busytimeout = 1500. Every SELECT goes through a helper that turns "no such table" and "no such column" into an empty result, s...
6. Frontend — Aletheia has one app page at /. It is plain HTML, CSS and JavaScript: no framework, no build step, no font file, no CDN and no dependency. It works offline. The older claude-mem...
7. Operations — bun bin/aletheia-server.mjs