Mnemos

mnemos

为你的 AI Agent 赋予可引用的记忆。

为 AI Agent 提供本地记忆，并附带来源引用。

Claude Code 功能强大，但它会忘记你的项目上下文：

• 它会忘记你为什么否决某种架构，
• 它会漏掉你的 ADR，
• 它会不看文档就编造答案，
• 它无法可靠地引用某个说法的出处。

mnemos 通过提供以下内容的本地引用式记忆来解决这个问题：

• 你的 ADR 和设计文档
• 你的笔记和运行手册
• 你的源代码
• 你的 OKF 知识库

无需向量数据库。无需 Ollama。无需 Python 或 Node 服务。只需一个不依赖 cgo 的 Go 二进制文件，即可为你的文件建立索引——任何纯 Markdown 文件夹都能直接使用——并通过 MCP 提供服务，让 Claude 能够搜索、阅读并引用你自己的知识，而不是猜测；每个答案都会准确定位到 file#section 和行范围。

60 秒快速体验

# 1. install — one cgo-free binary into $GOBIN (requires Go 1.25+)
git clone https://github.com/arhuman/mnemos.git && cd mnemos
make install

# 2. index a project
cd ~/work/myproject
mnemos init                              # creates ./.mnemos/ (mnemos.toml, kb, db, models)
mnemos add docs --collection myproject   # copy a directory into the kb and index it
mnemos search "why did we choose this architecture"

建议使用 make build（→ ./bin/mnemos），避免将它放到 $PATH 中。默认构建为纯 Go，不依赖 cgo（CGO_ENABLED=0）。

search 会输出可供打开的引用：

1. security/scim.md#Provisioning
   lines 42-88
   score 12.7

然后将它接入 Claude Code（注意 --config 路径必须是绝对路径）：

claude mcp add mnemos -- mnemos serve --config /abs/path/to/myproject/.mnemos/mnemos.toml

现在 Claude 会基于你的项目作答，而不是猜测，并展示信息来源：

你： 如何恢复丢失的提交？

Claude： 根据 recovery/reflog.md，reflog 会记录 HEAD 和每个分支指针所指向的位置——即使执行了硬重置也一样——因此你可以检出丢失提交的哈希值。（recovery/reflog.md —“Reflog：恢复丢失的提交”）

整个流程就是这样——建立索引 → 提问 → 获取带引用的答案。 以下内容将深入介绍：为何采用这种设计、工作原理和完整的功能。

mnemos add ~/work/api/docs   --into api
mnemos add ~/work/infra/docs --into infra

mnemos origin add ~/work/spec --prefix spec --collection spec
mnemos origin reindex spec    # picks up new files, evicts deleted ones

• 真正的本地优先：完全在你的机器上运行。无需网络，不收集遥测数据，数据不会离开你的项目。
• 零依赖：单个自包含、无需 cgo 的 Go 二进制文件。无需 Python、Docker、Qdrant 或 Ollama。
• 适用于任何 MCP 客户端：专为 Claude Code 打造，也适用于任何支持 MCP 的工具。
• 答案附有引用：每个结果都链接到确切的 file#section 和行范围，因此可以验证其中的说法。
• 默认快速搜索：开箱即用 SQLite FTS5 / bm25；还可通过构建标签启用可选的本地语义搜索和混合搜索。
• 读写记忆：Agent 可以记录持久笔记（remember）；你可以管理树结构（forget、move、list）。
• 默认安全：除非你选择启用，否则仅限只读；写入操作受到路径限制，内容在加入索引前会进行密钥扫描（包括捕获和摄取，需由 exclude_secrets 控制）。

工作原理

your files  →  mnemos index (SQLite/FTS5)  →  Claude Code memory  →  cited answers

接入后，Claude 就能根据你的项目作答，而不是泛泛而谈，并指出信息来源：

• “我们为什么选择这种架构？”
• “规则引擎的 ADR 在哪里？”
• “总结一下我们对 SCIM 配置的了解。”
• “这个项目的记忆最近有哪些变化？”

在底层，该二进制文件内嵌了 MCP 服务、索引流水线、SQLite 存储、全文搜索、增量文件监视器和管理 CLI。请参阅 docs/architecture.md。

它真的能检索到内容吗？

开箱即用即可命中并附上引用（默认词法构建版本，使用随附的示例包）：

$ mnemos add examples/git-recipes/bundle --into . --collection git
$ mnemos search "recover lost commits" --limit 1
1. recovery/reflog.md#Gotcha
   lines 24-28
   score 7.8

每个结果都包含真实的 file#section 和行范围，你可以直接打开查看——这正是它的核心用途。

检索质量，实测结果。 mnemos eval 会从 OKF 包中自动生成留出查询→来源对（从每个示例块所属的文档中移除该块，然后检查检索是否仍能找到正确的文档），并报告文档级指标。在随附的 examples/git-recipes 包上（6 个配方，关键词式查询）：

这三项都是 [0,1] 范围内的分数（乘以 100 即为百分比）；数值越高越好。@K 表示检索深度——Hit 取前 1 个结果，其余指标取前 12 个：

• Hit@1 — 第 1 个结果为正确文档的查询占比（0.83 = 5/6）。
• Recall@12 — 正确文档出现在前 12 个结果中的任意位置的查询占比。
• MRR@12 — 平均倒数排名：对前 12 个结果中第一个正确文档的排名取倒数，再求平均值（1.0 = 总是排在第一位）。

默认词法构建版本已经能出色地完成关键词检索。可选的嵌入构建版本（见 语义搜索）则能胜任更难的自然语言查询，尤其是查询结构化数据时：在 examples/onpage-seo 包中，留出答案是与其说明文字没有任何关键词重合的 JSON-LD / sitemap-XML 块，词法检索得分为 0.00，而 --semantic 可达到 Hit@1 0.57 / Recall@12 0.86。 复现方法（N 分别为 6 和 7——仅供快速验证，不是基准测试）：

mnemos eval examples/git-recipes/bundle              # lexical → 0.83
make build-embed && mnemos models install all-MiniLM-L6-v2
mnemos eval examples/git-recipes/bundle --semantic   # hybrid  → 1.00
mnemos eval examples/onpage-seo/bundle --semantic    # the hard case → 0.57

连接 Claude Code

上面的 60 秒快速入门使用了带有绝对 --config 路径的 claude mcp add：

claude mcp add mnemos -- mnemos serve --config /abs/path/to/project/.mnemos/mnemos.toml

若要与仓库共享，请改用 .mcp.json 并将其提交：

{ "mcpServers": { "mnemos": { "command": "mnemos", "args": ["serve", "--config", "/abs/path/to/project/.mnemos/mnemos.toml"] } } }

使用 claude mcp list 验证（应显示 mnemos ✓ connected），并在会话中运行 /mcp。随后 Claude 会自动调用工具；请参阅功能。

若要使用位于另一台机器上的工作区，请通过 SSH 运行 stdio；mnemos 不会开启网络监听器。请参阅 docs/remote-access.md。

一条命令即可完成配置：Claude Code 显示 mnemos ✓ connected。

语义搜索：问题中提到了 “disappeared”，这个词在笔记中从未出现，但 Claude 仍找到了 recovery/reflog.md 并引用了它。

此片段使用了可选的语义构建版本（make install-embed + mnemos models install all-MiniLM-L6-v2 + use_vectors = true；请参阅语义搜索）。默认的 make install 二进制版本仅支持词法搜索，因此无法回答这类不含关键词的问题——请改用关键词搜索（例如 mnemos search "recover lost commits"，它会命中同一文档）。

让 Claude 自动使用记忆（可选技能）

MCP 工具是被动的：它们虽可用，但 Claude 仍须自行决定在回答前调用 mnemos.search，或在你提到值得保留的信息时调用 mnemos.remember，而模型往往不会这么做。捆绑的 mnemos-okf 技能通过规定何时调用记忆功能来弥补这一差距：回答基于假设的问题前先回忆、记录持久事实，并使用 OKF 工具。

它是可选的，且仅适用于 Claude Code：不安装该技能，服务也能与任何 MCP 客户端配合使用。将其安装到用户级别（适用于所有项目）：

make install-skill        # copies skills/mnemos-okf -> ~/.claude/skills/ and merges its hooks

也可以手动放置，例如仅在此仓库中使用项目级安装：

mkdir -p .claude/skills && cp -r skills/mnemos-okf .claude/skills/mnemos-okf

记录操作有意采取保守策略（仅记录持久事实，并扫描秘密信息），且受 allow_write/allow_delete 限制：技能绝不会授予配置未启用的访问权限。请参阅 skills/mnemos-okf/SKILL.md。

记忆循环

mnemos 是面向编码 Agent 的本地项目记忆：带引用的回忆、持久化项目状态、知识整合。

prompt
  -> recall (search first, cite)
  -> act
  -> capture durable facts to the inbox
  -> update project/task state
  -> consolidate raw captures into canonical docs
  -> cite everything

打包的 mnemos-okf 技能将其编码为六种模式：RECALL、CAPTURE、OKF、RESTORE、TASK 和 CONSOLIDATE。任务是按 mnemos task list 分组的 Task 文档。整合绝不会悄无声息地覆盖内容：冲突会被明确指出，每轮处理都会记录在日志中。

参考布局位于 examples/project-memory/bundle/，这是一个虚构项目，包含状态、约束、决策、任务（状态与历史分开存放）以及整合日志。导入它即可查看 mnemos task list 的实际效果：

mnemos add examples/project-memory/bundle --into aurora --collection aurora
mnemos task list

in_progress (1)
  aurora/tasks/rate-limit-ingest.md  Rate-limit the ingest endpoint
todo (1)
  aurora/tasks/csv-export.md  Add CSV export
done (1)
  aurora/tasks/fix-auth-timeout.md  Fix auth token timeout

使用钩子实现自动化

该技能仅提供建议：由模型决定何时触发各个模式。Claude Code 钩子可让记忆循环变得确定。make install-skill（或单独运行 make install-hooks）会以幂等方式将 skills/mnemos-okf/hooks/settings.example.json 合并到你的 ~/.claude/settings.json，并保留 .bak；传入 SKIP_HOOKS=1 可选择跳过，也可以手动将该文件合并到项目级 .claude/settings.json。以下三个钩子会被启用：

PreCompact 持久化（会话摘要、捕获内容刷新）仍由技能负责，因为该钩子事件无法向模型注入上下文。

连接 opencode

一个全局条目即可服务所有项目。将其添加到 ~/.config/opencode/opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mnemos": { "type": "local", "command": ["mnemos", "serve"], "enabled": true }
  }
}

也可以用幂等方式将其合并到现有文件中（需要 jq；仅支持普通 JSON，不支持 JSONC）：

f=~/.config/opencode/opencode.json
[ -f "$f" ] || echo '{"$schema":"https://opencode.ai/config.json"}' > "$f"
jq '.mcp.mnemos = {type: "local", command: ["mnemos", "serve"], enabled: true}' "$f" > "$f.tmp" && mv "$f.tmp" "$f"

运行 opencode mcp list 验证（应显示 ✓ mnemos connected）。

这里无需使用 --config，与 Claude Code 不同：opencode 会在项目目录中启动本地 MCP 服务，因此直接运行 mnemos serve 时，如果项目中存在 .mnemos/，就会为其提供服务；否则会回退到 ~/.mnemos。有两种情况会覆盖此发现行为，因为 opencode 会将整个环境传递给服务：导出的 $MNEMOS_DIR 或 $CLAUDE_PROJECT_DIR 会将所有项目固定到同一个工作区。如需刻意为某个固定工作区提供服务，可在 command 中添加 "--mnemos-dir", "/abs/path/.mnemos"（opencode 不会展开 ~）。工具会显示为 mnemos_mnemos_search 等名称，因为 opencode 会替换工具名称中的句点。

功能

Claude 通过 MCP 工具访问你的记忆（你也可以通过对应的 CLI 命令访问）。请注意拼写：mnemos.search 是 Claude 调用的 MCP 工具；mnemos search 是你运行的 CLI 命令。

查询（只读，无需门控）

• mnemos.search：支持排序、筛选并附带引用的检索。
• mnemos.read：读取精准片段（通过 chunk_id）或完整文档（通过 uri）。传入 follow_links: true，还会附加该文档一跳范围内的链接邻居。
• mnemos.context：将 top-k 结果作为适合大模型的上下文块（uri:start-end → 内容）返回。传入 follow_links: true，会附加每个上下文块所属文档一跳范围内的链接邻居。
• mnemos.related：返回文档在链接图中的邻居、其出站链接和入站反向链接（1 跳，文档级别）。悬空的出站目标会以 resolved: false 返回。可通过 direction（outbound/inbound/both）和 limit 筛选。
• mnemos.list：遍历磁盘上的 OKF 树，并为每个文件标注索引元数据（标题、类型、标签、集合）以及 indexed 标记，因此无论文件是否已存储或尚未编入索引，都会显示。可按 path、collection、type 或索引状态筛选。
• mnemos.journal_pending：按时间从早到晚列出尚未审核的会话日志条目。日志条目不会纳入搜索；CONSOLIDATE 会通过此工具查找它们。

写入（需要 allow_write = true）

• mnemos.remember：将笔记写入记忆。可选传入 path（例如 "adr/0003-rule-engine.md"），将笔记放在 OKF 树中的指定位置，而不是在 kb/capture/ 下自动命名。写入和编入索引前，内容会经过机密信息扫描。
• mnemos.okfy：将树中已有的 .txt/.md 文件转换为 OKF 文档（frontmatter + 正文），写入 out（默认为源路径加 .md 扩展名）并编入索引，同时保留源文件。首先会对源文件正文进行机密信息扫描。
• mnemos.journal_promote：记录某条日志已审核，并将其 promoted_to 设为当前保存其内容的知识库文档（先通过 mnemos.remember 写入），或设为 none。它本身不会写入知识库文档；已添加标记的条目会被拒绝。

mnemos edit <uri> 是供人类使用的对应功能：通过终端编辑单个文档，受同一 allow_write 标记控制，但没有对应的 MCP 工具。请参阅交互式编辑文档。

管理（需要 allow_delete = true）

• mnemos.forget：从 OKF 树中删除文件并取消其索引；可重复执行。
• mnemos.move：在树中移动文件或目录，并在新路径下重新编入索引。移动目录时会移动其整个子树，并保留每篇文档的集合。V0 中不会重写指向旧路径的入站 Markdown 链接（会记录为警告）。

日志也有对应的命令行工具：mnemos journal pending 会列出尚未审核的条目，mnemos journal promote <entry-uri> <target|none> 会为某条条目添加标记（需要 allow_write），mnemos journal prune --older-than 30d 会列出超过指定期限的已审核条目，使用 --apply 可删除它们（需要 allow_delete）。尚未审核的条目绝不会被清理。

保持记忆内容最新

运行监视器以便在更改时重新编入索引（增量更新；会移除已删除的文件）：

mnemos watch . --collection myproject

在 .mnemos/mnemos.toml 中启用回写功能，以便 Claude 能够捕获和管理笔记：

[mcp]
allow_write = true     # gates mnemos.remember and mnemos.okfy
allow_delete = true    # gates mnemos.forget and mnemos.move

如果有监视器正在监视该目录树，forget/move 操作也会被监视器检测到（重复执行但可安全幂等）；这些工具会直接更新索引，无需监视器也能正常工作。当监视器监视 kb/capture/ 时，设置 [capture] defer_to_watcher = true，以避免对记忆笔记重复编入索引。

交互式编辑文档

mnemos edit <uri> 会打开终端编辑器，一次编辑一份 OKF 文档， 界面分为三个窗格：

• NAV：文档的出站链接、入站反向链接，以及（嵌入构建已为语料库计算嵌入后）语义相似的文档；否则，该区域会显示不可用提示，而不显示结果。
• METADATA：文档的 frontmatter 字段，按文档的 OKF type 进行类型处理。已知枚举值（例如任务的 status 或 priority）可用方向键循环切换，tags 会作为完整列表重新输入，未知字段则回退为自由文本，type 等由索引管理的字段为只读。
• CONTENT：正文；编辑时会交由 $EDITOR，退出后重新载入。

mnemos edit tasks/ship.md

按键：tab 聚焦，↑↓ 移动，enter 打开／编辑，←→ 切换枚举值，e $EDITOR，m 移动／重命名，s 保存，b／backspace 返回，q 退出。保存时会先写入文件，再仅重新索引该文档，因此即使重新索引失败，编辑内容也不会丢失；写入 frontmatter 时会保留文件其余部分（注释、键顺序、无关字段），而不是重写整个文件。 当前文档尚未保存时，若导航到另一份文档，会先保存当前文档。

m 可移动或重命名当前打开的文档。系统会以当前 uri 作为提示： 可直接修改，也可按 tab 打开模糊筛选选择器，选择已有文档的目录（enter 会将文件名移至所选目录下，esc 返回提示）。确认后会在磁盘上重命名文件，按新 uri 重新索引，并在新位置重新打开编辑器；仍指向旧路径的入站链接会被报告，但不会重写。和 mnemos mv 一样，由于会删除旧索引条目，因此需要设置 [mcp].allow_delete = true。

此命令需要 uri：直接运行 mnemos edit 会报错，目前还没有用于浏览目录树的选择器。其权限控制方式与 mnemos.remember／mnemos.okfy 相同：

[mcp]
allow_write = true   # also gates mnemos edit

没有对应的 MCP 工具：mnemos edit 仅供使用键盘操作的用户通过 CLI 使用。

语义搜索（可选）

默认二进制文件仅支持词法搜索（FTS5／bm25），体积小且不依赖 cgo。 本地语义检索与混合检索已完整实现，但编译时需启用 embed 构建标签，因此 ONNX／分词器依赖不会进入默认二进制文件。启用方法：

make build-embed                       # or: make install-embed  (still cgo-free, CGO_ENABLED=0)
mnemos models install all-MiniLM-L6-v2 # downloads the embedding model into ~/.mnemos/models
mnemos reindex --embeddings            # compute vectors for already-indexed chunks
mnemos search "why did we choose this architecture" --semantic

--semantic 会融合 bm25 与向量相似度，因此词法索引无法命中的自然语言查询也能找到结果。如果未启用 embed 构建（或未安装模型），该标志会被拒绝并显示明确提示；普通的 mnemos search 始终可用。

底层实现原理（模型、纯 Go ONNX 推理、RRF 融合）： docs/architecture.md。

OKF 支持

mnemos 原生支持 OKF （开放知识格式）包，也支持任何带有 YAML frontmatter 和交叉链接的 Markdown 知识库，无需特殊模式：

• frontmatter 中的 tags／type 会成为 FTS 的模糊排序信号；
• Markdown 链接会被捕获为边并进行遍历：mnemos related（以及 mnemos.related 工具）会遍历文档的出站链接和入站反向链接， follow_links 会将它们附加到读取或上下文调用中，而 [search] graph_expansion = true 会用排名靠前结果的 1 跳邻居填充空结果位置；
• index.md 文件仅作为结构处理（不会纳入 FTS 或链接图）。

OKF 包也可用作 mnemos eval 的语料库；该命令会自动生成留出的查询→来源配对，并根据已提交的基线报告 Hit@1／Recall@12／MRR@12。参见 docs/architecture.md。

参考

• docs/commands.md — 所有 CLI 命令及其标志。
• docs/configuration.md：分层配置 <MNEMOS_DIR>/mnemos.toml，包含所有默认值。
• docs/paths-and-indexing.md — 状态的定位方式、索引内容、写入位置，以及幂等性和 URI 规则。
• docs/architecture.md — 设计原则和检索评估方法。
• docs/remote-access.md：通过 SSH 使用另一台机器上的工作区、限制密钥，以及为何没有 HTTP/SSE 传输。

安全

• 不联网、不遥测；MCP 服务仅使用标准输入输出。
• 随附的二进制文件带有 SBOM（使用 syft 生成），并使用 cosign 签名（无密钥 OIDC）。
• 默认只读。回写需显式启用（allow_write = true）。破坏性操作（forget、move）需要单独显式启用（allow_delete = true）。
• 在执行任何磁盘操作前，所有调用方提供的路径都会经过边界防护检查：.. 遍历、树根目录之外的绝对路径、符号链接逃逸、访问 .mnemos/，以及 [security].exclude glob 均会被拒绝。
• 已注册的外部来源为只读：每个写入动词都会拒绝指向已注册命名空间的 URI，并指出所属来源。对于已注册来源之外的所有路径，防护规则保持不变，因此未注册的符号链接逃逸仍会像之前一样被拒绝。
• 内容在建立索引前会进行秘密扫描，覆盖捕获路径（ remember、okfy，遇到秘密会拒绝）和摄取路径（ingest、add、 watch、reindex，会跳过文件并警告匹配的规则，同时继续运行）。设置 [security] exclude_secrets = false 可禁用此功能。
• 路径/秘密排除模式会将 .env、密钥和秘密目录排除在索引之外。

完整策略请参阅 SECURITY.md。

开发

make build      # cgo-free binary -> bin/
make test       # go test -race ./...
make audit      # golangci-lint (incl. govet + staticcheck) + govulncheck + race tests
make tools      # install pinned dev tools (golangci-lint, govulncheck)
make help       # list all targets

架构、设计原则和检索评估方法见 docs/architecture.md；设计决策记录在 ADR 中。欢迎贡献；请参阅 CONTRIBUTING.md。

许可证

mnemos 根据 MIT License 授权：该许可证涵盖 mnemos 自身的代码 和内容。仓库还包含第三方材料，这些材料不受 MIT License 涵盖，并继续遵循各自的条款；请参阅 THIRD-PARTY-NOTICES.md（尤其是示例 OKF bundle，位于 examples/onpage-seo/bundle/）。