35 个 MCP 工具实现持久化 AI 记忆

概述

toon-memory 提供 35 个 MCP 工具和 4 个 MCP 资源，用于管理持久化记忆：

工具

工具	描述
memory_remember	保存决策、模式、缺陷、知识或 warning（负面“不要这样做”记忆，召回时加成）（可选 TTL、自动标签推断、links、自动质量评分、合并去重、置信度、可选 importance：critical/high/medium/low）
memory_recall	搜索记忆（应在读取文件之前使用，自动过滤过期 TTL）。mode: "graph" 可展开关系感知子图以获得更高精度。排名使用 RRF 融合（BM25×3 + 图中心性，自适应 k）；传入 rrf: false 使用旧版线性分数。sessionBias 提升来自当前 git 分支的条目。pathScope 将结果限定到文件路径（支持 globMatch）。budget："tiny"（前 3）、"normal"（前 10）或 "deep"（前 20）。as_of 会重新包含在指定日期之后被 superseded 的条目。explain: true 为每条结果追加原因行（说明为何被检索到）。budget_tokens 按估计 token 数限制输出（0 = 无限制）。mode: "index" 每行只列一条（key、id、分类、日期、相关度 %）不含内容；ids 按 id/key 批量获取条目并保持顺序
memory_forget	按 key 或 id 移除条目
memory_stats	查看记忆状态（包括 TTL 统计、质量分布、低于质量/访问阈值的冷记忆，以及命中率/重复率/废弃率指标：至少被召回一次的条目百分比、完全重复内容百分比、过时条目百分比）
memory_summary	保存/获取文件摘要
memory_archive	归档旧条目（>30 天）和过期 TTL 条目
memory_diff	显示自某日期以来的更改（24h、7d 或具体日期）
memory_suggest	为给定上下文查找相关条目
memory_captured	列出钩子自动捕获的活动（需启用）或清除日志
memory_checkpoint	会话检查点：创建当前内存状态的快照，TTL为7天。在长时间会话中可用于回滚参考
memory_consolidate	清理操作，确定性（无 LLM）：mode: "identical"（默认）去重内容完全相同的条目，"similar" 合并近重复条目（Jaccard >50%），"low-quality" 批量压缩低质量条目（minQuality、dryRun），"versions" 检测描述同一主题在不同库版本的条目，并淘汰旧条目、保留最新版本
memory_encrypt	启用 AES-256-GCM 加密
memory_decrypt	禁用加密
memory_backup	创建带时间戳的记忆文件备份（自动保留最近 10 个）
memory_sessions	显示活跃代理会话、分支和软文件冲突，用于并行会话协调
context_brief	单次调用的上下文简报：记忆 + 会话 + 健康状态，紧凑 markdown 格式。可替代 5-6 次独立的 memory_* 调用。零 LLM
context_generate	完整项目简报：一次调用结合项目结构、git 状态、记忆条目和活跃会话。替代 5-6 次手动工具调用
context_diff	增量简报：自上次会话以来的 git 提交 + 已修改文件 + 新增/更新的记忆
context_focus	超聚焦简报：仅返回与查询相关的记忆 + 相关源文件 + 调用者 + 测试文件
context_health	记忆健康审计：孤儿链接、重复项、损坏的文件引用、过期 TTL、过期会话，评分 0-100
context_export	导出记忆为 markdown：可用于系统提示词的注入式上下文（完整或紧凑格式）
memory_smart_recall	统一搜索：BM25 + 图 + 质量 + 新鲜度 + 衰减，一次调用完成。explain: true 为每条结果附加原因行，budget_tokens 按估计 token 数限制输出上限
memory_pin	Pin an entry: pinned entries always appear at the top of recall results, even without a keyword match
memory_unpin	Unpin an entry: remove the pinned flag
memory_search	Unified search with filters: same as memory_recall plus category, tags, from_date, to_date filters. Tag filter uses AND logic — all specified tags must match
memory_tag	Batch tag operations: add, remove, or set tags on one or more entries by key or id
memory_reflect	记忆反思：按过时程度、质量和过度连接确定性排名条目，揭示需要注意或清理的内容。零 LLM
memory_promote	自动提升草稿：确定性将低置信度条目提升为激活状态（阈值 0.65，Jaccard 去重 > 0.5，默认 dryRun）

MCP 资源

记忆也作为 MCP 资源暴露，可直接读取上下文：

资源	URI	描述
记忆条目	toon://memory/entries	完整记忆转储
记忆统计	toon://memory/stats	分类计数和 TTL 信息
记忆摘要	toon://memory/summaries	自动生成的系统引导：知识图谱、近期记忆和关键决策

资源允许代理直接读取记忆作为上下文，无需工具调用 — 适用于系统提示词或会话启动。系统引导提供关于项目知识状态的即时上下文。

示例

保存决策

memory_remember({
  category: "decision",
  key: "use-zod",
  content: "Use Zod for validation",
  file: "src/types.ts",
  tags: "validation;types"
})
// 🧠 Guardado: decision/use-zod (a1b2c3d4)
// 🎯 Quality: 0.80 | Confidence: 1.00
// 🔗 Entradas relacionadas:
//   [pattern] zod-schemas — Shared Zod schemas for API validation

条目会根据标签、链接、内容详情和具体性自动进行质量评分（0-1）。你主动断言的记忆置信度为 1.0；推断/收集的记忆为 0.65-0.75。

带 TTL 保存

memory_remember({
  category: "knowledge",
  key: "sprint-deadline",
  content: "Sprint ends July 18, feature freeze is July 16",
  ttl: "7d"
})
// 🧠 Guardado: knowledge/sprint-deadline (x1y2z3w4)
// 🎯 Quality: 0.55 | Confidence: 1.00
// ⏰ TTL: 2026-07-19

使用 ttl 设置临时上下文，如截止日期或冲刺信息。支持相对时间（7d、30d）或具体日期（2026-12-31）。过期条目会自动从搜索中过滤。

自动推断标签

memory_remember({
  category: "bug",
  key: "redis-connection-timeout",
  content: "Redis connection timeout in production, increased pool size"
  // tags 留空 — 从内容自动推断
})
// 🧠 Guardado: bug/redis-connection-timeout (a1b2c3d4)
// 🏷️ Tags inferidos: redis

当 tags 为空时，系统会从内容中推断标签，使用包含 20+ 分类的词汇表：redis、auth、api、db、security、test、deploy、config、performance、refactor、error、logging、types、async、state、ui、storage、email、payment、webhook。此外，toon-memory init 会根据你的依赖（package.json、Cargo.toml、requirements.txt、pyproject.toml、go.mod）生成项目词汇表，因此提及依赖（如 redis）的条目也会自动标记 redis。更多标签 = 更高的质量评分。

搜索记忆

memory_recall({ query: "redis" })
// [bug] redis-pool-fix (i9j0k1l2)
//   Added max_connections=20
//   File: redis.ts | Tags: redis;fix | Date: 2026-07-10 | Quality: 0.82

结果按质量加权 — 包含更多详情、标签和链接的条目会排在前面。

解释为什么返回该结果

memory_recall({ query: "redis", explain: true })
// [decision] redis-cache-config (a1b2c3d4)
//   Redis cache layer for session storage
//   File: src/cache.ts | Tags: redis;cache | Date: 2026-07-10
//   ↳ 92% relevance · used 14× · used today · importance HIGH

↳ 原因行是确定性的（相关性百分比、访问次数、最后使用时间、重要性）— 不涉及 LLM。当你想知道代理为什么被展示这些条目时，使用 explain: true。使用显式 importance 级别保存的条目也会报告该级别（例如 · explicit critical）。

使用 budget_tokens 限制输出

memory_recall({ query: "redis", budget_tokens: 300 })
// 条目贪心累积；超出预估的尾部会被丢弃。
// budget_tokens: 0（默认）= 无限制。

提示： 将 budget_tokens 与 budget: "deep" 结合使用，无论记忆多大，都能让上下文窗口保持在硬 token 上限之内。

浏览记忆索引（渐进式披露）

memory_recall({ mode: "index" }) // 或 { query, mode: "index" } 查看过滤结果
// 📇 记忆索引（15 条）:
//
// [1] use-zod (a1b2c3d4) · decision · 2026-07-10 · 100%
// [2] redis-cache-config (e5f6g7h8) · decision · 2026-07-09 · 82%
// ...

mode: "index" 每行只列一条——key、id、分类、日期、相关度 %——不含内容，因此即使记忆量很大，浏览成本也几乎为零。挑选你需要的 id，然后批量获取完整条目：

memory_recall({ ids: "a1b2c3d4,e5f6g7h8" })
// Fetched 2 entries:
// [decision] use-zod (a1b2c3d4)
//   Use Zod for validation
//   File: src/types.ts | Tags: validation;types | Date: 2026-07-10

ids 接受用逗号/空格/; 分隔的条目 id 或 key，并保持你的顺序（未知条目会被跳过）。三层渐进：浏览索引 → 按 id 获取 → 用 mode: "flat" 获取完整排序结果。

被否决的决策

记录你决定 不 采纳的方案，这样 agent 就不会反复重提。这是一个轻量约定——一条带 rejected 标签的 decision 条目，无需额外 schema：

memory_remember({
  category: "decision",
  key: "rejected-graphql",
  content: "Rejected GraphQL: REST + generated types wins on codegen and schema drift risk.",
  tags: "rejected;api;graphql"
})

给条目打上 rejected 标签，并用 rejected-<主题> 作为 key，便于关键词召回。如有必要可链接到胜出的方案（links: "rest-api"）。下次对该想法的 memory_recall 会带着理由浮出这个否决——你的「不」成为项目记忆的一部分，而不是每个会话都被重新争论。

带日期过滤的搜索

memory_recall({
  query: "redis",
  from_date: "2026-07-01",
  to_date: "2026-07-31"
})

显示自上次会话以来的更改

memory_diff({ since: "24h" })
// 📋 Cambios desde 2026-07-11:
//
// ➕ Nuevas (2):
//   [decision] use-zod (a1b2c3d4)
//     Use Zod for validation
//   [bug] redis-timeout (e5f6g7h8)
//     Redis connection timeout fix

since 支持相对时间（24h、7d）或具体日期。可通过 type 过滤：all、created 或 updated。

查找相关条目

memory_suggest({ context: "redis cache configuration" })
// 🔍 Sugerencias para "redis cache configuration":
//
// [decision] redis-cache-config (a1b2c3d4)
//   Redis cache layer for session storage
//   File: src/cache.ts | Tags: redis;cache | Date: 2026-07-10

归档旧条目

memory_archive()
// 📦 Archivadas 5 entradas antiguas
// 📋 Quedan 42 entradas activas

启用加密

memory_encrypt()
// 🔐 Encriptación habilitada
// ⚠️ Guarda esta clave (no se puede recuperar):
// a1b2c3d4...

列出活跃会话和冲突

memory_sessions({ conflictsOnly: false })
// 🧭 Sesiones activas (2) — ventana 10 min:
//
// • opencode @ feature/foo
//    id: sess-B
//    Archivos:
//      • src/shared.ts
// • claude @ feature/foo (tú)
//    id: sess-A
//
// 🔥 Conflictos suaves (1):
//   ⚠️ src/shared.ts  ↔  opencode@feature/foo, claude@feature/foo

如果只关心冲突，使用 memory_sessions({ conflictsOnly: true })。参见下方多会话协调。

多会话协调

当你并行运行多个 AI 代理会话时（例如同一仓库上同时运行三个 OpenCode 会话），它们可能会互相覆盖彼此的工作。memory_sessions 是一个基于文件的协调工具 — 无服务器、无网络、无 LLM 调用 — 让每个会话看到其兄弟会话在做什么。

工作原理

• 启动时，SessionStart 钩子为会话写入一个心跳文件到 .toon-memory/memory/sessions/<id>.json。每个进程只写自己的文件，因此没有锁竞争。
• 心跳记录代理名称、git 分支、已操作的文件和最后活跃时间戳。
• 跨所有这些文件进行读取，让每个会话获得一个共享的、最终一致的视图，了解其他活跃会话。
• 当最后心跳在 TTL 窗口内（10 分钟）时，会话被视为“活跃”。死亡会话（进程 PID 已不存在且心跳过期）会被延迟清理。
• 软冲突是指被2+ 个活跃会话操作的文件 — memory_sessions 会将其标记出来，以便你避免踩踏兄弟会话的工作。

并行会话推荐习惯

1. 会话启动时，SessionStart 钩子会打印其他活跃会话、它们的分支和任何软冲突。
2. 编辑共享文件之前，运行 memory_sessions() 确认没有兄弟会话正在操作这些文件。
3. 完成后，你的心跳会被标记为已结束，文件被释放。

记忆图（基于图的召回）

对于较大的记忆，平铺关键词搜索可能返回太多结果或遗漏关系。toon-memory 可以将记忆视为一个轻量级知识图谱，让召回以更少的 token 返回正确的条目。结合质量评分，最有用的条目会排在前面。

它是完全确定性和离线的 — 无嵌入、无向量数据库、无 LLM、无服务器。边来自：

• 显式 links — 你在保存条目时声明的键。
• 隐式 [[key]] 引用 — 内容中的任何 [[some-key]] 提及。

带链接保存

memory_remember({
  category: "decision",
  key: "risk-engine-priority",
  content: "The engine prioritizes risk over speed (see [[risk-spec]]).",
  file: "spec.md:10",
  tags: "risk;spec",
  links: "engine-arch"   // explicit edge to another entry
})
// 🧠 Guardado: decision/risk-engine-priority (a1b2c3d4)

图模式召回

memory_recall({ mode: "graph" }) 查找关键词匹配（种子），然后展开自我子图至 hops（1 或 2）层。相关性从种子传播到邻居，因此即使没有搜索词，相关的规格或决策也会浮现。结果被限制（limit，默认 6），以获得更小、更精确的上下文。

memory_recall({ query: "riesgo", mode: "graph", hops: 2 })
// [decision] risk-engine-priority (a1b2c3d4)
//   The engine prioritizes risk over speed (see [[risk-spec]]).
//   File: spec.md:10 | Tags: risk;spec | Date: 2026-07-01
//   links: engine-arch
//
// [knowledge] risk-spec (a2b3c4d5)
//   Risk specification for the engine.
//   links: risk-engine-priority;engine-arch
//
// [pattern] engine-arch (e6f7g8h9)
//   Engine architecture.
//   links: risk-spec

当一个决策涉及多个条目（架构、规格、相关缺陷）时，使用 mode: "graph"。对于孤立的事实，默认的 flat 模式就足够了。图在读取时构建，因此无需维护额外的索引文件。

Token 高效召回（compact: true）

当每个 token 都很重要时，传入 compact: true 以获得更紧凑的输出：

memory_recall({ query: "riesgo", mode: "graph", hops: 2, compact: true })
// [1] decision/risk-engine-priority
//   The engine prioritizes risk over speed (see [[risk-spec]]).
//   tags: risk;spec · edges: ->2, ->3
//
// [2] knowledge/risk-spec
//   Risk specification for the engine.
//   tags: risk · edges: ->1
//
// [3] pattern/engine-arch
//   Engine architecture.
//   tags: engine · edges: ->1

compact 模式的变化：

• 每个条目获得按分数排序的稳定数字索引（[1]、[2]、……）。
• 移除 id、date 和 file — 仅保留 tags。
• 在 graph 模式下，边渲染为 ->2（数字，非键名）。
• 通过图到达的邻居（非种子）被截断为带省略号的短片段，而直接匹配的种子保留完整内容。
• 存储的 .toon 文件不会被修改 — compact 仅重塑响应。

召回如何排序结果

召回是确定性和离线的（无嵌入、无 LLM）。自 v3.7.0 起默认排名为 RRF（Reciprocal Rank Fusion）：

• BM25 相关性 — 对 id + category + key + content + file + tags 的概率性词频评分，融合三次（在小型记忆图上唯一的真实检索器）。
• 图中心性 — 度归一化（0..1），融合一次；连接多个条目的枢纽即使没有搜索词也排在前列。
• 自适应 k — k = clamp(3..60, round(sqrt(n)))，其中 n 是候选项数量。教科书式 k=60 会压平小型图上的排名差异，因此它随 sqrt(n) 缩放。
• 每跳衰减 — 距种子 d 跳的节点乘以 0.5^d，使远距离上下文低于近距离上下文。
• 会话偏置 — 条目所在文件出现在当前会话中的获得 1.15× 加成。
• 语言家族 — 与查询使用相同文字体系（latin/CJK/cyrillic/…）书写的条目通过 languageFamily() 获得 +0.1 加成。
• 文件夹匹配 — path_scope 与当前文件匹配的条目获得 +0.05 加成。
• 显式重要性 — memory_remember({ importance }) 可让你设置 critical（+0.3）、high（+0.15）、medium（0）或 low（−0.1）；critical 决策排在 low 笔记之前，该级别会出现在 explain 原因和 budget: "deep" 输出中。空 = 自动（新近度 + 频率）。
• 优先级 — 固定的条目无论分数如何都排在首位。

传入 rrf: false 回退到旧版线性加权分数（BM25 + 0.4·centrality + 0.25·importance + 种子加分）。在 graph 模式下，召回以关键词匹配为种子，展开自我子图至 hops 层，然后按综合分数返回前 limit（默认 6）个结果。memory_smart_recall 在一次调用中组合所有这些信号。

智能召回（memory_smart_recall）

一次调用中组合 BM25、图、质量、新鲜度和衰减的统一搜索：

memory_smart_recall({ intent: "redis cache configuration", hops: 2 })
// Combines BM25 relevance + graph centrality + quality score + freshness decay
// Returns top results ranked by combined score

这是推荐的召回方式 — 它在一次调用中处理所有内容，无需你编排多个工具。

质量评分

每个条目自动进行质量评分（0-1），基于：

• 标签覆盖度（权重 0.3）— 更多标签 = 更高分数
• 链接丰富度（权重 0.2）— 更多链接 = 更高关联度
• 内容详情（权重 0.2）— 更长、更详细的内容得分更高
• 新近度（权重 0.15）— 近期条目得分略高
• 具体性（权重 0.15）— 包含文件引用和具体键的条目得分更高

高质量条目在召回结果中排在最前面，确保最有用的上下文始终突出。

合并去重

当你用已存在的键保存条目时，系统会合并属性：

• 标签：两个标签集的并集
• 链接：两个链接集的并集
• 质量：两个分数的最大值
• 置信度：两个分数的最大值
• 内容：保持原样（不覆盖）
• 日期：更新为当前时间
• 重要性：较高的显式级别胜出（critical > high > medium > low）

这意味着重新保存条目会丰富它，而不是替换它。

从项目依赖自动标记

在 toon-memory init 时，CLI 扫描你的依赖清单并将 vocab 表写入 .toon-memory/memory/config.json：

{
  "vocab": {
    "react": ["react"],
    "zod": ["zod"],
    "redis": ["redis"]
  }
}

memory_remember 会将新条目与此词汇表（以及内置词汇表）进行匹配。添加主要依赖后重新运行 toon-memory init 以刷新。vocab 键会与 config.json 中的 encrypted/capture 标志合并（不会被覆盖）。更多标签 = 更高的质量评分。

分类

条目按分类组织：

分类	用途
decision	设计决策（“为什么选择 X 而不是 Y？”）
pattern	项目模式（“使用 Zod 做校验”）
bug	缺陷修复（“Redis 连接池耗尽”）
knowledge	通用知识（“Broker 使用 RESP”）
warning	“不要这样做” — 反模式、雷区、要避免的错误（召回时 +0.2 加成）