memory-find

memors-mcp

一个本地 MCP 服务，为 Agent 提供可衡量、可解释的知识库：一个 Go 二进制文件，无云服务，无 CGo，每个知识库对应一个 SQLite 文件。文档和事实连同来源信息一起存入；搜索结果则以一个排序列表返回，涵盖四种检索方式，每条结果都包含其地址、可信度以及排名依据。用户可以在终端中读取同一知识库，也可以将其导出为 Markdown。

它最初是 obra/private-journal-mcp 的 Go 重写版，并于 2026-10 从头重建为知识库。1.0 版明确了契约：工具名称和参数、memo:// 地址、解释字段以及导出格式。搜索的决策方式记录在 docs/architecture.md 中；研究层（图谱、压缩、Web 界面）的规划见 docs/roadmap.md；相关研究见 docs/knowledge-base-sota.md。

功能

Claude（或任何 MCP 客户端）可通过一个知识库使用十种工具：

工具	用途
ingest	将 Agent 获取或撰写的文档以 Markdown 格式存储；内容相同则不执行任何操作，内容变更或出现新版本时则创建新修订版
search	按词语、精确标识符和含义查找段落，并融合为一个列表；response_format: explain 会说明每条结果的排名原因
read	解析 memo:// 地址：读取一个段落、其所在章节，或在令牌预算范围内读取整篇文档
remember	记录一条带有证据和有效日期的原子事实；要更正事实，请传入 supersedes，旧事实会保留为历史记录
forget	以指定理由将文档或事实标记为退役；它会从所有索引中移除，其地址会解析为“因……于……被遗忘”。工具调用只能将工具写入的记录标记为退役
promote	请求提高记录的可信度；工具调用本身无法执行此操作。能够显示对话框的客户端会直接询问用户（提供摘录、来源和目标级别）；其他客户端则会返回由用户执行的命令
explore	从一个指定事物开始遍历图索引：查找提及它的段落及与其一同提及的事物，并提供各自的证据地址
compact	提出整理建议：值得建立页面的实体、过时页面、相互矛盾的事实、近似重复的名称和段落。每项都包含所需的段落和事实；服务绝不会写入页面
submit	提交页面、冲突处理决定或合并决定。页面会作为派生内容（is_inference）存储，并附上引用的段落；遗漏检查会报告页面未包含的事实；dry_run 可先显示差异
status	显示命名空间、嵌入模型、待处理向量、后台任务、图和页面的数量

在 macOS 上，可选的菜单栏应用 MemoRS Tray（位于 tray/，是一个独立二进制文件，也是唯一使用 cgo 构建的部分）会显示连接到各个 memors-mcp serve --http 服务的客户端，在窗口中打开服务的 Live 页面，并启动和停止服务。其设置助手会从 GitHub releases 下载、验证并安装 memors-mcp，并设置首个知识库；设置窗口则涵盖其余选项（登录时启动、服务、嵌入模型）。请参阅 docs/guide/user/menu-bar.md。

用户可运行 memors-mcp ui，打开一个仅限环回地址访问的只读网页，其中包含相同的搜索功能（以及 Agent 可查看的相同解释表）、带有来源信息和历史记录的文档与段落、事实时间线、实体邻域、Agent 撰写的页面、状态、lint 和查询日志。网页上的任何操作都无法更改知识库。

相同的地址也可作为 MCP 资源读取（memo://doc/{id}、memo://chunk/{id}、memo://source/{id}、memo://fact/{id}）；memo://index 或 memo://ns/{namespace}/index 则会提供每篇文档一行的视图，大小不超过 8 KB，适合在会话开始时使用。MCP 提示词 ask 可将对话转变为围绕知识库进行的聊天：客户端模型根据搜索和读取的内容作答，并为每条主张引用其 memo:// 地址（在 Claude Code 中：运行 /mcp__memors__ask，然后照常提问）。SKILL.md 会指导 Agent 如何有效使用这些工具；memors-mcp export --index 会输出相同的索引，供 AGENTS.md 或 CLAUDE.md 文件使用。

所有内容都存储在本地。整个系统恰好只有一次对外网络调用：首次启动时从 Hugging Face 下载嵌入模型。此后，任何内容都不会离开这台机器。服务绝不会获取 URL；由 Agent 获取并传入文本。

搜索的工作原理

search 会在同一组预筛选的有效段落上运行最多三个检索分支，并融合结果：

• 关键词分支——使用 Porter 词干提取器和 BM25 评分的 SQLite FTS5，检索段落及其章节标题。“review”可以找到“reviewing”。
• 精确分支——第二个 FTS5 索引，会将标识符作为整体保留（useCallback、net/http、ERR_CONN_RESET）。查询看起来像代码时会自动启用。
• 语义分支——使用配置的模型（默认为 granite-small-r2，即 IBM granite-embedding-small-english-r2，384 维，通过 hugot 的纯 Go ONNX 后端在本地运行）对查询和每个段落进行嵌入，并在普通 SQLite 表中按余弦相似度进行比较。memors-mcp model ls 会列出其他选项，包括即时静态模型 potion。

三个排序列表以相同权重进行倒数排名融合（关键词结果排第 1 与向量结果排第 1 得分相同，因此关键词分支可以增加结果，而不只是调整顺序）；然后按每个文档中得分最高的段落聚合段落；笔记和对话会获得有限的时效性加成（×0.8 至 ×1.0，每 90 天减半；有版本的文档不会随时间衰减）；在第一个较大的分数差距处截断列表；最后按请求的令牌预算打包结果。如果某段落唯一的依据是低于弱相关区间（0.30）的语义相似度，就会将其丢弃。因此，对于语料库中没有内容的问题，系统会返回零条结果及原因和提示，而不是一页无关内容。

当问题提及两个或更多已知事物，或询问事物之间的关系时，两个结构分支会加入：实体分支会返回提及所指实体的段落；图谱分支会从每个所指实体开始，以个性化 PageRank 遍历提及图谱，并返回所有遍历结果一致指向的段落。这就是为什么询问 Billing Service 时，能找到从未提及它的复制页面。explore 会手动遍历同一图谱。两者采用路由选择，而非始终启用，因为始终启用实体分支会降低普通查找的效果。

精心整理的页面是第三种可搜索内容（granularity: page）：Agent 通过 compact 和 submit 根据段落编写的 Markdown，作为衍生内容存储，并引用其来源段落；只要其中一个段落所属的文档被修订或遗忘，页面就会立即标记为过时。

第四个文本分支会匹配通过 remember 记录的事实，并为其依据段落投票（“将事实作为额外键”）；granularity: fact 会直接返回事实。as_of 会根据某个日期回答知识库当时所认定的内容：那时仍有效的已被取代的修订和已被替换的事实。被遗忘的记录永远不会返回，即使使用 as_of 也是如此。范围筛选器（命名空间、类型、来源、库、版本、标签、日期、最低可信度）会在每个分支的查询中、排序前应用，因此筛选后的搜索不会遗漏结果。每条结果都附带其来源信息和相关度区间；使用 response_format: explain 时，还会附带各分支的排名和贡献、时效性系数，以及每次查询的追踪信息（运行了哪些分支及原因、范围筛选排除了什么、列表在哪里被截断）。终端会显示相同的数据：memors-mcp search "<q>" --explain 和 memors-mcp explain "<q>" memo://chunk/<n>。

存储

每个 MEMORS_KB 名称对应一个 SQLite 文件，位于 ~/.memors-mcp/kb/<name>.db（如果设置了 $MEMORS_HOME，则位于 $MEMORS_HOME/kb/）。memors-mcp 创建的目录和文件仅限所有者访问（0700/0600）；已有目录如果权限范围更广，则不会收紧。已启用 WAL 模式，因此两个进程访问同一个令牌（例如，两个并发的 Claude Code 会话）时不会冲突。

名称需显式指定，而不是根据工作目录推断——在 MCP 服务配置中（而非 shell 中）按项目设置 MEMORS_KB，每个项目都会获得独立的知识库。在同一个文件中，命名空间相当于书架，搜索默认会跨命名空间进行；不同文件则构成隐私边界。

设置

使用发布版本。 从 releases 下载适用于你平台的压缩包，解压后将 memors-mcp 放到 PATH 中的某个位置，然后运行 memors-mcp version。macOS 和 Linux（amd64、arm64）以及 Windows（amd64）均提供压缩包。该服务也已列入 MCP 注册表，名称为 io.github.kKEo/memors。

从源代码构建。 需要 Go 1.26+。

git clone https://github.com/kKEo/memors
cd memors
make build

这会生成一个独立的 memors-mcp 二进制文件（CGO_ENABLED=0，约 30MB，无运行时依赖）。

使用 Claude Code：

claude mcp add memors --env MEMORS_KB=my-project -- /path/to/memors-mcp

将其添加到 Claude Code 或 Claude Desktop 的 MCP 配置中：

{
  "mcpServers": {
    "memors": {
      "command": "/path/to/memors-mcp",
      "env": {
        "MEMORS_KB": "my-project"
      }
    }
  }
}

首次启动时，memors-mcp 会将默认嵌入模型（granite-embedding-small-english-r2，Apache-2.0，约 140MB）下载到 ~/.cache/memors-mcp/models，并向 stderr 输出一行信息。模型就绪前，搜索仅使用关键词，并会说明这一点（degraded）；期间写入的文档会在模型下载完成后生成向量。若要提前下载，请运行 memors-mcp model pull granite-small-r2。如果下载中断，程序会检测到并在下次运行时重试。

命令

不带参数运行二进制文件会通过 stdio 启动 MCP 服务。在终端中：

• memors-mcp ingest <file|dir|-> [--ns --kind --uri --title --library --version --trust --context --embed=false] — 添加 Markdown 文档；内容相同则不执行任何操作，内容变更则创建新修订
• memors-mcp search "<query>" [--mode auto|hybrid|keyword|exact|semantic --ns --library --version --kind --limit --format table|json|md --explain --no-model] — 搜索；--explain 会补充每条结果排名靠前的原因
• memors-mcp explain "<query>" <memo://chunk/n> — 查看单条结果的完整解释
• memors-mcp log tail|calls|show <id>|replay|prune — 查看可选启用的查询和调用日志（MEMORS_QUERY_LOG=1）；calls 列出工具调用的耗时和结果；replay 将记录的搜索打印为未标注的评估候选项（每行一个 JSON 对象），可直接添加标签并加入语料库
• memors-mcp metrics [--json --since 24h] — 查看知识库指标及可选启用的日志中各工具的调用统计
• memors-mcp remember "<fact>" [--ns --about --valid-from --valid-to --supersedes --evidence --trust user|curated] — 记录事实（CLI 写入的信任级别为 user；curated 必须手动指定）
• memors-mcp forget <memo://...> --reason "<why>" [--redact] — 使文档或事实失效；原因会保留并显示
• memors-mcp facts ls [--ns --as-of YYYY-MM-DD --history] — 列出事实，或查看某个日期时已知的事实
• memors-mcp trust ls | promote <uri> --to user|curated | demote <uri> --to agent|user — 用于管理信任级别的人工操作渠道；每次变更都会记录审计信息
• memors-mcp explore <name> [--ns --hops 1|2 --as-of --json] — 从某个实体遍历图索引：查看相关段落、与其一同提及的实体及证据地址
• memors-mcp graph merges [--state open|merged|rejected|all] | merge <id> | reject <id> | rebuild [--ns] — 查看近似重复实体名称的审核队列（未经人工决定不会合并）；rebuild 会重新提取图层之前或提取方式变更后写入的文件中的提及
• memors-mcp compact [--ns --kinds page,stale,conflict,merge,duplicate --lint --json] — 提议精简工作；--executor ollama [--apply] 使用本地模型写入页面项（MEMORS_OLLAMA_URL、MEMORS_OLLAMA_MODEL；默认仅试运行，除非指定 --apply）
• memors-mcp submit <item-id> [--content-file page.md | --keep <memo://fact/..> | --accept|--reject | --skip] [--reason ..] [--dry-run] — 人工处理工作项
• memors-mcp lint [--ns] — 检查矛盾、孤立实体、缺失或过时的页面及过期事实；不会更改任何内容
• memors-mcp pages ls [--ns --stale] — 列出已整理的页面
• memors-mcp read <memo://doc/...> [--history] — 打印文档、片段、来源或事实及其出处，或查看其修订链
• memors-mcp ls [--ns --kind --since --json] — 按时间倒序列出有效文档
• memors-mcp export --md <dir> [--ns] — 导出带有来源前置信息的 Markdown 文件（可在 Obsidian 中打开；重新导入不会产生新修订）
• memors-mcp export --index [--ns --library x@v --max-bytes 8192] — 打印精简索引（每份文档的标题、地址、类型、版本和信任级别；事实以摘要形式呈现），适合写入 AGENTS.md/CLAUDE.md；页脚会统计未能容纳的行数
• memors-mcp migrate — 将旧版二进制写入的文件迁移到当前架构（status、ui 和 search 等只读命令会拒绝处理过期文件并提示迁移）
• memors-mcp verify [--repair] — 检查片段、向量和索引
• memors-mcp backfill — 为向量尚未生成的片段生成向量
• memors-mcp status — 打印知识库统计信息（只读；绝不会创建文件）
• memors-mcp ui [--addr 127.0.0.1:0 --no-model] — 只读 Web 界面：可查看带解释表格的搜索结果、带出处和历史记录的文档与段落、事实时间线、实体邻域、带来源的页面、状态、lint 结果、查询日志及评估报告。除非指定 --allow-remote，否则仅限环回地址；不提供任何修改数据的路由

实验室：

• memors-mcp eval [--models hash,minilm,potion,granite-small-r2 --profiles default,all --corpus notes|kb|all --format table|md|json --explain-failures --rerank --agent-proxy] — 使用每个模型将固定测试语料加载到临时知识库，在每个配置下运行带标签的查询，并并列输出质量指标（召回率、MRR、nDCG、拒答率）和成本指标（延迟、令牌数）。hash 是确定性测试嵌入器；其他 ID 会下载真实模型。
• memors-mcp model ls | smoke <id>|--all | pull <id> | use <id> | redownload [<id>] — 嵌入模型注册表：列出带许可证的候选模型，验证哪些模型可在纯 Go 后端加载及其速度，下载模型，或将某个模型设为知识库的默认模型。
• memors-mcp reindex [--model <id>] — 为所有缺少某个模型向量的段落生成嵌入（“重新嵌入，不要重新分块”）；多个模型的向量可以共存，因此切换回来无需付费。
• memors-mcp profiles show [<name>] — 输出某个配置的所有排名常量及其推导方式。配置包括：default、precise（更深度的获取，并在连接交叉编码器时进行重排）、recency、code、minmax（使用分数融合而非排名融合），以及消融配置 keyword-only、semantic-only。覆盖项位于 $MEMORS_HOME/profiles.json。
• memors-mcp version — 输出构建版本、MCP 协议版本、Go 版本和模型目录
• memors-mcp model redownload — 强制重新下载模型，丢弃任何缓存副本后退出

旧写法 --stats 和 --redownload-model 在一个版本周期内仍可使用，并会输出弃用警告。

环境变量

变量	必填	用途
MEMORS_KB	否	选择要打开的数据库；文件路径为 $MEMORS_HOME/kb/<name>.db。仅允许字母、数字、.、_、-。默认为 default。
MEMORS_HOME	否	基础目录（默认值为 ~/.memors-mcp）
MEMORS_QUERY_LOG	否	设置为 1 时，在同一文件中保留一份可选的搜索日志（参数、结果地址、分数、跟踪信息；绝不记录段落文本）
MEMORS_MODEL	否	来自 memors-mcp model ls 的嵌入模型 ID（默认值为 granite-small-r2）。查询使用该模型的向量；切换后请运行 memors-mcp reindex
MEMORS_PROFILE	否	排名配置（默认值为 default）；参见 memors-mcp profiles show
MEMORS_OLLAMA_URL、MEMORS_OLLAMA_MODEL	否	memors-mcp compact --executor ollama 使用的可选本地模型；除非指定 --allow-remote，否则仅允许环回地址。其他操作不会使用它
MEMORS_METRICS_ADDR	否	与 serve --metrics-addr 相同：在 http://<addr>/metrics 暴露 Prometheus 指标。仅允许环回地址；为空时关闭
MEMORS_LOG_FORMAT	否	text（默认值）或 json；在 stderr 上输出结构化日志
MEMORS_LOG_LEVEL	否	debug、info（默认值）、warn、error
MEMORS_RERANK	否	设置为 1 时加载交叉编码器重排器（cross-encoder/ms-marco-MiniLM-L6-v2，Apache-2.0，约 91 MB）；仅启用重排的配置（precise）会使用它

可观测性

所有内容都保留在本机。指标通过回环地址拉取，日志写入服务器的 stderr，可选的调用日志存储在你自己的 SQLite 文件中。

• 指标。 memors-mcp serve --metrics-addr 127.0.0.1:9469（或 MEMORS_METRICS_ADDR）以 Prometheus 文本格式提供 GET /metrics：按工具和结果统计工具调用，并提供延迟和结果大小直方图；按模式和结果统计搜索，并提供各搜索分支的延迟和候选项数量；还包括弃答次数、降级搜索次数、截断类型、图缓存命中次数、按模型和角色统计的嵌入延迟、按操作统计的存储写入次数，以及每个表的计数指标（memors_kb_documents_live、memors_kb_pages_stale、memors_kb_pending_embeddings{model}，……）、Go 运行时统计信息和 memors_build_info。该端点拒绝非回环地址，只响应 GET，并检查 Host 标头。UI 也会提供自己的 /metrics。注册表约 300 行标准库代码，因此仪表板可以读取它所依赖的每一行；名称遵循 Prometheus 约定，并与 OpenTelemetry 名称一一对应，以便将来需要时使用桥接器。
• 日志。 通过 stderr 使用 log/slog，并可设置 MEMORS_LOG_FORMAT=text|json 和 MEMORS_LOG_LEVEL。每次工具调用记录一行（工具、客户端、延迟、结果、错误类别、结果、令牌），每次搜索记录一行（模式、已解析的搜索分支、截断、降级原因、延迟）。MCP logging 能力不会对外声明：服务器所使用的协议版本已弃用此能力，而且 Claude Code 无论如何都会显示 stdio 服务的 stderr。
• 调用日志。 设置 MEMORS_QUERY_LOG=1 后，每次工具调用和搜索都会记录：memors-mcp log calls、memors-mcp log tail、UI 的 /log 页面。参数会通过允许列表进行摘要；写入的内容和返回的文本绝不会被存储。
• 快照。 memors-mcp metrics [--json] [--since 24h] 会输出表计数指标；如果启用了可选日志，还会输出各工具的调用次数、错误数和 p50/p95 延迟，以及搜索汇总信息。实时计数器按进程统计，因此它会说明抓取这些指标的位置。

MEMORS_LOG_FORMAT=json memors-mcp serve --metrics-addr 127.0.0.1:9469 2> memors.log
curl -s http://127.0.0.1:9469/metrics | grep memors_mcp_tool_calls_total

与 Claude Code 内置记忆的区别

Claude Code 自带记忆功能（Auto Memory，以及供自定义 Agent 使用的 API 级文件记忆工具）。这些都是不错的默认选项，对大多数人来说，或许也是合适的选择。

memors-mcp 则有所不同：它是一个轻量、完全本地且完全可读的检索系统，你可以检查和衡量它，而不必面对黑箱。每个排序常量都是一个具名配置字段，并附有书面推导过程（memors-mcp profiles show）；每条结果都可以说明自己的排名依据（response_format: explain、memors-mcp explain）；每条记录都会注明来源以及背书者；internal/eval/ 中的评估框架会记录一个基准，每次变更都要按查询逐项与之对比。如果你想了解记忆系统为何会返回某些结果，或者想用自己的数据试验检索策略，这就是它的用途。

进一步阅读

• 用户指南：用通俗易懂的英语介绍 memors-mcp 的用途、十分钟快速入门和日常使用。
• 运维指南：安装、配置参考、检索调优、使用 Prometheus 监控、备份和故障排查。两份指南均由 .github/workflows/docs.yml 发布到 GitHub Pages；make docs 可在本地构建。
• docs/architecture.md：各层、写入和读取路径、公式、配置文件、解释约定和地址方案。
• docs/schema.md：以通俗语言介绍每张表和每个列、信任级别转换，以及 as_of 能看到的内容。
• docs/eval/：每个标签对应一份实测报告。
• articles/：每个阶段一篇面向初学者的文章：为什么要重建而不是迁移、设计知识架构、会自我解释的搜索、嵌入器是最关键的杠杆、来源、信任与时间、为 Agent 设计工具、发布纯 Go MCP 服务、将图谱用作索引，而非神谕。
• articles/compaction-without-a-server-llm.md：Agent 如何编写 Wiki，以及服务如何确保内容可靠。
• articles/a-knowledge-base-you-can-read.md：只读 Web 界面，以及它的数字为何与 Agent 使用的数字一致。
• articles/measuring-the-server-itself.md：不使用遥测的指标和日志。
• CHANGELOG.md。

这些文章、评估报告和技术探索笔记是在项目更名为 memors 之前编写的，因此使用了旧名称（memo-mcp、memo-tray、MEMO_*、~/.memo-mcp）；memo:// 地址未作更改。

隐私

• 所有处理都在本地进行——嵌入在进程内运行，搜索在 SQLite 中运行。
• 首次下载模型后，不会进行网络调用。
• 无遥测、无分析、无外部日志记录。指标和日志虽存在，但仅在本地：/metrics 绑定到回环地址且仅供拉取，日志写入 stderr，可选择启用的调用日志存储在你自己的 SQLite 文件中。
• 源代码足够精简，可完整阅读；没有混淆或压缩。
• 提高信任级别需要人工确认。promote 使用 MCP 征询：客户端会显示一个对话框，其中包含摘录、来源和目标级别，只有确认对话框后才会应用更改。会自动接受征询对话框的钩子或设置会取消这项保护；如果配置了这类功能，请不要认为 user 和 curated 记录比 agent 记录更可信。
• 有两点需要注意：知识库是纯文本 SQLite 文件，任何能访问你主目录的人都能读取；模型写入或搜索的所有内容都会作为工具输入经过 MCP 主机，因此其隐私程度取决于该主机。若嵌入模型不可用，搜索会仅使用关键词并说明此情况（degraded）；在此状态下写入的文档会在运行 memors-mcp backfill 或下次启动服务时生成向量。

项目状态

1.0 版本：核心知识库已完成并经过测量。稳定内容，以及 1.x 新增的功能（将图谱用作索引、压缩和页面、只读 Web UI、本地可观测性），详见 docs/roadmap.md。暂无计划：服务端大模型、导入 v0 日志文件。欢迎贡献和提交问题。

许可证

MIT——详见 LICENSE。基于 obra/private-journal-mcp 衍生，该项目同样采用 MIT 许可证。