关于 Aletheia
Aletheia 是面向 AI 编码工具的本地记忆与规则中心，使用 SQLite 保存共享记忆，并提供 MCP、REST、命令行和规则文件同步。项目处于 alpha 阶段，钩子尚未在真实工具会话中验证。
主要功能
- 01本地 SQLite 记忆存储
- 02搜索和管理记忆
- 03同步规则到工具指令文件
- 04支持 stdio 和 HTTP 的 MCP
- 05REST API 与命令行
- 06通过钩子捕获会话
适用场景
- 01在不同编码会话间复用项目上下文
- 02让多种编码工具共享记忆
- 03按各工具格式维护规则
MCP 相关
通过 MCP 的 stdio 或 HTTP 接口提供记忆、规则、会话上下文和工作状态的读写工具。HTTP 调用使用 bearer token。
配置
本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。
工具
本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。
详细介绍
Aletheia
为 AI 编码工具提供免费的本地记忆与规则中心。
在你的设备上存储一份数据。任何工具都能通过 MCP、REST 或命令行读取。
安装并运行。需要 Bun 1.1 或更高版本；CLI 在 Bun 上运行，而非 Node。
npm install -g aletheia-mem
aletheia-server
# open http://127.0.0.1:37790
状态：alpha。 记忆引擎和安装程序已通过测试。真实的 Claude Code、Command Code、Codex CLI 和 OpenCode 已列出生成的 MCP 配置，但尚未在任何工具中运行过钩子或会话，也尚未评估回答准确度。CI 在 Linux 和 macOS 上运行；目前不支持 Windows，也未经过测试。
1,414 项测试——0 项失败（运行 bun test）。
English · 中文 · Español · Português (Brasil) · 日本語 · Deutsch · Français · 한국어 · हिन्दी · العربية · Русский。
机器翻译版本位于 docs/i18n/；英文版为权威版本。所有译文均未经母语人士审核。
它是什么
Aletheia 是一个免费的本地记忆与规则中心，供 AI 编码工具使用。任何工具都可以通过 MCP、 REST 或 CLI 读取同一个 SQLite 存储库，而你的规则会写入各个工具自己的指令文件。
每个编码 Agent 都会在会话之间遗忘内容，而且各自的记忆方式也不同。Aletheia 会在你的设备上集中保存记忆和 规则，让每个工具都能以自己熟悉的格式读取。无需账户、没有遥测；除非你配置了模型提供商，否则不会发起网络 请求。它仅监听回环地址。
三条命令即可安装
git clone https://github.com/mohamed-ashraf-elsaed/aletheia-mem
cd aletheia-mem
bun bin/aletheia-server.mjs
打开 http://127.0.0.1:37790。需要 Bun 1.1 或更高版本。若要安装已发布的软件包，
请运行 npm install -g aletheia-mem，然后使用 aletheia-server 启动。无需安装任何运行时依赖。
首个界面有四个标签页：工作（Aletheia 对已捕获会话、事实和目标的视图）、记忆 （搜索、编辑、固定、删除、导出）、规则（编写一次并同步）和 工具（安装程序状态与审计）。
捕获机制
aletheia install claude-code --write
aletheia install cursor --write
aletheia install --list # capability level and verification per tool
不带 --write 时，该命令会进行试运行。它会列出所有将要修改的文件，但不会写入任何内容。每个被修改的
文件都会生成带时间戳的备份。钩子会调用已安装的 aletheia 命令，在存储前对机密信息和 <private> 块进行
脱敏；如果数据库不可用，则会将数据暂存到磁盘，并始终以 0 退出，因此绝不会阻塞宿主程序。
压缩任务会排队处理，不会在钩子内部运行。详细信息及各宿主对应的完整钩子列表：docs/25。
可连接的工具
Aletheia 不依赖任何单一工具。它支持 MCP（stdio 和 HTTP）、普通 REST API 和 CLI，并会写入各个工具已支持的指令文件。以下是已检查和未检查的内容：
| 检查项 | 结果 |
|---|---|
| 使用官方 MCP SDK 客户端测试 MCP 服务 | 通过（协议版本从 2025-11-25 到 2024-11-05） |
| Claude Code、Command Code、Cursor、Codex CLI、Gemini CLI、Windsurf、OpenCode 的配置格式 | 根据 2026-10-26 获取的官方文档编写，并使用测试样例验证。2026-10-27，实际 CLI 为 Claude Code、Command Code、Codex CLI 和 OpenCode 列出了 aletheia MCP 服务；Cursor、Gemini CLI 和 Windsurf 未在实际安装中测试。 |
| Claude Desktop MCP 配置 | 已编写文档并使用测试样例验证合并结果；未在应用中打开 |
规则文件：CLAUDE.md、AGENTS.md、GEMINI.md、.cursor/rules/*.mdc、.windsurf/rules/*.md、Copilot、Aider | 已在临时文件夹中编写并测试（docs/verification/rules-targets.md） |
| 在上述任一工具的实际安装中进行检查 | 2026-10-27，实际 CLI 已为 Claude Code、Command Code、Codex CLI 和 OpenCode 读回 MCP 配置；没有在任何工具中运行 hook 或会话。 |
| 通过工具的 hook 自动捕获 | 已为 Claude Code、Command Code、Cursor、Codex CLI、Gemini CLI 和 Windsurf 构建。每条已安装的 hook 命令都在临时 HOME 中使用录制的 payload 进行了端到端测试；没有在任何工具中运行。OpenCode 支持 MCP 和规则。 |
| 工具 | 级别 | 验证情况 | 已安装的 hook 事件 |
|---|---|---|---|
| claude-code | full | 2026-10-27 的 MCP 连接版本为 2.1.312；hook 未运行 | SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd |
| command-code | full | 2026-10-27 的 MCP 连接版本为 1.88.1；hook 未运行 | SessionStart、PostToolUse、Stop |
| cursor | full | 根据文档编写配置，未在实际安装中测试 | sessionStart、beforeSubmitPrompt、postToolUse、afterAgentResponse、stop、sessionEnd |
| codex | full | 2026-10-27 的 MCP 连接版本为 0.130.0；hook 未运行 | SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd |
| gemini-cli | full | 根据文档编写配置，未在实际安装中测试 | SessionStart、BeforeAgent、AfterTool、AfterAgent、SessionEnd |
| windsurf | full | 根据文档编写配置，未在实际安装中测试 | pre_user_prompt、post_run_command、post_write_code、post_cascade_response |
| opencode | mcp+rules | 2026-10-27 的 MCP 连接版本为 1.18.33；hook 未运行 | 无（仅支持 MCP 和规则） |
根据 src/hub/install.mjs 通过 aletheia install --list 生成。只有在实际 CLI 列出 MCP 服务时，对应行才会标明 MCP 连接；hook 尚未在任何工具中运行。
实测数据
在 LoCoMo 上，对比发布版 claude-mem 15.2.0 与本项目。以下是检索数据，不是答案准确率。
| 运行 | 问题数 | Recall@5 | MRR | 毫秒/次查询 |
|---|---|---|---|---|
| claude-mem 15.2.0（发布版），原始轮次 — 我们实测 | 1,536 | 36.0% | 0.285 | p50 1,699 ms，p95 2,824 ms（空闲状态，40 次查询） |
| 原始轮次，全部 10 段对话 | 1,536 | 57.4% | 0.497 | 3.72 |
| 数据集事实，全部 10 段对话 | 1,536 | 64.8% | 0.591 | 5.53 |
| 数据集事实，3 段对话 | 383 | 67.4% | 0.620 | 5.80 |
| 数据集事实，3 段对话，+ 重排 | 383 | 73.9% | 0.686 | 251.16 |
| 数据集事实，全部 10 段对话，+ 重排 | 1,536 | 72.3% | 0.680 | 646.19 |
| 我们用规则提取的事实，全部 10 段对话 | 1,536 | 57.7% | 0.492 | 4.94 |
仅检索：Recall@5 表示正确证据是否出现在前五个结果中，不代表答案准确率。每一行都是我们在相同的 LoCoMo 问题上实测的；本表不含厂商宣称的基准测试数据。数据生成自 bench/results/2026-10-26/（bench/claude-mem-baseline.mjs、raw-turns.json（混合检索）、dataset-facts.json（混合检索+事实）、dataset-facts-3-rerank.json（混合检索+事实）、dataset-facts-3-rerank.json（混合检索+事实+重排）、dataset-facts-rerank.json（混合检索+事实+重排）、our-facts-rules.json（混合检索+事实））；使用 bun scripts/compare-bench.mjs 重新运行。
解读表格时请注意：
- Recall@5 衡量的是检索效果。 它表示正确证据是否出现在前五个结果中，不评判答案是否正确。
- 尚未测量答案准确率。 目前还没有读者或评判器测试框架。
- 在两个系统获得相同提取事实的情况下，差距不到 2 倍。 速度差异大于质量差异。
- 首次本地提取运行失败。 Ollama
llama3.2:1b成功响应了一个简单调用，但facts-v1提示词在两轮对话窗口上的运行在 4 min 41 s 后返回 HTTP 500。该次运行未提取出任何事实。 - 我们的规则提取器无法复现事实带来的增益。 它新增了 1,672 条事实，Recall@5 从 57.3% 提升到 57.7%；数据集自带的事实则提升了 7.3 个百分点。方法、原始文件和负面结果见： bench/results。
对比
| 能力 | Aletheia（当前） | claude-mem | Mem0 | Zep/Graphiti | Supermemory | Basic Memory |
|---|---|---|---|---|---|---|
| 本地优先 | 是 | 是 | 是，开源 | 部分（仅 Graphiti） | 是，可自托管 | 是 |
| 免费 | 是 | 是，开源 | 是，开源 | 部分（Graphiti 免费） | 是，开源 | 是，开源 |
| 无需账户 | 是 | 是，本地 | 是，开源 | 是，Graphiti | 是，可自托管 | 是 |
| MCP | 是，stdio + HTTP | 是 | 是 | 部分（参考服务） | 是 | 是 |
| REST | 是，/v1 | 是，worker API | 是 | 是 | 是 | 部分 |
| CLI | 是 | 是，npx | 部分 | 否 | 部分 | 是 |
| 同步规则到工具文件 | 是，9 个目标 | 否 | 否 | 否 | 否 | 部分（AGENTS.md） |
| 工具间导入/导出 | 部分（自有 bundle + claude-mem） | 部分（导出/导入） | 部分（平台迁移） | 部分 | 部分 | 是，Markdown |
| Hook 捕获 | 是，支持 6 个宿主，经 fixture 测试；未打开任何宿主 | 是 | 否 | 否 | 否 | 部分 |
| 向量搜索 | 部分（可选 ONNX） | 是，Chroma | 是 | 是 | 是 | 是 |
| 图谱 / 实体记忆 | 部分（存在实体行；图谱检索） | 否 | 是 | 是 | 未验证 | 是，wikilinks |
| 时间推理 | 部分（双时态事实、失效处理；按时间点查询） | 部分（日期） | 是 | 是 | 是 | 部分 |
| 团队共享 | 部分（自托管同步和设备；团队模式） | 部分（付费） | 是，付费 | 是，付费 | 是，付费 | 否 |
| 已发布且可复现的基准测试 | 部分（检索是；回答否） | 否 | 仅供应商 | 仅供应商 | 仅供应商 | 否 |
| 支持的语言 | 11 种（英语 + 10 种机器翻译；未经母语审校） | 29 种模式，32 份 README | SDK | SDK | SDK | SDK |
竞品单元格摘自各项目自身的公开文档，获取日期为 2026-10-26。Aletheia 单元格于 2026-10-26 根据已测试的功能更新；安装程序来源见 docs/25-installers.md。来源未说明的单元格标为 UNVERIFIED。
同步和远程 MCP
两者均可自托管且免费；都未在两台真实设备间进行测试。
- Aletheia Sync 是仅追加操作日志，每个操作对应一个结果，支持设备配对、墓碑标记、压缩、清除和作用域令牌。可选的端到端加密会在设备上加密负载后再发送；但不会隐藏设备 ID、操作类型、实体 ID、时间或密文大小等元数据。未加密的账户会在中枢保留明文负载。仅在回环环境中测试。docs/29
- 远程 MCP 通过 MCP Streamable HTTP 传输提供读取工具（使用
sync或admin令牌时也提供写入工具）。每次调用都需要 bearer 令牌，受到速率限制，并会写入仅追加的审计行。TLS 由反向代理或隧道处理；未内置 OAuth。docs/30
接口
| 接口 | 位置 | 用途 |
|---|---|---|
| MCP（stdio） | bun bin/mcp.mjs | 下方的 13 个 MCP 工具（读取和写入） |
| MCP（HTTP） | 同步中枢 /mcp | 相同工具，使用 bearer 令牌和逐令牌作用域 |
| REST | /v1/memories、/v1/search、/v1/timeline、/v1/observations/batch、/v1/context、/v1/events、/v1/info、/v1/work | 脚本、CI、任何语言；可选的 ALETHEIA_API_KEY bearer 密钥 |
| CLI | bin/aletheia.mjs | hooks、shell、cron、同步 |
| 文件 | 规则同步 | 每个工具各自的指令文件 |
MCP 工具
| 工具 | 用途 | 访问权限 |
|---|---|---|
search | 搜索共享记忆 | 读取 |
timeline | 显示记忆的上下文 | 读取 |
get_observations | 按 ID 获取完整记忆文本 | 读取 |
save_memory | 保存记忆 | 写入 |
session_start_context | 加载会话开始时的上下文 | 读取 |
fact_history | 显示事实的变更情况 | 读取 |
list_rules | 列出长期规则 | 读取 |
add_rule | 添加长期规则 | 写入 |
confirm_rule | 确认规则仍然有效 | 写入 |
dismiss_memory | 忽略一条记忆 | 写入 |
restore_memory | 恢复一条已忽略的记忆 | 写入 |
work_state_write | 写入工作状态列表 | 写入 |
work_state_read | 读取工作状态列表 | 读取 |
配置
所有设置均为环境变量。默认值适用于单用户机器。
| 变量 | 默认值 | 含义 |
|---|---|---|
ALETHEIA_PORT | 37790 | 监听端口。 |
ALETHEIA_HOST | 127.0.0.1 | 绑定地址。绑定到非回环地址时会启用 Hub 登录。 |
ALETHEIA_DATA_DIR | ~/.aletheia | 本项目写入的所有内容，包括 hub.db。 |
ALETHEIA_HUB_DB | <data dir>/hub.db | 共享记忆存储。 |
ALETHEIA_API_KEY | 空 | 设置后，访问 /v1/* 需要 Bearer 密钥。 |
CLAUDE_MEM_DB | ~/.claude-mem/claude-mem.db | claude-mem 的数据库（只读；供导入器和可选的旧版查看器使用）。 |
ALETHEIA_RULES_FILE | <data dir>/MY-RULES.md | 旧版 Work 视图的规则文件。 |
ALETHEIA_PROVIDER | none | none、claude-cli 或兼容 OpenAI 的提供方。 |
ALETHEIA_PROVIDERS | 空 | 按顺序排列的备用提供方链，例如 ollama,openai。 |
ALETHEIA_OPENAI_BASE_URL, _API_KEY, _MODEL | OpenRouter URL、空、空 | 用于 openai 和人工复制。 |
ALETHEIA_OUTPUT_LANGUAGE | 空 | 提取事实和摘要时使用的语言。 |
ALETHEIA_BUG_COMPAT | 关闭 | 1 会复现原版观察内容为空的情况。 |
ALETHEIA_TOOL, ALETHEIA_CWD | MCP 服务：指定调用工具和默认项目。 |
限制和未经验证的说法
以下是 README 中如实说明的部分。
- 2026-10-27，真实 CLI 为 Claude Code、Command Code、Codex CLI 和 OpenCode 列出了 MCP 配置；但没有在任何宿主环境中运行钩子或会话。Cursor、Gemini CLI 和 Windsurf 仍属于“根据文档写入配置，未在真实安装环境中测试”。
- CI 在 Linux 和 macOS 上运行。基准测试仅在 Linux 上运行。暂不支持 Windows，也未进行测试。
- 未测量回答准确性。Recall@5 衡量的是检索效果，而非回答是否正确。
- 1B 模型的提取运行失败；对我们自己的提取器得出的事实仅使用规则提取器进行了测量。
- 同步和 E2EE 使用临时数据目录及回环 Hub 进行了测试。未使用真实隧道或第二台主机。
- E2EE 保护的是有效载荷，不包括元数据。
- 在 50,000 条合成行的情况下，关键词搜索的 p95 耗时为：按项目搜索 32.7 ms，跨所有项目搜索 58.6 ms（由我们测量，
bun bench/scale.mjs 50000 20000 --index tuned --queries 200 --seed 1，Linux）。按项目搜索达到了 50 ms 的目标。 - README 的 10 种译文由机器翻译生成，尚未经母语人士审校。
- 我们不会声称任何工具“可用”。只有经过真实安装测试，才能支持这种说法。
目录结构
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
文档
贡献
最有帮助的贡献是报告真实安装体验：提交 issue，说明工具、版本、运行的命令以及工具的行为。请参阅 CONTRIBUTING.md。提交 pull request 前，请运行 bun test 和
bun scripts/gen-tables.mjs --check。新增运行时依赖需要说明理由。
许可证
Apache-2.0。有关源自 claude-mem 的内容，请参阅 NOTICE.md。本项目与 claude-mem 作者或 Anthropic 无关，也未获其认可。
评论
一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。