面向 AI 代理的 Token 高效记忆 — 比 JSON 少 22% Token

为什么 Token 效率重要

你的 AI 代理处理的每个 token 都有成本和时间开销。当代理在会话启动时读取记忆文件，这些文件的格式直接影响：

• 费用 — 更少 token = 更低的 API 账单
• 速度 — 更少 token = 更快的响应
• 上下文窗口 — 更少 token = 更多空间用于实际工作

toon-memory 使用 TOON 格式（Token-Oriented Object Notation），具有以下特点：

• 比 JSON 效率高 22%，更适合 LLM 处理
• 为 AI 理解优化 — 针对 LLM 处理信息的方式设计
• 无损 — 无数据丢失，完整往返支持

Token 效率基准测试

文件级效率

格式              Token 数 (16 条目)    对比 JSON
──────────────  ───────────────────    ───────
JSON            1097                   基准
TOON            850                    -22.5%

会话级影响

方法                              获取上下文的 Token 数    对比重读文件
────────────────────────────  ─────────────────────    ───────────────────
重新读取源文件                    ~3000                    基准
memory_recall (平铺)             ~1200                    -60%
memory_recall (图, 紧凑)         ~900                     -70%
memory_smart_recall              ~850                     -72%

完整会话基准

模拟一个完整的 5 阶段代理会话：

阶段                                    无记忆         使用 memory_recall    使用 context_* 工具
─────────────────────────────────────  ─────────────────  ─────────────────       ─────────────────
阶段 1：会话启动                        516 t /  6 c       409 t /  3 c            373 t /  1 c
阶段 2：调试问题                        176 t /  4 c       182 t /  2 c            252 t /  1 c
阶段 3：实现功能                        189 t /  6 c       183 t /  3 c            305 t /  1 c
阶段 4：代码审查                        316 t /  4 c       130 t /  2 c            243 t /  1 c
阶段 5：收尾                          1,214 t /  5 c        68 t /  2 c            117 t /  1 c
─────────────────────────────────────  ─────────────────  ─────────────────       ─────────────────
总计                                 2,411 t / 25 c       972 t / 12 c          1,290 t /  5 c

结果：

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

TOON 格式的工作原理

传统 JSON

{
  "id": "a1b2c3d4",
  "category": "decision",
  "key": "use-zod",
  "content": "Use Zod for validation",
  "file": "src/types.ts",
  "tags": "validation;types",
  "date": "2026-07-10"
}

TOON 格式

a1b2c3d4|decision|use-zod|Use Zod for validation|src/types.ts|validation;types|2026-07-10

TOON 格式的特点：

• 使用 | 作为分隔符（比 " 和 : 和 , 消耗更少 token）
• 字符串不加引号
• 无花括号
• 紧凑但仍可人类阅读

Token 高效召回模式

平铺模式（默认）

memory_recall({ query: "redis" })
// 返回匹配的条目及完整详情

图模式

memory_recall({ query: "redis", mode: "graph", hops: 2 })
// 通过图连接展开相关条目

紧凑模式

memory_recall({ query: "redis", compact: true })
// 返回数字索引的条目，移除 id/date/file
// 图边渲染为 ->2, ->3

智能召回（推荐）

memory_smart_recall({ intent: "database configuration" })
// 一次调用组合 BM25 + 图 + 质量
// 在每次任务开始时使用

各模式使用场景

模式	最适合	Token 成本
平铺	简单关键词搜索	中等
图	相互关联的决策	低（紧凑）
紧凑	Token 受限的上下文	最低
智能	未知搜索词	中等（全面）

费用节省计算器

假设 GPT-4 定价（$0.03/1K 输入 token）：

场景	无记忆	使用 toon-memory	节省
每天 10 次会话	$0.72/天	$0.29/天	$0.43/天
每月 30 次会话	$21.60/月	$8.70/月	$12.90/月
每年 365 次会话	$262.80/年	$105.85/年	$156.95/年

开始使用

npm install -g toon-memory
npx toon-memory  # 交互式安装器

你的代理将在下一次会话中使用 token 高效的记忆。