Exomem

exomem

为支持 MCP 的 Agent 提供持久记忆，并保留来源、证据、历史记录和审核功能。

exomem 将自有的 Markdown/Obsidian 知识库转化为本地知识基础，供 Codex、Claude Code、Cursor、聊天机器人、命令行 Agent，以及任何能够调用 MCP 工具的客户端使用。你的文件始终是纯文本、本地存储、可移植的，并且可以在服务之外编辑。

agent -> MCP tools -> exomem -> your Markdown / Obsidian vault

30 秒验证效果

uvx exomem demo

一条命令，无需安装、无需配置，也不需要你自己的知识库：

exomem demo — bundled sample vault, keyword mode, fully local
vault: /tmp/exomem-demo-XXXXXX

1. doctor: PASS (0.8s)
2. find "retrieval": PASS (0.1s)
   - Knowledge Base/Sources/Sessions/2026-06-30-sample-session.md
   - Knowledge Base/Notes/Insights/retrieval-needs-owned-files.md
3. get retrieval insight: PASS (0.0s)
   - title: Retrieval needs owned files
   - type: insight
   - excerpt: Local-first knowledge tools should retrieve from files the user already owns.
4. audit: PASS (0.0s)

demo PASS — total 1.0s. This is your proof: agents search files you own.
Next: connect your own vault with `exomem setup`

完全在本地运行，并且以只读方式访问软件包中附带的示例知识库。添加 --keep 可在运行后保留副本，以便在 Obsidian 中打开。

一行安装

Mac / Linux — 粘贴到终端：

curl -fsSL https://raw.githubusercontent.com/Artexis10/exomem/main/scripts/install.sh | sh

Windows — 粘贴到 PowerShell：

irm https://raw.githubusercontent.com/Artexis10/exomem/main/scripts/install.ps1 | iex

两种方式都会安装 uv 和 exomem，并引导你完成 exomem setup，为这台机器上的所有 Agent 客户端完成配置——Claude Code 和 Codex 都会获得 MCP 服务、全部十个技能，以及捕获/检索钩子。

之后可安全地再次运行——已完成的步骤会跳过。如果无法进行交互式提示（例如从其他脚本运行），它会打印接下来要运行的准确命令，而不是自行猜测。想亲自逐步操作？请参阅下文，或查看完整的手动指南 QUICKSTART.md。

Claude Code：作为插件安装

该插件包含技能和钩子。它的 MCP 配置项是可选的共享 HTTP URL；它不会在每次 Claude Code 会话中自动启动完整的 stdio 服务：

/plugin marketplace add Artexis10/exomem
/plugin install exomem@exomem

然后选择相应的方式。如果你已经将 Exomem 作为服务运行，以便通过手机或托管方式访问，可复用同一个经过身份验证的核心服务：

exomem setup --vault "/path/to/vault" --mcp-url https://<host>/mcp

如需仅在本地使用，请运行 exomem setup --vault "/path/to/vault" --stdio。此处有意要求显式指定 stdio，因为每个客户端会话都拥有自己的进程，并且可以加载自己的嵌入运行时。从旧版插件升级时，请运行 /plugin update exomem@exomem，然后运行 /reload-plugins 或重启 Claude Code，再次运行 setup。

claude.ai 和 ChatGPT

这两个平台都无法通过程序安装技能，需要手动上传。请先构建压缩包，然后在客户端的设置中上传：

exomem package-skills          # writes dist/skills/*.zip (all ten)

将客户端连接到你的服务，作为连接器使用（请参阅 docs/remote-quickstart.md）。这两个平台都没有钩子系统，因此其中的捕获由技能驱动，而非自动执行。

5 分钟完成设置

uv tool install exomem   # or: pip install exomem
exomem setup --vault "/path/to/your/Obsidian"

重新运行一行安装命令会升级现有的 uv-tool 安装，而不是让较旧的 exomem 命令继续留在 PATH 上。exomem --version --json 是一项不依赖模型的来源信息检查，因此也适用于精简版 CLI 与功能更完整的托管服务配套使用的场景。

一条命令即可完成整个本地设置：向导会扫描你的知识库并显示其中已有的内容，初始化 Knowledge Base/，运行 doctor 预检，为检测到的所有客户端（Claude Code 和 Codex）注册服务，并为每个客户端安装技能。

如果当前工作目录中的 .env 或进程环境包含 EXOMEM_BASE_URL，setup 会向 Claude Code 和 Codex 注册其规范的 /mcp 端点，使它们共用现有服务。否则会使用显式指定的本地 stdio 回退方式。使用 --mcp-url 直接选择服务，使用 --stdio 强制采用本地 stdio，并在有意替换现有手动配置的路由时使用 --replace-client-registration。原生客户端负责处理 OAuth；setup 绝不会存储 bearer token。

对于并非由它创建的配置文件，程序会尊重你的所有权：合并而非覆盖，先备份文件，并打印差异。 已经有一个装满笔记的知识库？这很常见：adopt 会先扫描，并以只读方式报告现有内容、建议的知识包，以及安全的复制／编译规划后续操作。Exomem 只会在 Knowledge Base/ 下写入内容——除非你明确复制或编译选定材料，否则现有文件不会受到影响。包括每日笔记知识库在内的完整说明，请参阅 QUICKSTART.md § 已经有一个装满笔记的知识库？。重新运行 setup 是安全的；已完成的步骤会显示 [skipped]。非交互模式： exomem setup --yes --vault "/path" --lean。

各个独立步骤（exomem init / doctor / install-skill / install-hook，以及 claude mcp add）仍可作为手动安装途径——请参阅 QUICKSTART.md。

该技能以 Claude Code 名称 exomem 安装——与连接器同名，因此技能、服务和工具都属于同一产品。对于 Claude Code，建议使用该技能——服务为 Claude 提供工具，技能则让它知道如何使用这些工具。钩子是面向 Claude Code 和 Codex 的本地客户端可靠性辅助工具：在回答前提供读取侧提醒，在自然停顿时提供写入侧提醒，并在压缩前后共享本地续接检查点。检查点只存储有界的结构性证据（仓库状态、产物哈希／计数和对话记录来源哈希），绝不存储对话、工具、摘要或产物内容。它不需要 MCP 连接或 Exomem 凭据。 读取侧钩子会屏蔽明显的控制／状态提示，例如 continue、 merge it 和 are you done?；也可以选择将该提醒升级为实际检索到的 KB 内容（EXOMEM_RETRIEVE_INJECT=1，需主动启用；旧名称 KB_RETRIEVE_INJECT 仍然有效）——或者设置 EXOMEM_RETRIEVE_INJECT=working_set，将编译后的 recall_context 数据包作为数据标头注入，并受 EXOMEM_RETRIEVE_INJECT_MAX_CHARS 限制（默认值为 4,000）。对于 Codex，运行 exomem install-hook --client codex；对于 Claude Code，运行 exomem install-hook——请参阅 QUICKSTART.md § 7。 两个客户端都会在手动或自动触发的 PreCompact 时创建检查点，并在 SessionStart(compact|resume) 时重新注入；Claude 还会在 SessionEnd 时创建检查点。固定版本 Codex CLI 0.144.3 不提供 SessionEnd 钩子，因此 Exomem 不会凭空添加一个。 其他 MCP 客户端仍可使用该服务。如果它们不支持 Skills，请让它们在会话开始时调用一次 bootstrap()；它会通过 MCP 返回相同的精简操作规范，其中包括何时搜索、何时保存、如何发现工作流技能、上传指引和性能配置。它还会引导内容编写流程：先搜索，起草类型化笔记，运行 suggest_links，使用合适的工具写入，检查警告／建议，然后报告路径。

你可以调整它执行这些操作的积极程度：四个显著程度级别（off / light / balanced / maximal），可通过 exomem prominence <level> 设置，或粘贴到网页助手的自定义指令中。带钩子的客户端默认使用 balanced；网页端和托管端默认使用 maximal，因为它们无法在轮次之间重新触发检查。级别说明和可直接复制粘贴的内容块，请参阅 docs/prominence.md。

有关特定客户端的助手指令，请参阅 docs/ai-assistant-guide.md。有关 Exomem 与聊天产品内置记忆之间的界限，请参阅 docs/vs-built-in-memory.md。

完整的本地安装说明见 QUICKSTART.md。远程／移动端安装说明见 docs/remote-quickstart.md 和 docs/deployment.md。 远程 OAuth 会通过 GitHub 一次性验证已配置的登录账号和不可变用户 ID，然后签发由 Exomem 管理的持久会话。运维人员可以使用 exomem auth sessions、exomem auth revoke <session-id> 和 exomem auth revoke --all 检查并撤销这些会话；会话管理绝不会作为 MCP 工具提供。

产品模型刻意保持简单：内置 AI 记忆负责记住偏好和路由，而 Exomem 则存储持久且受治理的知识，包括来源、证据、历史、决策、记录和审核。完整的思维模型请参见 docs/product-model.md，关于由用户持有的纵向记录，请参见 docs/records.md；关于交互式终端 UI（exomem tui，可选的 tui extra），请参见 docs/tui.md；关于打包的浏览器审核流程，请参见 docs/review-studio.md；关于每日审核和关系修复，请参见 docs/epistemic-inbox.md；关于知识包和管理详情，请参见 docs/knowledge-packs.md；关于命名的 Agent 工作流，请参见 docs/workflow-skills.md。

如需开发，或从代码检出目录运行示例知识库，而不是安装软件包：

git clone https://github.com/Artexis10/exomem.git
cd exomem
uv sync
uv run exomem demo

连接你的 Agent

codex mcp add exomem --env EXOMEM_VAULT_PATH="/path/to/vault" -- exomem --transport stdio

exomem install-hook --client codex

exomem install-hook --check

[mcp_servers.exomem]
command = "exomem"
args = ["--transport", "stdio"]
env = { EXOMEM_VAULT_PATH = "/path/to/vault" }

{"mcpServers": {"exomem": {"command": "exomem", "args": ["--transport", "stdio"], "env": {"EXOMEM_VAULT_PATH": "/path/to/vault"}}}}

claude mcp add exomem -- docker run -i --rm -v "/path/to/vault:/vault" -e EXOMEM_VAULT_PATH=/vault ghcr.io/artexis10/exomem:latest --transport stdio

首次启动时会在后台下载搜索模型 — find 会立即使用关键词排序，并在模型下载完成后自动升级为语义搜索。运行 exomem warm 可提前下载模型。

资源模式

Exomem 默认优先使用 CPU，避免空闲服务悄然占用 GPU 内存。无需修改代码即可控制机器资源占用：

exomem mode quiet          # low-resource: no heavy warm-up, evict caches, defer semantic reindex
exomem mode normal         # default: CPU steady-state, warm CPU caches allowed
exomem mode performance    # explicit opt-in for GPU-capable bulk/model work
exomem status --resources --json

玩游戏或运行其他前台任务前，请使用 quiet。关键词/BM25 新鲜度、文件变更新鲜度、入站链接和解析器状态都会保持实时；开销较大的语义/CLIP 重建索引工作可以延后，并会在资源状态中报告。稍后运行 exomem index 或 kb reconcile，即可补齐延后的语义工作。

自动切换到安静模式是可选的。手动选择 quiet、通过 EXOMEM_MODE 固定模式或禁用 EXOMEM_AUTO_QUIET 时，监控程序会跳过 GPU 压力查询。自动安静模式仍会监控压力，以便恢复先前的模式。

在受影响的 WSL/NVIDIA 系统上，反复运行 Linux nvidia-smi 进程可能会增加 Windows 驱动的内核内存占用，并干扰前台任务。 Microsoft WSL 问题 #12756 记录了复现过程。对于较旧版本的 Exomem，配置了 EXOMEM_AUTO_QUIET=0 的服务会在该服务重启后停止其监控程序。 设置空的 CUDA_VISIBLE_DEVICES 也会禁用 GPU 工作和 GPU 余量查询。 这些设置无需重启 Windows；现有驱动状态可能仍会保留。

功能

• 搜索你已有的知识库。 Markdown 文件会保留在原处；exomem 不会将副本导入专有笔记存储。
• 安全接管杂乱的知识库。 adopt 会先生成只读报告，并提供明确的复制和编译规划选项，因此在你做出选择前，原始文件会保持归档状态。
• 跨文本和媒体检索。 Markdown、PDF、Office 文档、图像、屏幕截图、音频和视频都可以通过本地提取变为可搜索内容。
• 将来源与结论分开保存。 原始采集内容、编译后的笔记、实体、证据和已被取代的结论会存放在不同类型的文件夹中。
• 呈现待审核事项。 审计和待处理队列可以显示尚未处理的来源、过时笔记、失效链接，以及值得审核的相近主张。
• 只做测量，不做判断。 服务负责确定性工作：搜索、提取、排序、嵌入、文件写入和图检查。推理仍由客户端模型完成。

为什么使用它

大多数 AI 笔记工具要求你迁移到它们的应用，或将文件导入它们的存储。exomem 采取相反的方式：让 Agent 来到你的知识库。

如需更深入的特定时间点对比，请参阅 docs/comparison-engraph.md。与 Basic Memory 的可复现纯图对比见 docs/comparison-basic-memory-graph.md。 如需了解它与聊天产品自带记忆功能的实际界限，请参阅 docs/vs-built-in-memory.md。

检索质量经过测量，速度亦然。 检索效果通过可复现的黄金集评估工具进行评测，而非仅凭断言；同时还会在语料库规模下按通道测量延迟：在 50,000 条笔记下，混合 find() 的端到端耗时低于 1 秒（参考桌面设备上为 864 ms，关闭热缓存），关键词/BM25 通道则由 FTS5 辅助索引提供服务，耗时仅为数毫秒。FTS5 内置于标准库 SQLite 中，因此精简安装也能使用。方法与数据见 docs/benchmarks.md。

简单入口

Agent 应先通过简单操作处理普通用户请求，然后再使用底层的类型化工具。

核心工具

exomem 提供用于常见知识库工作的类型化 MCP 工具：

第 2 层工具涵盖治理管理和文件系统逃生口，例如列出目录、创建文件、移动页面、将文件移至废纸篓，以及从废纸篓恢复文件。如果需要更精简的工具集，请设置 EXOMEM_DISABLE_TIER2=1。

每次写入都会在 Knowledge Base/log.md 中记录持久历史。服务调用也会写入 logs/exomem.log。

一项操作，三个入口

每项操作只声明一次，并通过以下方式提供：

• MCP，供 Agent 使用。
• CLI，供终端和脚本使用。
• REST，在设置 EXOMEM_REST_API_KEY 后，用于个人 HTTP 集成。

示例：

kb find "project handoff" --mode keyword
kb find "stale decision" --json
kb get "Notes/Insights/retrieval-needs-owned-files" --json
kb note --note-type insight --title "Agents need durable context" \
  --content "# Agents need durable context"

curl -s -X POST http://127.0.0.1:8765/api/find \
  -H "Authorization: Bearer $EXOMEM_REST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "project handoff", "mode": "keyword"}'

CLI 和 REST 使用相同的 JSON 封装：

{"success": true, "data": []}

默认支持多模态，仅在工作时驻留

原生发行版的服务命令会安装 standard 配置：本地嵌入、PDF/Office 文档、OCR 绑定、ASR 和 CLIP。服务启动时不会加载大型模型。媒体任务会进入持久队列，在一个一次性子进程中串行运行；空闲五分钟后，子进程会退出，其 RAM 和 MPS/MLX/CUDA 状态随之释放并还给主机。

手动安装或从源代码安装时，也可以直接选择相同的功能：

uv sync --extra embeddings
uv sync --extra media

• embeddings：本地文本嵌入和 CLIP 图像搜索。
• media：图像 OCR、PDF 提取、Office 文档提取，以及适用于音频/视频的 faster-whisper ASR。

CSV、TSV 和 JSON 证据上传会生成数据集来源卡片，便于发现和执行精确查询。YAML、JSONL、XML 和 TOML 导出会生成有长度限制的文本预览。这些路径无需可选附加项；有关限制和治理行为，请参阅来源格式。

资源受限的机器仍可使用 lean 和 hybrid。生成式图像描述和说话人分离属于高级可选功能，并非标准多模态路径的必要条件。

系统工具：图像 OCR 需要 Tesseract。在 Windows 上：

winget install --id UB-Mannheim.TesseractOCR -e

GPU 加速很有用，但并非必需。在 normal 和 quiet 模式下，稳态运行的 torch 模型默认使用 CPU；performance 是适用于性能足够的 NVIDIA CUDA 或 Apple Silicon MPS/Metal 路径的显式可选模式。有关 CUDA、Blackwell、Apple Silicon、说话人分离和远程服务的详情，请参阅 docs/deployment.md。

配置

服务会读取环境变量或 .env 文件。主要变量如下：

EXOMEM_CLAIM_NLI_MODEL 已弃用。模型身份仅来自仓库内的固定版本注册表；此变量中保留的值不会选择任何模型，exomem doctor 会将其报告为已忽略。

随附的固定模型是多语言检查点 MoritzLaurer/mDeBERTa-v3-base-xnli-multilingual-nli-2mil7，使用一个精确的上游版本。其准入测试样例涵盖英语、德语、法语、爱沙尼亚语，以及英语和爱沙尼亚语混合示例。这些证据仅限于这些示例，并不保证模型卡所列的每种语言都具有同等质量。其标签表示 NLI 关系：contradict、duplicate、refine 或 neutral。neutral 包含无关、相容和不确定的配对；它绝不表示“已证明无关”。

降级模式

默认情况下，可选层级不会安装，缺失时会静默降级，而不是使用替代方案。各层级中“缺失”的含义如下：

旧版 EXOMEM_* 名称（来自项目先前的工作名称 exomem）仍受支持：启动时，每个旧名称都会映射到对应的 EXOMEM_* 名称；如果同时显式设置了 EXOMEM_* 值，则优先使用该值。import exomem 和 python -m exomem 也仍可作为已弃用的别名使用。

仅限远程服务的变量和完整部署说明请参阅 docs/deployment.md。

项目状态

exomem 已发布到 PyPI，使用 Release Please 进行版本管理，并遵循 docs/release.md 中的轻量级 SemVer 策略。公开的 CLI 入口点是 exomem；kb 是用于日常知识库操作的简短别名。

许可证

AGPL-3.0-or-later。请参阅 LICENSE。