Thoth-Mem

面向 AI 编码智能体的持久内存

为编码智能体提供跨会话、上下文压缩和上下文重置的持久项目记忆。

Thoth-Mem 是一个本地优先的 MCP 服务器，后端由 SQLite 和 FTS5 提供支持。它保存有用的决策、问题修复、约定和会话连续性，然后只检索智能体所需的证据。同一个安装还提供 CLI、可选的 HTTP API，以及对受支持编码工具（coding harnesses）的原生生命周期集成。

全局作用域管理当前用户的工具配置；项目作用域是显式的，并且仅限定在所选项目及其回执树（receipt tree）内。Engram、thoth-agents 或其他记忆集成可能存在重叠；请仅将其视为一个警告：thoth-mem 不会编辑、禁用、移除或写入外部仓库。

快速开始

需要 Node.js 18 或更高版本。原生设置是可选的：手动 MCP 连接只需要 mcp 命令。

运行已发布版本

无需安装全局命令即可启动最新发布的 MCP 服务器：

npx -y thoth-mem@latest mcp

这会启动 MCP 服务器及其本地 HTTP 桥接。当只需要 MCP 传输时，请添加 --no-http。新的客户端配置应使用显式的 mcp 子命令。

原生集成在设置完成之后会调用持久化的 thoth-mem 命令，因此在配置某个工具之前，请先在全局安装或更新该命令。使用 npx 从最新发布版本运行 setup 的实现、检查其零写入计划，然后应用它：

npx -y thoth-mem@latest setup codex --scope global --plan --json
npx -y thoth-mem@latest setup codex --scope global --json

对于其他受支持的工具，请将 codex 替换为 opencode 或 claude，然后重启该工具。单独运行 setup 不会安装或更新 npm 包。

安装此仓库

请使用仓库流程来测试尚未发布的提交：

pnpm install
pnpm run build
pnpm add -g .
thoth-mem version
thoth-mem setup codex --scope global --plan --json
thoth-mem setup codex --scope global --json

thoth-mem@latest 只包含最新的已发布版本。拉取较新的未发布提交后，请重新构建并重新运行 pnpm add -g .。

更新现有安装

先更新包。如果之前安装了原生集成，请重新运行其设置，使已复制的资源、技能、钩子和受管声明与新的包版本保持一致：

pnpm add -g thoth-mem@latest
npx -y thoth-mem@latest setup codex --scope global --plan --json
npx -y thoth-mem@latest setup codex --scope global --json

然后重启工具或 MCP 进程。手动 MCP 用户不需要 setup；重启 npx -y thoth-mem@latest mcp 即可。

设置会保留记忆数据库和用户拥有的配置。启动时，缺失的配置字段可能会被回填，但显式的值（例如 LM Studio 模型）仍然是订阅的一项配置。配置格式保持为 "version": 1。对于某次发布安装，请将较旧的 $schema 手动更新为该发布版本的 URL，以获得当前编辑器校验和自动补全。未发布的工作副本必须使用本仓库的 config.schema.json，因为 unpkg 在版本发布前无法公开该变更。schema URL 不会影响运行时迁移。

更改嵌入模型属于模型操作，而不是设置操作。请根据调整调整 embedding.provider、model、baseUrl 和原生 dimensions；profile: "auto" 会解析支持的模型家族。请重启 thoth-mem，并让变更新的嵌入谱系（embedding lineage）将幂等的语义索引重建编入待处理队列。

Related MCP server: LumenCore

记忆循环

一个有效的智能体工作流应当简单且可重复：

1. 保存有持久价值的经验。 使用 mem_save 保存决策、根本原因、约定，或其他在当前上下文之外仍应存在的不显而易见的经验。

2. 收窄召回。 使用 mem_recall(mode="compact") 开始，用 mode="context" 扩展强候选，再使用 mem_get 获取一条完整记录。

3. 以身份继续。 保持相同的稳定 session_id 和 project；使用 mem_context 读取最近的连续性，使用 mem_session 读取 root 拥有的生命周期事件。

示例观察：

{
  "kind": "observation",
  "title": "Retry SQLite writes in a new transaction",
  "type": "bugfix",
  "project": "my-project",
  "topic_key": "sqlite/busy-retry",
  "content": "**What**: Roll back after SQLITE_BUSY and retry in a new transaction.\n**Why**: Retrying inside the failed transaction repeats the failure.\n**Where**: write transaction helper.\n**Learned**: Use bounded backoff before opening the new transaction."
}

在持久化之前先移除 <private>...</private> 内的内容。请勿存储凭据、完整转录内容、被当作用户意图的生成式智能体提示词，或在没有可复用经验的情况下存储原始日志。

六个 MCP 工具

Setup、sync、migration、rebuild 和维护命令是 CLI / HTTP 管理能力，不会新增更多 MCP 工具。

检查图谱社区

社区来自一个项目知识图谱的摘要。操作者通过 CLI 构建或刷新这些已提交的摘要：

thoth-mem rebuild-communities --project my-project

然后智能体通过 mem_project 获取它们：

{
  "action": "graph",
  "project": "my-project",
  "navigation": "community",
  "limit": 5,
  "max_chars": 2000
}

响应会报告社区状态和新鲜度，然后返回结果，例如 community=<id>、graph coverage、confidence、degradation state、一个 bounded summary 和 sources=obs:<id>。社区检查要求提供项目，但不要求 focus node 或 observation ID。如果没有已提交的摘要，它会直接提示，而不会合成一个全局视图。

若要检查某个社区的原始证据，请从其 sources 取一个 obs:<id>，然后调用 mem_get(kind="observation", id=<id>)。observation ID 也会出现在召回结果中。在穷尽的 graph 邻域内，将相同 ID 作为 focus_node_id="obs:<id>"，配合 navigation="neighborhood" 使用。

原生代码集成

原生安装会在工具支持的情况下安装包自带的 MCP 声明、记忆技能和生命周期钩子。先查看零写入计划，然后删除 --plan 重新运行以应用：

OpenCode 的默认 setup 命令是 thoth-mem setup opencode；对于指定的项目，可以加上 thoth-mem setup opencode --scope project --project /path/to/project --force， 或使用 thoth-mem setup codex --rollback /path/to/receipt.json 进行按回执限定的加载。

这些状态和退出码是稳定的：

项目本机设置是显式的：

thoth-mem setup opencode --scope project --project /path/to/project --plan --json

应用前请先检查冲突位置。只有已证明归 thoth-mem 所有的冲突位置，才使用 --force。Codex 0.144.x、0.146.x 和 0.147.x 属于已测试兼容集，无需 --force。对于其他 Codex 版本，当所选的 working scope 仍然会暴露完整的、可独立验证的插件管理器能力时，可以不应用验证版本号，这时会返回 requires_user_action，并在状态中输出警告。它不会绕过状态验证、所有权验证、包含检查、调和或清理保护，也不会授权任何与 thoth-mem 无关的配置。

Claude Code 还支持原生 marketplace 流程：

claude plugin marketplace add EremesNG/thoth-mem
claude plugin install thoth-mem

原生集成是可选的。现有的记忆条目和六个工具的 MCP 服务器在手动连接下仍然全部运行。

手动 MCP 备用

原生钩子是可选的。如果不想采用受管设置或原生插件，请继续使用一个普通的 MCP 六工具连接；现有记忆仍然需要。

迁移到原生工具集成

原生设置是可选加入：先查看零写入计划，检查冲突，然后运行针对该 bar 的工具命令。对于 Codex，请在 /plugins 中安装 EremesNG/thoth-mem 并验证 marketplace 插件状态。外部 Codex 注册无法原子回滚，因此请先确认外部状态再重试或还原本地设置。

受管安装约定：Plan 模式执行零写入，而最终还可支持对 thoth-mem 拥有的位置进行修改。在首次修改之前会创建备份；OpenCode 接受 opencode.json 或 opencode.jsonc。每次会写一条带有状态 in_progress 的回执，然后才进行写入：

• 全局回执：<thoth-data-dir>/setup/receipts/<receipt-id>/receipt.json

• 项目回执：<project>/.thoth/setup/receipts/<receipt-id>/receipt.json

回执缺失或被篡改会失败并生效。已验证的回滚只影响彼此无关的部分，而状态不一致或不可用的能力会返回 requires_user_action。如果已验证的状态已经匹配，重复设置且未回滚会变成无操作。

Gemini CLI：手动 MCP

Gemini CLI 是手动 MCP 的客户端路径，不是可管理的原生 thoth-mem 集成。将它添加到 ~/.gemini/settings.json：

{
  "mcpServers": {
    "thoth": {
      "command": "npx",
      "args": ["-y", "thoth-mem@latest", "mcp"]
    }
  }
}

评估检索与图谱质量

仓库包含确定性评估命令：

pnpm run eval:retrieval
pnpm run eval:kg
pnpm run eval:embedding-models -- --help

eval:retrieval 会注入信号观察以及三种干扰，并测量期望到的记忆是否排在顶。请将其报告作为一组 Signals 来阅读：

• 召回与排名显示是否正确发现证据，以及证据有多早出现。

• 噪声与混合情况显示了直接、改写和来自仓库的示例之间的鲁棒性。

• 压缩显示在交付上下文之前移除了多少证据；它是效率指标，并不是剩余原文正确性的证据。

• Lane 和新款证明词语、语义词向量/HyDE 以及 KG 的参与率，包括未出版或已降级的语义行为。

• 谱系与溯源显示返回的证据是否仍然可以归属到最初源。

eval:kg 会衡量 subject-relation-object 召回、禁止的三元组泄漏、确定性提取行为以及可选 LLM 已人工确认的增强。缺失预期事实表示由覆盖的缺口，禁止列表命中表示存在表示不安全的结论不create。

这些评测属于确定的开发 gate，覆盖已筛选的合成 fixture。它不是生产语料总体的预测、也不可替代人工抽查、不代表原生工具集成正确，更无法单独证明可选的社区读取路径是安全的。请阅读各具体示例与失败详情，而不要把某个总数当成代表整体质量的数字。

嵌入配置与模型比较

Semantic embedding 输入由带版本的 model profile 格式化。auto 可认识 Nomic、EmbeddingGemma 和 Qwen3-Embedding 的 model-family 别名；调用未知模型 raw 则不会得到推断的非对称格式。配置工程有意不配置全局 task 字段：检索意图和 query/document 角色是为每个输入在内部确定的，包括按 document-role 生成的 HyDE answers。

{
  "embedding": {
    "provider": "lmstudio",
    "model": "text-embedding-embeddinggemma-300m",
    "baseUrl": "http://127.0.0.1:1234",
    "dimensions": 768,
    "profile": "auto",
    "normalize": true
  }
}

支持的 profile 值为 auto、nomic、embeddinggemma、qwen3 和 raw。THOTH_EMBEDDING_PROFILE 和 THOTH_EMBEDDING_NORMALIZE 会覆盖持久化值。解析后的 profile 版本和归一化标志是语义索引谱系的一部分，因此更改它们会将先前的向量标记为过期，并使用现有的幂等重建队列。

本地 Transformers.js 推理可以选择特定的 ONNX 执行设备：

{
  "embedding": {
    "provider": "transformers_local",
    "model": "onnx-community/embeddinggemma-300m-ONNX",
    "device": "dml",
    "dimensions": 768,
    "profile": "auto",
    "normalize": true
  }
}

支持的设备值为 auto、cpu、dml、cuda 和 coreml；默认值为 cpu。THOTH_EMBEDDING_DEVICE 会覆盖持久化的 embedding.device 值。对于 Transformers.js 使用的预构建 Node ONNX Runtime，dml 针对 Windows 上的 DirectML，cuda 针对受支持的 Linux x64 CUDA 安装，coreml 针对 macOS。显式指定不可用的设备会导致模型初始化失败，而不是静默回退到 CPU。auto 将特定于平台的提供程序排序和回退委托给 Transformers.js，因此其有效后端可能因主机或依赖版本而异。

设备选择仅影响 transformers_local；远程 Ollama 和 LM Studio 请求会忽略它。GPU 后端的冷启动可能明显更慢，因此它们对持久化 MCP 进程或较大的嵌入批次最有用。设备被有意排除在语义索引谱系之外：仅更改 embedding.device 不会将现有向量标记为过期，也不会排队重建。

提供者模型示例：

EmbeddingGemma 本地执行使用 sentence_embedding。Qwen 本地执行仅对查询应用检索指令，并使用最后关注的隐藏状态 token 进行池化。所有提供者都拒绝不完整、非有限、零值或维度不一致的批次。LM Studio 响应索引会经过验证，有效的乱序行会恢复为输入顺序；缺失、重复或无效的索引会被拒绝。在召回期间，这些错误会明确降级语义检索，而词法和知识图谱检索会继续。

使用显式模型 ID 和持久输出路径运行三模型质量门：

pnpm run eval:embedding-models -- --provider lmstudio --base-url http://127.0.0.1:1234 --nomic-model <nomic-id> --embeddinggemma-model <gemma-id> --qwen3-model <qwen-id> --output <result.json>

该门要求所有三次执行都完成，并且至少一个候选者满足 Recall@1/Recall@5/MRR 阈值，且不使任何 Nomic 指标回归。Nomic 是相对比较器，不是受绝对阈值约束的候选者。如果两个候选者都合格，则显式质量分数和稳定的平局决胜顺序会选出获胜者。模型缺失、向量无效、没有合格候选者或报告写入失败都会以非零状态退出，并保留当前默认值。

记录的 2026-08-08 LM Studio 运行选择了 EmbeddingGemma 作为发布的本地默认值。EmbeddingGemma 和 Qwen3 均以 Recall@1 1.00、Recall@5 1.00 和 MRR 1.00 完成，而 Nomic 为 0.50、1.00 和 0.7167；两个候选者都合格，EmbeddingGemma 通过稳定的词法 profile-ID 规则赢得了它们完全相同的质量平局。持久化决策运行中的中位延迟为：Nomic 190.5 毫秒，EmbeddingGemma 195 毫秒，Qwen3 320.5 毫秒。

Qwen3 文件大小取决于运行时工件：

Qwen3 Q8 模型在 Transformers.js 中比 EmbeddingGemma Q8 大 304,069,133 字节，在 LM Studio 中大 305,559,648 字节。它还使用原生 1024 维向量，而不是 EmbeddingGemma 的 768 维。运行器不会代表操作员安装或发现提供者模型。

当您想要更严格的本地运行时，可以缩放检索噪声：

$env:THOTH_RETRIEVAL_EVAL_NOISE='250'
pnpm run eval:retrieval

高级操作

• 运行 thoth-mem help 获取完整的 CLI 命令和选项列表。

• 在 http://localhost:7438/ 打开本地仪表板，在 http://localhost:7438/docs 打开 OpenAPI 文档。

• 使用 thoth-mem sync --dir=.thoth-sync 和 thoth-mem sync-import --dir=.thoth-sync 进行 Git 友好的可移植性。

• repair-sync-journal (--project <name> | --all) --apply 在内部预览并绑定其修复批次。当外部工作流已有预览绑定时，可选的 --expected-fingerprint 仍然可用。

• prune-operation-traces (--project <name> | --all) --apply 同样在内部绑定一个保留批次。添加 --until-complete 以使用一个固定的有效瞬间和新的后续指纹处理初始有界积压。外部提供的绑定必须同时包含 --expected-fingerprint 和 --effective-now。

• compact-database [--data-dir <path>] 执行只读预览。仅在查看其可回收空间和容量估算后添加 --apply。应用可能需要物理和逻辑数据库大小中较大者的两倍，可能被其他 SQLite 客户端阻止，并且仅在完整性、外键、模式、持久计数和 WAL 检查后报告成功。它使用 SQLite 管理的检查点和 VACUUM；它不承诺在提交压缩后回滚。

• 压缩永远不会自动进行。对实时数据运行它需要单独的操作员授权；仓库测试仅使用一次性数据库。

• 查看 config.schema.json 以了解持久化配置和环境支持的设置。

• 数据默认位于 ~/.thoth/thoth.db；使用 THOTH_DATA_DIR 或 --data-dir 覆盖数据目录。

语义索引是非阻塞的。如果嵌入或 sqlite-vec 不可用，召回仍可通过受支持的词法和图证据使用，并报告降级通道，而不是静默声称语义成功。

开发

pnpm install
pnpm run integration:verify
pnpm run build
pnpm test

许可证

MIT