Aletheia Mem

mohamed-ashraf-elsaed7stars

Free, local memory and rules hub for AI coding tools. One store for any tool over MCP, REST and CLI. Sync rules to CLAUDE.md, AGENTS.md, Cursor and more.

Databases Knowledge Memory

Install Run on PlugMCP

GitHub Website

Run on PlugMCP

1# Aletheia Mem

README.mdMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

Install from the publisher. Not a PlugMCP endpoint.

Run on PlugMCP

Host a copy with our keys and logs.

No packaged release in the registry yet. Follow the repository README.

RepositoryPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
License: Apache-2.0
Last checked: 2026-10-28

Stars: 7
Tools: —
Uptime: —

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install Aletheia Mem?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Aletheia Mem need an API key?

No required environment variable is listed on this record.

What transport does Aletheia Mem use?

Aletheia Mem runs locally over stdio.

When was Aletheia Mem last checked?

Last checked 2026-10-28. Free, local memory and rules hub for AI coding tools. One store for any tool over MCP, REST and CLI. Sync rules to CLAUDE.md, AGENTS.md, Cursor and more.

From the publisher

Documentation

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

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, but no hook or session has run inside any tool yet, and answer accuracy is not measured. CI runs on Linux and macOS; Windows is not supported yet and not tested.

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

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.

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 four tabs: Work (Aletheia's own view of captured sessions, facts and goals), Memory (search, edit, pin, delete, export), Rules (write once and sync) and Tools (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; no hook or session ran inside any tool.
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; none has been run inside the tool. OpenCode is MCP+rules.

Tool	Level	Verification	Hook events installed
claude-code	full	MCP connection 2.1.312 on 2026-10-27; hooks not run	SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd
command-code	full	MCP connection 1.88.1 on 2026-10-27; hooks not run	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.130.0 on 2026-10-27; hooks not run	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 only when the real CLI listed the server; hooks have not been run inside any tool.

Measured numbers

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

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 the table this way:

Recall@5 is retrieval. It asks whether the gold evidence is in the top five results. It is not a judgment of whether an answer was right.
Answer accuracy is not measured. There is no reader or judge harness yet.
The gap is not 2× when both systems receive the same extracted facts. The speed difference is larger than the quality difference.
The first local extraction run failed. Ollama llama3.2:1b answered a trivial call, but the facts-v1 prompt over a two-turn window returned HTTP 500 after 4 min 41 s. No fact was extracted from that run.
Our rule extractor does not reproduce the fact gain. It added 1,672 facts and moved Recall@5 from 57.3% to 57.7%; the dataset's own facts added 7.3 points. Method, raw files and the negative result: bench/results.

How it compares

Capability	Aletheia (today)	claude-mem	Mem0	Zep/Graphiti	Supermemory	Basic Memory
Local-first	yes	yes	yes OSS	partial (Graphiti only)	yes self-host	yes
Free	yes	yes OSS	yes OSS	partial (Graphiti free)	yes OSS	yes OSS
No account	yes	yes local	yes OSS	yes Graphiti	yes self-host	yes
MCP	yes stdio + HTTP	yes	yes	partial (reference servers)	yes	yes
REST	yes `/v1`	yes worker API	yes	yes	yes	partial
CLI	yes	yes `npx`	partial	no	partial	yes
Rules sync to tool files	yes 9 targets	no	no	no	no	partial (AGENTS.md)
Import/export between tools	partial (own bundle + claude-mem)	partial (export/import)	partial (platform migration)	partial	partial	yes Markdown
Hook capture	yes six hosts, fixture-tested; no host opened	yes	no	no	no	partial
Vector search	partial (optional ONNX)	yes Chroma	yes	yes	yes	yes
Graph / entity memory	partial (entity rows exist; graph retrieval)	no	yes	yes	UNVERIFIED	yes wikilinks
Temporal reasoning	partial (bi-temporal facts, invalidation; as-of query)	partial (dates)	yes	yes	yes	partial
Team sharing	partial (self-hosted sync and devices; team mode)	partial (paid)	yes paid	yes paid	yes paid	no
Benchmark published and reproducible	partial (retrieval yes; answer no)	no	vendor only	vendor only	vendor only	no
Languages supported	11 (English + 10 machine translations; no native review)	29 modes, 32 READMEs	SDK	SDK	SDK	SDK

Competitor cells are copied from each project's own public documentation, fetched 2026-10-26. Aletheia cells were updated 2026-10-26 from tested features; installer sources are in docs/25-installers.md. Cells the source did not state read UNVERIFIED.

Sync and remote MCP

Both are self-hosted and free; neither is tested across two real machines.

Aletheia Sync is an append-only operation log with one result per operation, device pairing, tombstones, compaction, purge and scoped tokens. Optional end-to-end encryption encrypts payloads on the device before they are sent; it does not hide metadata such as device id, operation kind, entity id, timing or ciphertext size. Unencrypted accounts keep plaintext payloads on the hub. Tested on loopback only. docs/29
Remote MCP serves the read tools (and, with a sync or admin token, the write tools) over the MCP Streamable HTTP transport. Each call needs a bearer token, is rate-limited and is written to an append-only audit row. TLS is delegated to a reverse proxy or tunnel; OAuth is not built. docs/30

Interfaces

Interface	Where	Use
MCP (stdio)	`bun bin/mcp.mjs`	the 13 MCP tools below (read and write)
MCP (HTTP)	sync hub `/mcp`	the same tools with a bearer token and per-token scope
REST	`/v1/memories`, `/v1/search`, `/v1/timeline`, `/v1/observations/batch`, `/v1/context`, `/v1/events`, `/v1/info`, `/v1/work`	scripts, CI, any language; optional `ALETHEIA_API_KEY` bearer key
CLI	`bin/aletheia.mjs`	hooks, shell, cron, sync
Files	rules sync	each tool's own instruction file

MCP tools

Tool	Purpose	Access
`search`	Search shared memory	read
`timeline`	Show context around a memory	read
`get_observations`	Get full memory text by id	read
`save_memory`	Save a memory	write
`session_start_context`	Load session start context	read
`fact_history`	Show how a fact changed	read
`list_rules`	List standing rules	read
`add_rule`	Add a standing rule	write
`confirm_rule`	Confirm a rule is still right	write
`dismiss_memory`	Dismiss a memory	write
`restore_memory`	Restore a dismissed memory	write
`work_state_write`	Write a work-state list	write
`work_state_read`	Read a work-state list	read

Configuration

All settings are environment variables. The defaults are safe for a single-user machine.

Variable	Default	Meaning
`ALETHEIA_PORT`	`37790`	Listen port.
`ALETHEIA_HOST`	`127.0.0.1`	Bind address. A non-loopback bind turns on Hub login.
`ALETHEIA_DATA_DIR`	`~/.aletheia`	Everything this project writes, including `hub.db`.
`ALETHEIA_HUB_DB`	`<data dir>/hub.db`	The shared memory store.
`ALETHEIA_API_KEY`	empty	Bearer key required on `/v1/*` when set.
`CLAUDE_MEM_DB`	`~/.claude-mem/claude-mem.db`	claude-mem's database (read-only; importer and optional legacy viewer).
`ALETHEIA_RULES_FILE`	`<data dir>/MY-RULES.md`	The legacy Work view's rules file.
`ALETHEIA_PROVIDER`	`none`	`none`, `claude-cli` or an OpenAI-compatible provider.
`ALETHEIA_PROVIDERS`	empty	Ordered fallback chain, for example `ollama,openai`.
`ALETHEIA_OPENAI_BASE_URL`, `_API_KEY`, `_MODEL`	OpenRouter URL, empty, empty	For `openai` and human copy.
`ALETHEIA_OUTPUT_LANGUAGE`	empty	Language for extracted facts and summaries.
`ALETHEIA_BUG_COMPAT`	off	`1` reproduces the original's empty observation half.
`ALETHEIA_TOOL`, `ALETHEIA_CWD`		MCP server: names the calling tool and default project.

Limits and unverified claims

This list is the honest half of the README.

MCP config was listed by the real CLI for Claude Code, Command Code, Codex CLI and OpenCode on 2026-10-27; no hook or session ran inside a host. Cursor, Gemini CLI and Windsurf remain "config written from docs, not tested on a real install."
CI runs on Linux and macOS. The benchmark runs on Linux only. Windows is not supported yet and not tested.
Answer accuracy is not measured. Recall@5 is retrieval, not whether an answer was correct.
The 1B-model extraction run failed; facts from our own extractor were measured with the rule extractor only.
Sync and E2EE are tested with temp data dirs and a loopback hub. No real tunnel or second host was used.
E2EE covers payloads, not metadata.
At 50,000 synthetic rows, keyword search p95 is 32.7 ms project-scoped and 58.6 ms across all projects (measured-by-us, bun bench/scale.mjs 50000 20000 --index tuned --queries 200 --seed 1, Linux). The 50 ms target is met for project-scoped search.
The 10 README translations are machine-translated. No native speaker has reviewed them.
"Works with " is not claimed for any tool. Only a real install test would justify it.

Layout

bin/            server, CLI, MCP server, sync hub, legacy Work ledger CLI
src/
  server.mjs app.mjs source.mjs config.mjs humancopy.mjs      server and the legacy Work API
  readmodel/ ledger/ refresh/ store/ http/                     legacy Work internals
  hub/            store (memories, FTS5, rules, bundles)  rules-sync  tools  importers  capture  compress  mcp  routes  sync
public/         the one UI (index.html, one-ui.*, tabs/, work-view.js);
                work.html and assets/ are the optional legacy viewer
public-hub/     the old Memory Hub assets, still served at /hub/app.js
prompts/ vendor/ the original's skill prompts and Python scripts
test/           the test suite and a synthetic fixture database
docs/           the documents

Documents

Architecture · Data model · HTTP API · Frontend · Operations
Installers · Sync · Remote MCP · Team mode · Requests and goals
Dependencies and licences · Claude Desktop · Rules targets

Contributing

The most useful contribution is a report from a real install: open an issue with the tool, its version, the command you ran and what the tool did. See CONTRIBUTING.md. Run bun test and bun scripts/gen-tables.mjs --check before a pull request. A new runtime dependency needs a reason.

Licence

Apache-2.0. See NOTICE.md for what comes from claude-mem. Not affiliated with or endorsed by the claude-mem authors or Anthropic.

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; no hook or session ran inside any tool.

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; none has been run inside the tool. OpenCode is MCP+rules.

Tool

Level

Verification

Hook events installed

claude-code

full

MCP connection 2.1.312 on 2026-10-27; hooks not run

SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd

command-code

full

MCP connection 1.88.1 on 2026-10-27; hooks not run

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.130.0 on 2026-10-27; hooks not run

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)

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

Capability

Aletheia (today)

claude-mem

Mem0

Zep/Graphiti

Supermemory

Basic Memory

Local-first

yes

yes OSS

partial (Graphiti only)

yes self-host

yes

Free

yes

yes OSS

partial (Graphiti free)

yes OSS

No account

yes

yes local

yes OSS

yes Graphiti

yes self-host

yes

MCP

yes stdio + HTTP

yes

partial (reference servers)

yes

REST

yes /v1

yes worker API

yes

partial

CLI

yes

yes npx

partial

yes

Rules sync to tool files

yes 9 targets

partial (AGENTS.md)

Import/export between tools

partial (own bundle + claude-mem)

partial (export/import)

partial (platform migration)

partial

yes Markdown

Hook capture

yes six hosts, fixture-tested; no host opened

yes

partial

Vector search

partial (optional ONNX)

yes Chroma

yes

Graph / entity memory

partial (entity rows exist; graph retrieval)

yes

UNVERIFIED

yes wikilinks

Temporal reasoning

partial (bi-temporal facts, invalidation; as-of query)

partial (dates)

yes

partial

Team sharing

partial (self-hosted sync and devices; team mode)

partial (paid)

yes paid

Benchmark published and reproducible

partial (retrieval yes; answer no)

vendor only

Languages supported

11 (English + 10 machine translations; no native review)

29 modes, 32 READMEs

SDK

Interface

Where

Use

MCP (stdio)

bun bin/mcp.mjs

the 13 MCP tools below (read and write)

MCP (HTTP)

sync hub /mcp

the same tools with a bearer token and per-token scope

REST

/v1/memories, /v1/search, /v1/timeline, /v1/observations/batch, /v1/context, /v1/events, /v1/info, /v1/work

scripts, CI, any language; optional ALETHEIA_API_KEY bearer key

CLI

bin/aletheia.mjs

hooks, shell, cron, sync

Files

rules sync

each tool's own instruction file

Tool

Purpose

Access

search

Search shared memory

read

timeline

Show context around a memory

read

get_observations

Get full memory text by id

read

save_memory

Save a memory

write

session_start_context

Load session start context

read

fact_history

Show how a fact changed

read

list_rules

List standing rules

read

add_rule

Add a standing rule

write

confirm_rule

Confirm a rule is still right

write

dismiss_memory

Dismiss a memory

write

restore_memory

Restore a dismissed memory

write

work_state_write

Write a work-state list

write

work_state_read

Read a work-state list

read

Variable

Default

Meaning

ALETHEIA_PORT

37790

Listen port.

ALETHEIA_HOST

127.0.0.1

Bind address. A non-loopback bind turns on Hub login.

ALETHEIA_DATA_DIR

~/.aletheia

Everything this project writes, including hub.db.

ALETHEIA_HUB_DB

<data dir>/hub.db

The shared memory store.

ALETHEIA_API_KEY

empty

Bearer key required on /v1/* when set.

CLAUDE_MEM_DB

~/.claude-mem/claude-mem.db

claude-mem's database (read-only; importer and optional legacy viewer).

ALETHEIA_RULES_FILE

<data dir>/MY-RULES.md

The legacy Work view's rules file.

ALETHEIA_PROVIDER

none

none, claude-cli or an OpenAI-compatible provider.

ALETHEIA_PROVIDERS

empty

Ordered fallback chain, for example ollama,openai.

ALETHEIA_OPENAI_BASE_URL, _API_KEY, _MODEL

OpenRouter URL, empty, empty

For openai and human copy.

ALETHEIA_OUTPUT_LANGUAGE

empty

Language for extracted facts and summaries.

ALETHEIA_BUG_COMPAT

off

1 reproduces the original's empty observation half.

ALETHEIA_TOOL, ALETHEIA_CWD

MCP server: names the calling tool and default project.

bin/ server, CLI, MCP server, sync hub, legacy Work ledger CLI src/ server.mjs app.mjs source.mjs config.mjs humancopy.mjs server and the legacy Work API readmodel/ ledger/ refresh/ store/ http/ legacy Work internals hub/ store (memories, FTS5, rules, bundles) rules-sync tools importers capture compress mcp routes sync public/ the one UI (index.html, one-ui.*, tabs/, work-view.js); work.html and assets/ are the optional legacy viewer public-hub/ the old Memory Hub assets, still served at /hub/app.js prompts/ vendor/ the original's skill prompts and Python scripts test/ the test suite and a synthetic fixture database docs/ the documents