如何为 Claude、Cursor 和 OpenCode 设置持久化记忆

为什么你需要持久化记忆

Claude、Cursor 和 OpenCode 等 AI 编程代理功能强大 — 但有一个关键限制：在会话之间没有记忆。

每次开始新会话时，你的代理：

• 忘记昨天的架构决策
• 不记得你发现的缺陷修复
• 无法回忆你团队建立的模式
• 必须从头重新学习你的项目

这浪费了 token、消耗了时间，并导致令人沮丧的重复。

toon-memory 通过为你的代理提供跨重启存活的持久化记忆来解决这个问题。

快速设置（2 分钟）

第 1 步：安装 toon-memory

npm install -g toon-memory

第 2 步：运行安装器

npx toon-memory

安装器将：

1. 检测你安装了哪些代理
2. 询问要配置哪些代理
3. 自动添加 MCP 配置

第 3 步：开始使用记忆

在你的下一次代理会话中：

# 保存重要决策
memory_remember({
  category: "decision",
  key: "use-postgres",
  content: "Choose Postgres for ACID compliance"
})

# 搜索记忆
memory_recall({ query: "database" })

# 一次调用获取完整上下文
memory_smart_recall({ intent: "what I was working on" })

就这样。你的代理现在拥有了持久化记忆。

代理专属设置

Claude Code

Claude Code 对 toon-memory 有最佳的集成，包括完整的钩子支持。

自动设置（推荐）

npx toon-memory
# 选择：claude

手动设置

添加到 .claude/settings.json：

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

钩子： toon-memory 为 Claude Code 安装 SessionStart、PostToolUse 和 Stop 钩子。这些提供：

• 会话启动时的自动提醒
• 从记忆加载上下文
• 会话协调

Cursor

Cursor 原生支持 MCP 服务器。

自动设置

npx toon-memory
# 选择：cursor

手动设置

添加到 .cursor/mcp.json：

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

OpenCode

OpenCode 使用基于插件的方式实现钩子。

自动设置

npx toon-memory
# 选择：opencode

将创建：

• .opencode/opencode.json — MCP 配置
• .opencode/plugins/toon-memory.ts — 带 SessionStart 钩子的插件

手动设置

添加到 .opencode/opencode.json：

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

注意： OpenCode 1.17+ 会拒绝配置中的 "Unrecognized key: hooks"。请改用插件方式。

Windsurf

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

{
  "servers": {
    "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"]

Codex CLI 也通过 [[hooks]] 配置支持钩子。

Gemini CLI

添加到 .gemini/settings.json：

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

Gemini CLI 通过 hooks.* 配置支持钩子。

Zed

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

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

多代理设置

你可以同时为多个代理配置 toon-memory：

npx toon-memory
# 选择：claude, cursor, opencode

所有代理共享 .toon-memory/memory/data.toon 中的同一记忆文件。

会话协调

并行运行多个代理时：

memory_sessions()
// 🧭 Active sessions (2):
// • claude @ feature/auth (you)
// • opencode @ feature/db
// 🔥 Soft conflicts: src/types.ts

查看其他会话正在操作的文件以避免冲突。

常用命令

保存重要上下文

# 架构决策
memory_remember({
  category: "decision",
  key: "use-microservices",
  content: "Use microservices for payment and auth, monolith for core"
})

# 缺陷修复
memory_remember({
  category: "bug",
  key: "redis-timeout",
  content: "Redis connection timeout — fix was increasing pool to 20"
})

# 代码模式
memory_remember({
  category: "pattern",
  key: "error-handling",
  content: "Always use custom AppError class, never throw raw Error"
})

搜索记忆

# 简单关键词搜索
memory_recall({ query: "database" })

# 图模式（查找相关条目）
memory_recall({ query: "redis", mode: "graph", hops: 2 })

# 紧凑模式（更少 token）
memory_recall({ query: "auth", compact: true })

# 智能召回（推荐）
memory_smart_recall({ intent: "what I was working on" })

管理记忆

# 查看统计
memory_stats()

# 查看自上次会话以来的更改
memory_diff({ since: "24h" })

# 查找相关条目
memory_suggest({ context: "database configuration" })

# 一次调用获取完整上下文
context_generate({})

高效记忆使用技巧

应该保存什么

• 架构决策 — “为什么选择 X 而不是 Y”
• 缺陷修复 — “什么坏了以及如何修复的”
• 代码模式 — “我们在这里怎么做”
• 项目知识 — “团队规范、部署流程”

不应保存什么

• 临时调试笔记
• 密钥或 API 密钥
• 阅读代码就能明显看出的内容
• 重复信息（合并去重会自动处理相同键）

会话习惯

会话开始时：

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

会话结束时：

memory_remember({
  category: "decision",
  key: "today's-approach",
  content: "What I decided and why"
})

故障排除

安装后找不到记忆

1. 运行 npx toon-memory status 验证安装
2. 完全重启你的代理
3. 检查 MCP 配置文件是否存在且 JSON 有效

记忆文件为空

这在首次安装时是正常的。开始使用 memory_remember 保存条目。

重复条目

memory_remember 用相同键现在会自动合并。使用 memory_consolidate 清理现有重复项。

开始使用

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

你的代理将在下一次会话中拥有持久化记忆。