Toon Memory

English | Español | 中文 | 日本語 | 한국어 | Português (BR) | Deutsch | Français

toon-memory

AI Agent 的连续性层 — AI Agent 不应该每次会话都重新学习你的项目。

---

目录

• 概览
• 博客文章
• 功能
• 安装
• 支持的 Agent
• MCP 工具
• 多会话协调
• 记忆图谱（基于图谱的回忆）
• 技巧与最佳实践
• CLI 命令
• 配置
• 工作原理
• 为什么选择 TOON？
• 故障排除
• 常见问题
• 开发
• 贡献
• 安全与隐私
• 许可证

---

概览

你是否有过这样的感觉：AI Agent 忘记了昨天会话中的所有内容？你第三次解释同一个架构决策，它却仍然建议你已经否决过的方案？

**toon-memory 可以解决这个问题。**它是 AI Agent 的连续性层——一个轻量级系统，可在不同会话之间保存项目的知识、决策和约定，让每次会话都能从上次结束的地方继续。完全本地化且私密，通过 MCP 工作——无需云端，也无需服务器。

📖 阅读文档

实际应用场景

场景	toon-memory 的作用
设计讨论	“我们选择 Redis 而不是 Memcached，因为它支持发布/订阅”
框架选择	“这个项目使用 Zod 进行验证，而不是 Joi”
Bug 修复	“Redis 连接池耗尽——解决方法是 max_connections=20”
架构说明	“Broker 服务使用 RESP 协议，而不是 HTTP”
新人入职	“部署脚本位于 scripts/deploy.sh”
团队背景信息	“PR #142 撤销了缓存更改——不要重新添加”

---

博客文章

阅读《toon-memory 如何让你的 AI Agent 更智能》，了解持久化记忆在实际应用中的演示。

---

功能

• 完整的记忆工具包 — 通过 Model Context Protocol 实现完整的记忆管理，包括 memory_smart_recall（带会话偏置的统一回忆）、用于多会话协调的 memory_sessions、用于一次调用生成上下文（简报、差异、焦点、健康审计、导出）的 context_* 工具、memory_compress（由 LLM 驱动的压缩）、memory_consolidate（确定性去重／合并／清理）、memory_primer（自动注入上下文）、memory_merge_sessions（跨会话合并）、memory_pin/memory_unpin（以 1-5 的优先级固定重要条目）、memory_checkpoint（TTL 为 7d 的会话快照）、memory_search（带标签筛选和会话偏置的统一搜索）、memory_tag（批量标签操作）、memory_export_gist/memory_import_gist（GitHub Gist 同步）、memory_secret（加密密钥库）、memory_export_global/memory_import_global（跨项目约定）、memory_forget（软／硬删除、恢复、取代）、memory_reflect（时效性／质量反思）和 memory_promote（自动提升低置信度草稿）
• MCP 资源 — 无需调用工具即可将记忆作为上下文读取，包括系统导览（自动生成的知识地图）
• 支持 22 种 Agent — OpenCode、VS Code、Claude Code、Cursor、Windsurf、Cline、Continue、Codex CLI、Gemini CLI、Zed、Antigravity、Aider、KiloCode、OpenClaw、Kiro、Qwen、Kimi、Goose、Junie、Amp、Grok、Trae
• 交互式安装程序 — 通过菜单选择要配置的 Agent
• SessionStart hooks — 为 Claude Code、Codex CLI、Gemini CLI、Antigravity 自动提供提醒
• TOON 格式 — 比 JSON 少用 22% 的 token（实测），更便于大模型理解
• 按项目划分记忆 — 每个项目都有自己的记忆文件
• 零配置 — 安装后即可使用
• 自动添加到 gitignore — 自动将 .toon-memory/memory/ 添加到 .gitignore
• 日期筛选 — 按日期范围搜索记忆
• 自动归档 — 自动将旧条目（>30 days）、过期的 TTL 条目或 100+ 条目移至归档
• 加密 — 对敏感数据使用 AES-256-GCM 加密
• 监视模式 — 每 N 分钟自动备份
• 记忆 TTL — 可为每个条目配置过期时间（7d、30d 或确切日期）
• 标签推断 — 标签为空时，根据内容自动检测标签（内置词汇表 + 项目依赖）
• 记忆差异 — 查看自上次会话以来的变化
• 相关条目 — 保存时自动推荐相关记忆
• 记忆图谱 — 使用 links/[[key]] 引用连接条目；memory_recall 可扩展具备关系感知能力的子图，从而实现更精准、token 消耗更低的回忆（无需嵌入，无需 LLM）
• 高效使用 token 的回忆 — memory_recall({ compact: true }) 返回以数字为索引的条目，移除 id/date/file，将图谱边渲染为 ->2，并将图谱邻居截断为摘要
• BM25 + 中心性排序 — 回忆会根据 BM25 相关性和图谱中心性重新排序（即使不包含查询词，也会显示枢纽条目）；逐跳衰减会降低远距离节点的排序
• 根据依赖自动添加标签 — toon-memory init 会扫描 package.json/Cargo.toml/requirements.txt/go.mod 并写入项目词汇表，因此提及某个依赖的条目会自动添加该依赖作为标签
• 智能回忆 — memory_smart_recall 一次调用即可结合 BM25 + 图谱 + 衰减 + 质量；LLM 会在每项任务开始时调用它
• 质量评分 — 根据结构（标签、链接、内容具体程度、时效性、访问次数）为每个条目评分，范围为 0–1；高质量条目优先显示
• 合并去重 — 使用相同 key 保存时会合并属性（标签取并集、置信度取最大值、日期取最新值、链接合并），而不是覆盖
• 近似重复检测 — 整合时通过 Jaccard 相似度（阈值 0.7）检测近似重复项并合并
• 置信度分数 — 每个条目都会记录可靠性：用户断言 = 1.0，推断 = 0.65–0.75
• LLM 驱动的压缩 — memory_compress 使用 AI 总结较长的条目；memory_consolidate(mode: "low-quality") 以确定性方式批量清理
• 跨会话合并 — memory_merge_sessions 会合并针对某个文件的并行会话中的观察结果
• GitHub Gist 同步 — memory_export_gist 和 memory_import_gist 通过 GitHub Gist 同步记忆条目（零依赖）
• 逐字保留模式 — config.verbatim 会保留原始条目，而不是在保存时覆盖
• 上下文生成工具 — context_generate（完整简报）、context_diff（增量差异）、context_focus（定向聚焦）、context_health（审计）、context_export（Markdown）——每个工具都可替代 5-6 次手动工具调用。无需 LLM，纯确定性聚合
• 系统导览 — 会话开始时通过 systemPrimer() 自动注入，展示排名前 5 的记忆，以便快速了解上下文
• 路径范围限定 — 可通过 glob 模式（path_scope）将条目限定到文件路径；回忆时会自动按范围筛选
• 预算控制 — 三种输出级别：budget: "tiny"（key + 1 行，约 50 个 token）、"normal"（包含标签／边的精简内容）、"deep"（包含来源／范围／状态的所有字段）。向后兼容 compact: true
• 来源追踪 — 每个条目都会记录其来源（human、agent、inferred）；人工断言会获得质量加成
• 软删除 — 默认情况下，memory_forget 会软删除（设置 status=obsolete）。使用 memory_forget(key, action: "restore") 恢复，使用 action: "soft" 隐藏，使用 action: "hard" 永久删除
• 增强的健康审计 — context_health 现在可检测缺少依据的条目（有 path_scope 但文件不存在）和过时断言（同一类别中内容重叠）
• 带类型的图谱边 — 边携带类型（superseded_by、supersedes、relates），在图谱中以 type:key 的形式写入。显式的 links 会变为 relates:key，因此你可以了解条目之间的关系类型，而不只是它们存在关联
• RRF 排序 — 回忆通过 Reciprocal Rank Fusion 融合 BM25（×3）和图谱中心性排名，并使用自适应 k = clamp(3..60, round(sqrt(n)))。基准测试（8 个黄金查询）：nDCG 0.776、MRR 0.917——与之前的线性评分完全一致。传入 rrf: false 可回退
• 记忆反思 — memory_reflect 根据时效性、质量和过度连接程度为条目排序，以找出需要关注或清理的内容。确定性执行，无需 LLM
• 记忆取代 — memory_forget(key, action: "supersede", new_key) 会将条目标记为已被较新的条目取代（添加 superseded_by 链接 + supersededOn 日期）。memory_recall({ as_of }) 会在查询条目被取代前的特定时间点时，重新纳入旧条目
• 自动提升 — memory_promote 以确定性方式将低置信度草稿提升为有效条目（阈值 0.65，Jaccard 去重），默认启用 dryRun
• 解释原因 — memory_recall/memory_smart_recall 接受 explain: true，并为每个返回的条目附加确定性的原因说明（↳ 100% relevance · used 14× · used today · importance HIGH）——解释它为何被检索到，无需 LLM
• Token 预算 — budget_tokens 根据估算的 token 数量限制回忆输出；条目会贪心累加，超出预算的尾部内容会被丢弃（0 = 无限制）
• 版本取代 — memory_consolidate(mode: "versions") 会检测描述同一主题不同库版本的条目（例如“使用 React 18”和“使用 React 19”），并用最新版本取代较旧条目
• 负面记忆 — 用于表示“不要这样做”事实的 warning 类别；warning 条目会获得回忆加成，以便 Agent 在再次犯错前看到这些警示
• 语言 + 文件夹排序 — 回忆会优先显示使用相同书写系统系列（拉丁文／CJK／西里尔文／……）撰写的条目，以及 path_scope 与当前文件匹配的条目
• 显式重要性 — memory_remember({ importance }) 可设置 critical、high、medium 或 low。关键决策优先显示（+0.3），低优先级笔记则不妨碍查看其他内容（−0.1）；留空则自动计算（时效性 + 频率）。再次保存会保留较高的级别
• 证据层 — 每次 memory_remember 保存都会标注证据级别：引用的文件在磁盘上存在时为 verified，不存在时为 unverified，与警告或关键／高优先级决策内容重叠时为 conflict。冲突会获得 +0.15 的回忆加成（verified +0.03，unverified −0.02），并在保存时显示 ⚠️ CONTRADICTION 警告，但绝不会阻止写入
• 密钥库 — memory_secret 会将凭据存储在加密的 sidecar 文件（secrets.toon，AES-256-GCM）中，让 data.toon 保持为可读的开放格式，同时确保敏感值不会以明文形式出现
• 全局记忆导入／导出 — memory_export_global 将项目记忆写入 ~/.toon-memory/memory/global.toon；memory_import_global 通过一次性、确定性的离线合并导入跨项目约定（不会形成实时双源）
• 约 1 MB 的安装包 — 包含三个精简的 prompt 包（@inquirer/checkbox/select/confirm）；MCP SDK、zod 和 TOON 解析器已打包到发行二进制文件中——一次 npm i -g 下载约 1 MB（原为约 14 MB），安装后占用约 4.4 MB 磁盘空间（原为约 33 MB）

---

安装

1. 安装

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/LuiggiVal08/toon-memory/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/LuiggiVal08/toon-memory/main/install.ps1 | iex

# Or with npm (any platform)
npm i -g toon-memory

提示： npm 安装是最可靠的方式。curl/irm 脚本只是便捷封装。

大小： 仅执行 npm i -g toon-memory 会下载约 1 MB，安装约 4.4 MB——包含三个精简的提示词包；其他所有内容（MCP SDK、zod、TOON 解析器）均已打包。

2. 配置你的 Agent

# Interactive installer — detects agents and configures MCP
npx toon-memory

安装程序将：

1. 检测已安装的 AI Agent
2. 询问要配置哪些 Agent
3. 自动添加 MCP 服务配置

3. 使用

就这么简单！在下次 Agent 会话中，试试：

memory_stats      # See what's in memory
memory_recall     # Search memory before reading files
memory_remember   # Save important decisions

提示： 始终在会话开始时运行 memory_recall。你的 Agent 会立即获取之前会话的上下文。

MCP 客户端快速设置

Cursor

添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "toon-memory": {
      "command": "npx",
      "args": ["-y", "toon-memory", "mcp"]
    }
  }
}

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "toon-memory": {
      "command": "npx",
      "args": ["-y", "toon-memory", "mcp"]
    }
  }
}

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "toon-memory": {
      "command": "npx",
      "args": ["-y", "toon-memory", "mcp"]
    }
  }
}

---

支持的 Agent

Agent	配置位置	格式	Hooks	自动设置
OpenCode	.opencode/opencode.json + .opencode/plugins/toon-memory.ts	插件	SessionStart（插件，不使用顶层 hooks）	✅
VS Code / Copilot	.vscode/mcp.json	JSON	—	✅
Claude Code	.mcp.json（MCP）+ .claude/settings.json（hooks）	JSON	SessionStart + PostToolUse + Stop	✅
Cursor	.cursor/mcp.json	JSON	—	✅
Windsurf	~/.codeium/windsurf/mcp_config.json	JSON	—	✅
Cline	.cline/mcp.json	JSON	—	✅
Continue	.continue/config.json	JSON	—	✅
Codex CLI	.codex/config.toml	TOML	SessionStart + PostToolUse + Stop（[[hooks]] event=）	✅
Gemini CLI	.gemini/settings.json	JSON	SessionStart + PostToolUse + Stop（hooks.*）	✅
Zed	~/.config/zed/settings.json	JSONC	—	✅
Antigravity	.agents/mcp_config.json + .agents/hooks.json	hooks.json	PreInvocation + PostToolUse + Stop（没有 SessionStart 事件）	✅
Aider	—	—	—	📝 说明
KiloCode	~/.kilocode/mcp_settings.json	JSON	—	✅
OpenClaw	.openclaw.json	JSON	—	✅
Kiro	.kiro/settings/mcp.json	JSON	—	✅

提示： 你可以同时为多个 Agent 配置 toon-memory。每个 Agent 都会使用同一个共享记忆文件 .toon-memory/memory/。

---

MCP 工具

工具	描述
memory_remember	保存决策、模式、Bug、知识或警告（负面的“不要这样做”记忆，回忆时会提升优先级）——支持可选 TTL、自动推断标签、通过 links 构建记忆图、相同键合并去重、自动评分质量和置信度。写入路径智能：每次保存都会标注证据级别——引用的文件存在于磁盘上时为 verified，不存在时为 unverified，与警告或重要／高优先级决策重叠时为 conflict（回忆时会提升优先级并显示 ⚠️ 矛盾警告，但绝不会阻止写入）
memory_recall	搜索记忆（读取文件前使用，可过滤已过期的 TTL）。mode: "graph" 会扩展能够感知关系的子图，以提高精确度。`budget: "tiny"
memory_smart_recall	统一回忆：一次调用结合 BM25、图、衰减和质量。sessionBias 会提升当前 git 分支中条目的优先级。explain: true 会附加每个条目的原因说明，budget_tokens 按估算的 token 数限制输出。每项任务开始时使用。返回精简且节省 token 的输出
memory_forget	按键或 ID 执行生命周期操作：action: "soft"（默认）标记为已过时，"hard" 永久删除，"restore" 恢复为活动状态，"supersede" 将其归档，并通过 superseded_by 链接到 new_key
memory_stats	查看记忆状态（包括 TTL 统计、质量分布、来源／状态细分、低于质量／访问阈值的冷记忆，以及命中率／重复／过时指标）
memory_summary	保存／检索文件摘要
memory_archive	归档旧条目（超过 30 天）和 TTL 已过期的条目
memory_diff	显示某日期以来的变更（24h、7d 或指定日期）
memory_suggest	根据给定上下文查找相关条目
memory_encrypt	启用 AES-256-GCM 加密
memory_decrypt	禁用加密
memory_backup	创建带时间戳的记忆文件备份（自动清理，仅保留最近 10 个）
memory_captured	列出钩子自动捕获的活动（需选择启用），或清除日志
memory_checkpoint	会话检查点：创建当前记忆状态的快照，TTL 为 7d。适用于长会话期间作为回滚参考
memory_consolidate	清理操作，确定性执行（无需 LLM）：mode: "identical"（默认）对内容完全相同的条目去重，"similar" 合并近似重复项（Jaccard >50%），"low-quality" 批量删除低质量条目（minQuality、dryRun），"versions" 淘汰较旧的库版本条目，保留最新版本
memory_sessions	显示活动 Agent 会话（分支、文件、最后查看时间）以及并行工作中的软冲突
memory_compress	由 LLM 驱动的两步压缩：总结 + 覆盖。若有 anthropic/openai CLI，则使用它；否则返回提示词供手动压缩
memory_primer	一次调用生成上下文导览：精选记忆 + 类别 + 会话文件变更。会话开始时自动注入
memory_merge_sessions	合并多个并行会话中关于某个文件的观察结果。去重，并可选择自动提升为记忆
memory_export_gist	将记忆条目导出到 GitHub Gist（公开或私密）。使用 GITHUB_TOKEN 或 gh CLI
memory_import_gist	从 GitHub Gist 导入条目。与现有条目合并（合并标签集合，取最高置信度）
memory_secret	加密密钥库（secrets.toon，AES-256-GCM）：支持 store/get/list/forget。保持 data.toon 可读，同时对静态存储的敏感值进行加密。需要 TOON_MEMORY_KEY
memory_export_global	将当前项目记忆写入全局文件（~/.toon-memory/memory/global.toon）。一次性共享跨项目约定
memory_import_global	将全局文件中的跨项目约定合并到此项目（一次性、确定性、离线）。merge: false 则会替换
memory_graph_path	在知识图谱的两个条目之间查找 BFS 最短路径。展示概念之间的连接方式
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_pin	以 1-5 的优先级固定条目：固定条目始终优先显示在回忆结果中，并按优先级排序，即使没有关键词匹配也会显示
memory_unpin	取消固定条目：移除优先级标记
memory_search	支持筛选条件的统一搜索：与 memory_recall 相同，另支持 category、tags、from_date、to_date 筛选。标签筛选使用 AND 逻辑——所有指定标签都必须匹配。budget 控制输出详略。path_scope 按 glob 模式筛选。sessionBias 会提升当前 git 分支中条目的优先级
memory_tag	批量标签操作：按键或 ID 为一个或多个条目添加（add）、移除（remove）或设置（set）标签

MCP 资源

记忆也通过 MCP 资源开放，可直接读取上下文：

资源	URI	描述
记忆条目	toon://memory/entries	完整记忆转储
当前记忆	toon://memory/current	包含近期条目的当前记忆状态
记忆统计	toon://memory/stats	类别数量和 TTL 信息
系统概要	toon://memory/summaries	自动生成的知识图谱（热门条目、类别、模式）

MCP 提示词

提示词	描述
summarize_project_context	分析当前 TOON 记忆，并生成简洁的项目摘要。可选的 intent 参数可指定重点关注的领域

示例

记住一项决策

memory_remember({
  category: "decision",
  key: "use-zod",
  content: "Use Zod for validation — simpler than Joi, better TS support",
  file: "src/types.ts",
  tags: "validation;types"
})
// 🧠 Guardado: decision/use-zod (a1b2c3d4)
// Quality score: 0.65 (2 tags, detailed content)
// 🔗 Entradas relacionadas:
//   [pattern] zod-schemas — Shared Zod schemas for API validation

提示： 使用描述性键名，例如 use-zod，而不要使用 validation 这类模糊名称。Agent 会根据键名和内容进行搜索，因此越具体越好。使用相同的键保存时会自动合并（标签取并集，置信度取最大值）。

设置 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)
// ⏰ TTL: 2026-07-19
// Quality score is calculated automatically.

提示： 对截止日期、迭代信息或时效性备注等临时上下文使用 TTL。TTL 过期的条目会自动从搜索结果中过滤掉。

设置明确的重要性

memory_remember({
  category: "decision",
  key: "db-choice",
  content: "We chose Postgres over MySQL — JSONB for flexible schemas, better extension ecosystem",
  importance: "critical"
})
// 🧠 Guardado: decision/db-choice (a1b2c3d4)
// 🎯 Importance: critical (+0.3 boost) — surfaces above routine entries

提示： 将基础性决策标记为 critical，使其始终排在回忆结果的前列。importance 可设为 critical、high、medium 或 low；留空则由系统根据近期程度和频率自动排序。

自动推断标签

memory_remember({
  category: "bug",
  key: "redis-connection-timeout",
  content: "Redis connection timeout in production, increased pool size"
  // tags left empty — auto-inferred from content
})
// 🧠 Guardado: bug/redis-connection-timeout (a1b2c3d4)
// 🏷️ Tags inferidos: redis
// Quality score is calculated automatically based on inferred tags and content.

提示： 将 tags 留空，系统会使用内置的 20 多个类别词汇（redis、auth、api、db、security 等）以及在 init 时根据依赖项生成的项目词汇，从内容中推断标签。因此，如果项目依赖 redis，任何提到“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

提示： 先搜索，再读取文件。这样既能节省 token，也能为 Agent 提供单靠代码无法获得的上下文。按质量加权的排序会优先显示最有用的条目。也可以使用 memory_smart_recall 获取更全面的结果。

按日期筛选搜索

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

提示： 当你大致记得某件事发生的时间，但不确定具体内容时，可使用日期筛选。排序仍会按质量加权。

归档旧条目

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

提示： 定期运行此操作，让记忆保持精简。归档的条目仍可通过带日期筛选的 memory_recall 搜索。TTL 过期的条目也会自动归档。质量较低的条目在回忆时优先级较低。质量较低的条目在回忆时优先级较低。

显示上次会话以来的更改

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

提示： 在会话开始时使用 memory_diff，查看 Agent 自你上次处理项目以来学到的内容。新条目会包含质量评分。新条目会包含质量评分。

查找相关条目

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
//
// [bug] redis-pool-fix (i9j0k1l2)
//   Added max_connections=20
//   File: redis.ts | Tags: redis;fix | Date: 2026-07-10

提示： 当你需要了解某个主题的上下文，但不确定要搜索什么时，可使用 memory_suggest。也可以使用 memory_smart_recall 获取更全面的结果。

智能回忆（统一）

memory_smart_recall({ intent: "diseño de base de datos para backend" })
// [1] decision/use-postgres
//   Choose Postgres for ACID compliance and JSON support
//   tags: db;decision · edges: ->2
//
// [2] pattern/db-migrations
//   Use sequential migration files, never edit committed ones
//   tags: db;pattern · edges: ->1
//
// [3] bug/redis-timeout
//   Redis connection timeout — increased pool to 20
//   tags: redis;bug

提示： 每项任务开始时都使用 memory_smart_recall。它会在一次调用中结合 BM25、图、衰减和质量，无需猜测搜索内容。

解释返回结果的原因

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。想了解 Agent 为什么显示这些条目时，请使用 explain: true。

使用 budget_tokens 限制输出

memory_recall({ query: "redis", budget_tokens: 300 })
// Entries accumulate greedily; the tail that would exceed the estimate is dropped.
// budget_tokens: 0 (default) = no limit.

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

完整项目简报（一次调用）

context_generate({})
// # Project Briefing (full)
//
// ## Project
// - Name: my-app
// - Root: /path/to/project
// - Package Manager: npm
// - TypeScript: ✓ (v5.3)
//
// ## Git Status
// - Branch: main
// - 3 uncommitted, 0 untracked
//
// ## Memory (42 entries, 12 patterns, 8 bugs)
// [1] decision/use-postgres
//   Choose Postgres for ACID compliance
//   tags: db;decision
//
// ## Sessions
// - egraterol (main, 2m ago): 42 files touched

提示： 在会话开始时使用 context_generate，一次调用即可获取完整上下文。可替代 5-6 次单独的工具调用。

记忆健康审计

context_health({})
// # Memory Health (score: 87/100)
//
// ## Summary
// - 42 entries (12 patterns, 8 bugs, 15 decisions, 7 knowledge)
// - 65.3% average quality
//
// ## Issues (3)
// - Orphan link: pattern/db-migrations → pattern/db-seed (key not found)
// - Duplicate: [bug] redis-pool-fix has identical content
// - Expired TTL: [knowledge] sprint-deadline (expired 2026-07-20)
//
// ## Stale Files (1)
// - src/legacy.ts (deleted, 2 refs)

提示： 当记忆显得杂乱时，运行 context_health。它会显示孤立链接、重复项、已过期的 TTL 条目、损坏的文件引用、缺少证据的条目（没有文件的 path_scope）以及过时的声明（内容重叠）。

合并去重（自动）

使用相同的 key 保存时，属性会合并，而不是覆盖：

// First save
memory_remember({
  category: "decision",
  key: "use-zod",
  content: "Use Zod for validation",
  tags: "types"
})
// 🧠 Guardado: decision/use-zod (a1b2c3d4)

// Later save with same key — merges automatically
memory_remember({
  category: "decision",
  key: "use-zod",
  content: "Use Zod for validation — also handles API response parsing",
  tags: "types;api"
})
// 🧠 Actualizado: decision/use-zod (a1b2c3d4)
// 🔗 Merge: tags combinados, fecha y links actualizados
// Tags now: "types;api" (union of both)

提示： 使用描述性强且稳定的键。相同的键 = 合并，不同的键 = 新条目。

质量评分

每个条目都会根据结构自动获得质量分数（0–1）：

因素	权重	衡量标准
标签	最高 0.3	标签越具体，质量越高
链接	最高 0.2	关联条目越多，质量越高
内容长度	最高 0.3	详细内容优于含糊内容
新近度	最高 0.1	越新的条目，分数越高
具体程度	最高 0.1	唯一词语与重复词语的对比
来源	+0.1/−0.05	人工陈述加分，推断内容略微扣分

高质量条目会优先显示在回忆结果中。使用 memory_stats 查看质量：

memory_stats()
// ...
// Calidad promedio: 0.58 (12 con score)

置信度分数

每个条目都会记录信息的可靠程度：

来源	置信度	含义
用户陈述	1.0	“我们使用 Postgres”——直接陈述
推断	0.65–0.75	Agent 根据上下文推断
不确定	0.50	Agent 在猜测

合并时会保留置信度（取两个条目中的较高值）。

系统摘要

系统摘要是自动生成的知识地图，以 MCP 资源的形式公开。Agent 会在会话开始时加载它，以立即获取上下文：

// Exposed as toon://memory/summaries
// Auto-regenerates on every read
// Contains: top entries, categories, patterns

提示： 将 toon://memory/summaries 添加到 Agent 的系统提示词中，以便在会话开始时立即获取上下文。

启用加密

// First, set TOON_MEMORY_KEY in your environment (or .env file):
// export TOON_MEMORY_KEY="your-secret-key-here"

memory_encrypt()
// 🔐 Encriptación habilitada

警告： 加密前必须通过 TOON_MEMORY_KEY 环境变量设置加密密钥。请将密钥保存在安全的地方——如果丢失，记忆数据将永远无法找回。加密过程中会保留质量分数和置信度。

---

多会话协调

当你并行运行多个 AI Agent 会话时（例如，在同一个仓库中同时运行三个 OpenCode 会话），它们可能会意外覆盖彼此的工作。toon-memory 内置了 memory_sessions，这是一种基于文件的协调工具，可让每个会话了解其他会话正在做什么——无需服务器、网络或 LLM 调用。

工作原理

• 启动时，SessionStart 钩子会在 .toon-memory/memory/sessions/<id>.json 为该会话写入一个心跳文件。每个进程只写入自己的文件，因此不会发生锁竞争。
• 心跳会记录 Agent 名称、git 分支、修改过的文件以及最后出现时间戳。
• 读取所有这些文件后，每个会话都能获得一个共享且最终一致的视图，了解还有哪些会话处于活动状态。
• 对已结束的会话（进程 PID 已不再运行，且心跳已超过 TTL 时间窗口）进行延迟清理。

memory_sessions 工具

memory_sessions({ conflictsOnly: false })
// 🧭 Sesiones activas (2) — ventana 30 min:
//
// • opencode @ feature/auth (tú)
//   id: a1b2c3d4
//   hace 2 min
//   Archivos:
//     • src/auth.ts
//
// • claude @ feature/db
//   id: e5f6g7h8
//   hace 9 min
//     • src/db.ts
//
// 🔥 Conflictos suaves (1):
//   ⚠️ src/types.ts  ↔  opencode @ feature/auth, claude @ feature/db

• 传入 conflictsOnly: true 可跳过会话列表，仅显示软冲突：

  memory_sessions({ conflictsOnly: true })
  // 🔥 Conflictos suaves (1):
  //
  // ⚠️ src/types.ts
  //    ↔ opencode @ feature/auth (a1b2c3d4), claude @ feature/db (e5f6g7h8)
  

• 软冲突是指有 2 个或更多活动会话修改了同一文件——这会提醒你可能正在编辑相同的代码。这不是硬性锁定，只是协调提醒。

推荐的并行会话习惯

1. 每次会话开始时，SessionStart hook 已会打印其他活跃会话和任何软冲突。
2. 运行 memory_smart_recall({ intent: "what I'm working on" })，获取完整上下文（记忆 + 图谱 + 质量）。
3. 运行 memory_sessions() 查看完整情况（分支、文件、上次出现时间）；如果只关心冲突，则运行 memory_sessions({ conflictsOnly: true })。
4. 如果你与另一个会话共用一个文件，请先协调，再进行编辑，以免覆盖彼此的更改。

提示： 这完全在本地运行，且无需锁定机制，可放心随时运行。在会话开始时将其与 memory_smart_recall({ intent: "project context" }) 结合使用，可同时获取跨会话记忆和跨会话在线状态。系统引导信息（MCP 资源）也能提供即时上下文。

---

记忆图谱（基于图谱的召回）

随着记忆不断增长，扁平的关键词搜索可能返回过多结果（每个匹配项），或返回错误的上下文（没有关联关系）。toon-memory 可以将记忆视为一个轻量级知识图谱，让召回用更少的 token 返回正确条目。结合质量评分后，最有用的条目会优先显示。

它完全确定且离线运行——不需要嵌入、向量数据库、大模型或服务。边来自两个来源：

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

工作原理

1. memory_remember 会将 links 存储在条目中（键之间以空格或 ; 分隔）。质量分数会自动计算。
2. memory_recall({ mode: "graph" }) 会查找关键词匹配项（种子），然后沿着边扩展自我子图，最多扩展 hops（1 或 2）跳。
3. 相关性会从种子传播到相邻条目，因此即使相关决策或规范中不含查询词，也会被显示出来。按质量加权的排序会确保最有用的条目优先显示。
4. 结果集有上限（limit，默认值为 6）→ 为 Agent 提供更小、更精准的上下文。也可以使用 memory_smart_recall 进行统一调用。

使用链接保存记忆

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)
// Quality score is calculated automatically based on tags, links, and content detail.

使用图谱模式进行召回

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

提示： 当一个决策会影响多个条目（架构、规范、相关 Bug）时，使用 mode: "graph"。对于互不相关的事实，默认的 flat 模式就足够了。也可以使用 memory_smart_recall，它会自动结合图谱 + BM25 + 质量评分。

节省 token 的召回（compact）

当每个 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 只会调整响应格式。

提示： 从大型互相关联的记忆中召回时，将 compact: true 与 mode: "graph" 结合使用，可获得最小的上下文窗口。对于主动式／后台召回，使用 budget: "tiny"，它只会返回键和一行内容（约 50 个 token）。也可以直接使用 memory_smart_recall，它会自动完成这些操作。

Recall 如何为结果排序

Recall 具有确定性，且可离线运行（不使用嵌入或 LLM）。每个候选条目都会获得一个综合评分：

• BM25 相关性 — 根据查询计算经典的概率型词频评分，使用 id + category + key + content + file + tags + quality + confidence。
• 图中心性 — 按度数归一化（0..1）；连接许多条目的枢纽得分接近 1，因此即使查询中没有对应词也会浮现。
• 重要性 — 新近程度 + 访问频率（与其他地方使用的信号相同）。
• 质量加成 — 质量评分较高（标签、链接和细节更多）的条目会获得排名加成。
• 种子加成 — 与查询直接匹配的条目会获得固定加成。
• 逐跳衰减 — 距离种子 d 跳的节点会乘以 0.5^d，因此较远的上下文排名低于较近的上下文。

在 graph 模式下，recall 会根据关键词匹配选取种子，将自我子图扩展至 hops 跳，并按综合评分返回排名前 limit 个结果（默认为 6）。memory_smart_recall 会在一次调用中综合所有这些信号。

根据项目依赖自动添加标签

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

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

随后，memory_remember 会在内置词汇表的基础上，将新条目与此词汇表匹配，因此内容中提及某个依赖时，会自动附加相应标签。标签越多 = 质量评分越高。支持的清单：package.json、Cargo.toml、requirements.txt、pyproject.toml、go.mod。

提示： 添加主要依赖后，重新运行 toon-memory init 以刷新词汇表。vocab 键会与 config.json 中的 encrypted/capture 标志合并（绝不会覆盖它们）。标签越多 = 质量评分越高。

---

记忆图查看器

将记忆可视化为交互式力导向图。一目了然地查看条目、它们之间的连接、类别和访问模式。

CLI 查看器（独立 HTTP 服务器）

npx toon-memory viewer          # Start HTTP server + open browser
npx toon-memory viewer --port 3001  # Custom port
npx toon-memory viewer --export     # Save as static HTML

打开后，可在终端中按 r 从磁盘重新加载，或在浏览器中按 r / 点击 ↻ 刷新页面。

内嵌查看器（MCP Apps）

在任何兼容 MCP Apps 的宿主中调用 memory_visualize，即可内嵌呈现图表——无需服务器。查看器会以交互面板的形式显示在聊天界面中。

功能

交互	说明
悬停 节点	查看包含内容预览、质量和访问次数的工具提示
点击 节点	选中 + 居中 + 高亮相邻节点
双击 节点	打开详情面板
拖动 节点	手动重新定位（右键点击可取消固定）
搜索	筛选条目；匹配的节点会发出脉冲光晕
⇿ 路径查找器	点击两个节点以查找并高亮最短路径
缩放/平移	使用鼠标滚轮或 +/− 按钮
⚙ 物理设置	调整电荷、链接距离和中心引力
主题切换	深色/浅色模式（会保存设置）
导出	将图表保存为 PNG 或 SVG

截图

图表视图	搜索高亮	路径查找器	详情面板

截取自己的截图

npm run capture:viewer

需要 Playwright（npx playwright install chromium）和 ffmpeg。

---

提示与最佳实践

以下是一些适用于 toon-memory 的做法：

“会话开始”习惯

每次开始新会话时，运行：

memory_smart_recall({ intent: "what I was working on" })

这会让你的 Agent 立即了解此前发生的事情——在一次调用中综合 BM25、图、质量和衰减。

“会话结束”习惯

关闭会话前，保存所有重要内容：

memory_remember({
  category: "decision",
  key: "auth-approach",
  content: "Chose JWT over sessions — stateless, works across microservices",
  file: "src/auth.ts",
  tags: "auth;architecture"
})

系统会根据条目的结构（标签、内容细节、链接）自动为其评分。

选择类别

类别	适用场景
decision	架构选择、权衡、“为什么选 X 而不是 Y”
pattern	约定、框架、代码风格规则
bug	已修复的问题及修复方法
knowledge	项目事实、领域信息、团队背景
warning	“不要这样做”——反模式、陷阱、应避免的错误（回忆时会提高优先级）

提示： 不要想得太复杂。如果是未来的你（或 Agent）可能想了解的内容，就保存下来。内容详尽且标签具体的条目质量评分更高。

实用标签

使用分号分隔标签，方便筛选：

tags: "redis;performance;fix"
tags: "auth;jwt;security"
tags: "api;rest;versioning"

提示： 标签要简短且一致。它们不是主题标签，而是搜索筛选条件。标签越具体，质量评分越高。

不要保存的内容

• 不要保存阅读代码就能显而易见的内容
• 不要保存临时调试笔记
• 不要保存机密、API 密钥或凭据（改用环境变量）
• 不要用不同的键重复保存相同信息（merge-dedup 会自动处理相同键）
• 没有标签的模糊条目质量评分较低——请写具体

保持记忆整洁

每月运行 memory_archive()，将旧条目移至归档。运行 memory_stats()，检查条目数量和质量分布。低质量条目（内容模糊、没有标签）会自动降低回忆优先级。使用 memory_consolidate 合并重复项，并使用 mode: "versions" 淘汰已被较新库版本取代的笔记。

---

CLI 命令

npx toon-memory              # Interactive installer
npx toon-memory init         # Quick setup (no prompts)
npx toon-memory mcp          # Run MCP server directly
npx toon-memory status       # Check installation status
npx toon-memory stats        # View memory statistics
npx toon-memory export       # Export memory to JSON
npx toon-memory import <file> # Import memory from JSON
npx toon-memory viewer       # Open the memory graph viewer (http server)
npx toon-memory viewer --export # Save viewer as static HTML
npx toon-memory viewer --port 3001 # Custom port
npx toon-memory watch [options] # Auto-backup with options
npx toon-memory upgrade      # Update to latest version
npx toon-memory uninstall    # Remove from all agents

示例

统计信息

$ npx toon-memory stats

🧠 toon-memory stats

📊 Memory Stats
━━━━━━━━━━━━━━━━━━
Total entries: 45
├── decision: 12
├── pattern: 18
├── bug: 8
└── knowledge: 7
Last updated: 2026-07-10
File size: 12.4 KB

提示： 如果记忆条目过多（100 条以上），可以考虑归档，或使用 memory_forget 删除过时条目。

导出

$ npx toon-memory export

🧠 toon-memory export

Exported 45 entries to:
  /path/to/project/toon-memory-export.json

提示： 在重大重构前进行导出。如果出现问题，之后随时可以导入备份。

导入

$ npx toon-memory import backup.json

🧠 toon-memory import

Imported 3 new entries
Skipped 2 duplicates

提示： 系统根据键检测重复项。如果要重新导入某个条目，请先使用 memory_forget 删除旧条目。

监视

$ npx toon-memory watch 15 -c -m 20

🧠 toon-memory watch

Watching memory file every 15 minutes...
Max backups: 20
Compression: enabled
Logging: disabled
Press Ctrl+C to stop

📦 Backup #1 created: 2026-07-11T16-00-00-000Z
📦 Backup #2 created: 2026-07-11T16-15-00-000Z
^C
✅ Watch stopped. 2 backups created.

提示： 监视模式非常适合长时间运行的会话。使用 -c 进行压缩，并使用 -m 5 只保留 5 个备份。

监视选项：

选项	说明	默认值
[interval]	备份间隔（分钟）	5
-c, --compress	启用 gzip 压缩	关闭
-l, --log [path]	启用文件日志记录	关闭
-m, --max-backups <n>	保留的最大备份数（0=不限）	10

---

配置

交互式安装程序（推荐）

npx toon-memory

安装程序（需要终端）将会：

1. 显示全部 22 个受支持的 Agent、检测状态（找到配置时显示 ✓）以及支持的范围（local/global 或 solo local）
2. 让你选择要配置的 Agent——可以按编号（1,3,5）、按名称（claude,codex）、输入 all、按 Enter 全选，或输入 q 退出
3. 询问安装范围：(1) Local（项目级：仓库中的 .toon-memory 和 Agent 配置）或 (2) Global（~home 配置）
4. 显示确认摘要（agent → scope → path (MCP/plugin/hooks/instrucciones)），并询问 ¿Proceder? [Y/n]
5. 自动配置 MCP 服务、说明文件和钩子

没有终端时（CI/管道环境），npx toon-memory 会显示非交互式安装帮助。使用 npx toon-memory init [local|global] 无需回答问题即可安装。未知命令会显示用法并报错退出。

OpenCode

添加到 .opencode/opencode.json 或 ~/.config/opencode/opencode.json：

{
  "mcp": {
    "toon-memory": {
      "type": "local",
      "command": ["npx", "-y", "toon-memory", "mcp"],
      "enabled": true
    }
  }
}

钩子通过插件提供，而不是顶层的 hooks 键。OpenCode 1.17+ 会在配置中遇到 "Unrecognized key: hooks" 时拒绝配置——toon-memory init 会改为写入 .opencode/plugins/toon-memory.ts。不要在 opencode.json 中添加 hooks。

Claude Code

添加到 .mcp.json（项目根目录）：

{
  "mcpServers": {
    "toon-memory": {
      "command": "npx",
      "args": ["-y", "toon-memory", "mcp"]
    }
  }
}

VS Code / Copilot

添加到 .vscode/mcp.json：

{
  "servers": {
    "toon-memory": {
      "command": "npx",
      "args": ["-y", "toon-memory", "mcp"]
    }
  }
}

Codex CLI

添加到 .codex/config.toml：

[mcpServers.toon-memory]
command = "npx"
args = ["-y", "toon-memory", "mcp"]

Gemini CLI

添加到 .gemini/settings.json：

{
  "mcpServers": {
    "toon-memory": {
      "command": "npx",
      "args": ["-y", "toon-memory", "mcp"]
    }
  }
}

Zed

添加到 ~/.config/zed/settings.json：

{
  "mcp_servers": {
    "toon-memory": {
      "command": "npx",
      "args": ["-y", "toon-memory", "mcp"]
    }
  }
}

提示： 如果希望所有项目都使用记忆，请使用全局配置。如果只想在特定项目中使用，请使用项目级配置。

---

工作原理

1. MCP 服务 — 在本地运行，通过 stdio 与 Agent 通信
2. TOON 格式 — 以 Token-Oriented Object Notation 存储数据（与 JSON 相比，令牌数减少约 22.5%；基于 16 条条目使用 gpt-tokenizer 测量）。每条条目都会自动记录质量（0–1）和置信度（0–1）。
3. 项目级记忆 — 每个项目都有 .toon-memory/memory/data.toon
4. 零配置 — 只需安装即可使用

记忆文件格式

version: 1
entries[3|]{id|category|key|content|file|tags|date|ttl|accessed|links|quality|confidence|lastAccessed|priority|path_scope|origin|status|supersededOn|importance|evidence}:
  a1b2c3d4|decision|use-zod|Use Zod for validation|src/types.ts|validation;types|2026-07-10||0||0.65|1.0||0||agent|active|||verified
  e5f6g7h8|pattern|pydantic-configs|Project uses Pydantic v2|config.py|python;patterns|2026-07-10||0||0.55|1.0||0||agent|active|||
  i9j0k1l2|bug|redis-pool-fix|Added max_connections=20 (see [[use-zod]])|redis.ts|redis;fix|2026-07-10|7d|0|use-zod|0.70|0.9||0||agent|active|||conflict
summaries:
  src/services/redis.ts: Redis connection pool with retry logic

文件结构

.toon-memory/
├── memory/
│   ├── data.toon        # Main memory file
│   ├── archive.toon     # Archived entries (>30 days)
│   ├── config.json      # Encryption settings
│   └── backups/         # Watch mode backups
│       ├── backup-2026-07-11T16-00-00-000Z.toon
│       └── backup-2026-07-11T16-10-00-000Z.toon
└── hooks/
    ├── session-start-claude.sh
    ├── session-start-codex.sh
    ├── session-start-gemini.sh
    └── session-start-antigravity.sh

---

为什么选择 TOON？

TOON（Token-Oriented Object Notation）专为大模型设计：

格式	令牌数（16 条条目）
JSON	1097
TOON	850

使用 gpt-tokenizer（cl100k_base）对 16 条有代表性的记忆条目进行测量 — 参见 scripts/benchmark-toon.mjs（npm run bench）。

令牌节省在会话期间会累积：npm run bench:impact 会模拟有记忆与无记忆时检索上下文，并测量得出使用相同上下文所需的令牌数减少约 68%（召回 compact，而不是重新读取源文件）。完整会话基准测试（npm run bench:full）显示，使用 context_* 工具时，工具调用减少 80%，令牌数减少 47%。

• 文件级别的令牌数比 JSON 减少 22.5%（单条条目最多减少 30.5%）
• 无损往返 — 不会丢失数据
• 更易于大模型理解 — 采用适合 AI 使用的结构
• 质量与置信度 — 每条条目都会自动记录结构质量（0–1）和可靠性（0–1）

提示： 令牌数越少 = 响应越快 + API 成本越低。你的 Agent 会在每次会话开始时读取记忆文件，因此效率很重要。

---

基准测试：toon-memory 与替代方案对比

功能	toon-memory	@modelcontextprotocol/server-memory	mem0	shodh-memory
存储	本地文件（TOON）	本地文件（JSON）	云端	RocksDB
依赖项	无	无	云 API	sentence-transformers、RocksDB
搜索	BM25 + 图谱 + 质量	基础关键词	仅向量	混合（向量 + 图谱）
令牌效率	比 JSON 少 22.5%	基准（JSON）	不适用（云端）	相近
质量评分	自动（0–1，启发式）	无	无	BND 算法
合并去重	标签合并 + 置信度取最大值	无	无	内容去重
置信度跟踪	按条目（0–1）	无	无	按条目
系统初始提示	自动生成	无	无	无
多会话	基于文件的协调	无	不适用	无
钩子	15 个 Agent	无	无	仅 Claude
加密	AES-256-GCM	无	云端管理	无
设置时间	npx toon-memory	手动 JSON	注册云服务	Docker + 配置

令牌效率（实测）

Format          Tokens (16 entries)    vs JSON
──────────────  ───────────────────    ───────
JSON            1097                   baseline
TOON            850                    -22.5%

召回效率（实测）

Method                          Tokens to get context    vs re-reading files
──────────────────────────────  ─────────────────────    ───────────────────
Re-read source files            ~3000                    baseline
memory_recall (flat)            ~1200                    -60%
memory_recall (graph, compact)  ~900                     -70%
memory_smart_recall             ~850                     -72%

Context 工具基准测试（实测）

context_* 工具可将 3–6 次单独的工具调用合并为一次调用，节省令牌和工具调用开销。

Scenario                          Without   With    Saved    Tools
────────────────────────────────  ────────  ──────  ───────  ──────
context_generate (full briefing)    5,556     378    93.2%   6 → 1
context_diff (incremental)            533     152    71.5%   4 → 1
context_focus (targeted)              413     225    45.5%   4 → 1
context_health (audit)                322     246    23.6%   5 → 1
context_export (injectable md)      1,178     218    81.5%   3 → 1
────────────────────────────────  ────────  ──────  ───────  ──────
TOTAL                              8,002   1,219    84.8%  22 → 5

各场景的测量内容：

工具	不使用（手动流程）	使用（单次调用）	节省原因
context_generate	读取 package.json + README + tsconfig.json + 完整记忆转储 + 记忆统计 + 会话 = 6 次调用	一份包含所有内容的精简简报	消除 5 次冗余读取；输出经过去重和精简
context_diff	git log + git diff --name-only + memory_diff + 会话 = 4 次调用	一份增量差异	将 git 状态和记忆变更合并到一个输出中；没有重叠内容
context_focus	memory_recall + findCallers + findRelatedFiles + findTestFiles = 4 次调用	一份针对性简报	只返回相关内容；无需扫描完整记忆
context_health	memory_stats + 孤立项扫描 + 重复项扫描 + 文件引用验证 + 过时会话扫描 = 5 次调用	一份健康报告	每项检查只执行一次并去重；没有冗余查询
context_export	memory_stats + memory_recall({ compact: true, mode: "graph" }) + 手动格式化 = 3 次调用	一份 Markdown 导出	直接格式化输出；Agent 跳过“格式化为 Markdown”步骤

提示： 在会话开始时使用 context_generate（节省 93% 的令牌）。使用 context_diff 查看“自上次以来发生了什么变化？”（节省 72%）。使用 context_focus 深入了解特定主题（节省 45%）。

使用 gpt-tokenizer（cl100k_base）在真实项目场景中测量——参见 scripts/bench-context-tools.mjs（npm run bench:context）。

完整会话影响（实测）

模拟一个完整的 5 阶段 Agent 会话（会话开始 → 调试 → 实现 → 审查 → 收尾），比较 3 种方式：不使用记忆、使用 memory_recall，以及使用 context_* 工具。

Phase                                   Without memory     memory_recall      context_* tools
──────────────────────────────────────  ─────────────────  ─────────────────  ─────────────────
Phase 1: Session Start                  516 t /  6 c       409 t /  3 c       373 t /  1 c
Phase 2: Debug Issue                    176 t /  4 c       182 t /  2 c       252 t /  1 c
Phase 3: Implement Feature              189 t /  6 c       183 t /  3 c       305 t /  1 c
Phase 4: Code Review                    316 t /  4 c       130 t /  2 c       243 t /  1 c
Phase 5: Wrap-up                      1,214 t /  5 c        68 t /  2 c       117 t /  1 c
──────────────────────────────────────  ─────────────────  ─────────────────  ─────────────────
TOTAL                                 2,411 t / 25 c       972 t / 12 c     1,290 t /  5 c

主要发现：

指标	不使用记忆	使用 memory_recall	使用 context_* 工具
每次会话的令牌数	2,411	972 (-60%)	1,290 (-47%)
每次会话的工具调用次数	25	12 (-52%)	5 (-80%)
每次会话的成本（GPT-4）	$0.072	$0.029	$0.039

权衡： memory_recall 使用的令牌更少（972 对比 1,290），因为它只返回匹配的条目。context_* 工具会返回更丰富的上下文（调用方、相关文件、测试文件、健康审计）——每次调用使用更多令牌，但工具调用次数减少 80%。实际使用中，Agent 无需再进行 context_focus 已包含的 3–4 次“查找相关内容”后续调用。

context_ 优势显著的场景：*

• 会话开始（阶段 1）：令牌减少 28%，调用次数从 6 次降至 1 次——一份简报取代读取 6 个文件
• 收尾（阶段 5）：令牌减少 90%——context_health 取代 5 次手动扫描
• 工具调用：调用次数从 25 次降至 5 次 = 每次会话的延迟开销减少 80%

提示： 需要特定条目时使用 memory_recall（令牌更少）。需要以更少往返次数获取全面上下文时使用 context_*（调用更少）。

使用 gpt-tokenizer（cl100k_base）测量——参见 scripts/bench-full-impact.mjs（npm run bench:full）。

提示： memory_smart_recall 可在一次调用中结合 BM25、图和质量，节省令牌和工具调用开销。每项任务开始时都应使用它。

RRF 排序基准测试（实测）

从 v3.7.0 开始，召回会使用 Reciprocal Rank Fusion 对 BM25（×3）和图中心性排名进行融合，并采用自适应 k = clamp(3..60, round(sqrt(n)))。基于 8 个黄金标准查询及人工标注的相关性进行测量（参见 scripts/bench-rrf.mjs，npm run bench:rrf）：

Metric        linear (v3.6.x)     RRF (v3.7.0)
────────────  ─────────────────   ────────────────
nDCG@10       0.776               0.776   (parity)
MRR           0.917               0.917   (parity)

RRF 在排序成本为零的情况下，效果与之前的线性加权分数相当，同时简化了评分流程（BM25×3 + 中心性，不受重要性／时效性噪声影响）。图模式会遵循条目的取代关系：过时条目仍会被排除，但 as_of 时间点查询除外。

检索基准测试（LongMemEval 风格，实测）

从 v4.1.0 开始，检索基准测试基于真实项目记忆的冻结快照——一组 LongMemEval 风格的测试集，包含人工编写的标准查询。语料库：187 条真实的 data.toon 条目（快照日期为 2026-08-01），涵盖 6 个类别的 42 条标准查询（核心事实、时间、知识更新、多跳、元数据/会话、干扰项）。实测代码采用生产环境流水线（src/lib），通过 esbuild 捆绑并在内存中运行——没有忠实副本。确定性的 today 参数固定了时效性/衰减，避免结果随系统时钟变化；运行过程只读（不跟踪访问情况）。两个描述数据文件本身的优先级元条目不计入。参见 benchmarks/retrieval-corpus.toon、benchmarks/gold-queries.json（npm run bench:retrieval）：

Mode            R@5     nDCG@5  MRR@5   answerable
─────────────   ─────   ─────   ─────   ──────────
linear         0.643   0.654   0.776   81.0%
rrf            0.861   0.764   0.788   97.6%
smart (unified) 0.829  0.739   0.760   92.5%

RRF 是排名最高的模式（R@5 为 0.861，97.6% 的查询可从前 5 条结果中找到答案）；memory_smart_recall 在单次调用中仍具有竞争力。

---

故障排除

安装后找不到记忆

症状： Agent 表示没有记忆工具。

解决方法：

1. 运行 npx toon-memory status 验证安装
2. 完全重启 Agent（关闭后重新打开）
3. 检查 MCP 配置文件是否存在且为有效的 JSON

记忆文件为空

症状： memory_stats 显示 0 条记录。

解决方法： 首次安装时这属于正常情况。开始使用 memory_remember 保存条目。

重复条目

症状： 同一个键出现多次。

解决方法： 现在，使用相同键调用 memory_remember 会自动合并（合并标签、取最高置信度、采用最新日期）。使用 memory_consolidate 合并所有同键条目并删除内容完全重复的条目。手动清理请使用 memory_forget。

加密密钥丢失

症状： 无法解密记忆。

解决方法： 遗憾的是，密钥无法恢复。生成后，加密密钥不会存储在任何地方。这是出于安全考虑的设计。你需要重新开始，或从未加密的备份中恢复。

记忆过大

症状： Agent 响应缓慢。

解决方法：

1. 运行 memory_archive() 将旧条目移至存档
2. 使用 memory_forget 删除无关条目
3. 保持条目简洁——保存决策，而非整段对话
4. 低质量条目（内容含糊、没有标签）会自动降低召回优先级

---

常见问题

这适用于任何 AI Agent 吗？

是的，只要它支持 MCP（Model Context Protocol）。我们为 22 个 Agent 提供自动设置，其他 Agent 可手动配置。

我的数据会被发送到其他地方吗？

不会。所有数据都保留在你的设备上。MCP 服务通过 stdio 在本地运行——没有网络请求、没有遥测数据，也不使用云服务。

我能在多台设备上使用吗？

可以，只要同步 .toon-memory/memory/ 目录（例如，通过 Git 或共享文件夹）。每台设备都需要安装 toon-memory，但记忆文件可以移植。

如果我有多个项目，会怎样？

每个项目都有自己的记忆文件。不同项目之间不会泄露记忆。

我能只加密特定条目吗？

不能，加密会应用于整个记忆文件。如果需要选择性加密，请将敏感数据保存在单独的工具中。

这和直接使用 Markdown 文件有什么区别？

Markdown 文件没有结构化，Agent 无法以相同方式搜索它们，也无法通过 MCP 集成；此外，它们不具备归档、日期筛选、质量评分、合并去重、置信度跟踪或加密等功能。toon-memory 是专为 AI Agent 打造的。

---

开发

git clone https://github.com/LuiggiVal08/toon-memory.git
cd toon-memory
npm install
npm run build
npm test

项目结构

toon-memory/
├── src/
│   ├── bin/
│   │   └── toon-memory.ts      # Entry point
│   ├── cli/
│   │   ├── setup.ts             # CLI commands
│   │   └── toon-memory.ts       # CLI runner
│   ├── mcp/
│   │   ├── server.ts            # MCP server (38 tools + 4 resources + 1 prompt)
│   │   ├── tools.ts             # Tool registration (38 tools)
│   │   ├── resources.ts         # Resource registration (4 resources)
│   │   ├── prompts.ts           # Prompt registration (1 prompt)
│   │   ├── session-store.ts     # Session layer (auto-promote, cleanup)
│   │   ├── memory-io.ts         # Memory file read/write
│   │   ├── entries.ts           # Entry parsing & utilities
│   │   ├── scoring.ts           # Entry scoring & access tracking
│   │   ├── archive.ts           # Archive management
│   │   ├── consolidation.ts     # Duplicate consolidation
│   │   ├── config.ts            # Config loading & saving
│   │   └── crypto.ts            # AES-256-GCM encryption
│   ├── lib/
│   │   ├── lock.ts              # Advisory file lock + atomic write
│   │   ├── sessions.ts          # Multi-session coordination
│   │   ├── graph.ts             # Memory graph (parse, build, BM25, centrality, compact render)
│   │   ├── quality.ts           # Quality scoring, merge-dedup, smart recall, system primer
│   │   ├── context.ts           # Context briefing generator (one-call context)
│   │   └── vocab.ts             # Project-vocabulary discovery from dependencies
├── tests/
│   ├── cli.test.ts              # CLI tests
│   ├── memory.test.ts           # Memory tests
│   ├── sessions.test.ts         # Multi-session tests
│   ├── graph.test.ts            # Memory graph tests
│   └── quality.test.ts          # Quality scoring, merge-dedup, smart recall, system primer tests
├── .github/workflows/
│   ├── ci.yml                   # CI (Node.js 20/22)
│   └── publish.yml              # Auto-publish on release
├── package.json
├── tsconfig.json
└── vitest.config.ts

---

贡献

欢迎贡献！请先阅读我们的行为准则和贡献指南。

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'feat: add amazing feature'）
4. 推送到该分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

---

安全与隐私

toon-memory 将安全与隐私作为核心设计原则。

• 100% 本地存储 — 所有记忆都存储在您设备的 .toon-memory/memory/ 中。不会向外部服务、云服务或第三方发送任何数据。
• 无遥测 — 本项目完全不包含任何遥测、分析或跟踪功能。不会收集任何使用数据。
• 不执行远程代码 — toon-memory 通过 stdio 作为标准 MCP 服务运行。它不会下载、执行或评估远程代码。
• 静态加密 — 可选使用 AES-256-GCM 对整个记忆文件进行加密。启用 memory_encrypt（需要 TOON_MEMORY_KEY 环境变量）。
• 加密密钥绝不存储 — 必须通过环境变量提供加密密钥，toon-memory 绝不会持久化该密钥。若密钥丢失，数据将无法恢复。
• 按项目隔离 — 每个项目都有独立的记忆文件。项目之间的记忆不会泄漏。
• 自动添加 .gitignore — 安装程序会将 .toon-memory/memory/ 添加到 .gitignore，以防意外提交记忆数据。

---

许可证

MIT

---

致谢

基于 @toon-format/toon 和 @modelcontextprotocol/server 构建。