memory-management

记忆管理

持久化记忆系统，确保 Claude 不会重复犯错，并始终在对话中应用已学习的模式。

4 个工具

• mcp__claude-recall__load_rules - 开始工作前加载所有有效规则。无需查询。
• mcp__claude-recall__store_memory - 存储一条规则或学习成果。会立即在当前对话中生效。
• mcp__claude-recall__search_memory - 按关键词搜索记忆。做决定前，用它查找特定记忆。
• mcp__claude-recall__delete_memory - 按 ID 删除特定记忆。先用 search_memory 查找 ID。

使用时机

加载（回忆）

• 每次会话的首要操作 — 在调用任何工具（包括 Read/Glob/Grep）之前，先调用 load_rules。规则必须指导探索过程，而不只是编辑。
• 上下文压缩后 — 如果上下文经过压缩或对话时间较长，请再次调用 load_rules。较早的规则可能已经丢失。
• 切换任务领域时 — 从一个领域切换到另一个领域时（例如从测试切换到数据库，再切换到 CI），请使用新领域作为查询内容调用 search_memory。
• 修改文件前 — 使用文件路径或模块名称调用 search_memory，检查是否有针对该文件的约定。

存储（记录）

• 用户纠正你的工作时 - 使用 metadata.type: "correction" 调用 store_memory
• 用户提及偏好时 - 使用 metadata.type: "preference" 调用 store_memory
• 克服挑战后 - 使用 metadata.type: "failure" 调用 store_memory
• DevOps/工作流规则 - 使用 metadata.type: "devops" 调用 store_memory

关键指令

1. 始终先加载规则再采取行动 — 在会话中，第一步就调用 load_rules，甚至要早于读取文件。规则不仅指导编辑，也指导探索方式。
2. 应用已加载的规则 — 加载后，在继续操作前说明哪些规则适用于当前任务。如果某条规则与你的计划冲突，请遵循该规则。如果没有适用规则，请说明。只加载而不应用，等同于没有加载。
3. 在正文中引用所应用的规则 — 当某条规则影响你的工作时，请注明：（应用自记忆：）。将引用放在受其影响的操作旁边，而不是无关内容的末尾。
4. 用户说“recall”/“remember”/“store this” → 使用 Claude Recall — 用户说出这些关键词时，始终使用 mcp__claude-recall__store_memory。对于此类请求，切勿写入原生记忆目录（~/.claude/projects/*/memory/）。Claude Recall 是用户偏好的记忆系统。
5. 存储前先询问 — 调用 store_memory 前，告知用户你计划存储的内容并征求确认
6. 立即记录纠正内容 — 用户的修正优先级最高（仍需先询问）
7. 切勿存储机密信息 — 不得存储 API 密钥、密码、令牌或个人身份信息

快速参考

加载规则（每项任务开始前）

mcp__claude-recall__load_rules({})

一次调用即可返回所有有效偏好、纠正内容、失败记录和 DevOps 规则。确定且完整。

存储记忆（发生重要事项时）

mcp__claude-recall__store_memory({
  "content": "Description of what to remember",
  "metadata": { "type": "preference|correction|devops|failure" }
})

返回存储的规则，其中包含 activeRule 字段和 _directive，用于立即应用该规则。无需再次调用 load_rules。

同一会话内的规则

调用 store_memory 时，响应会包含：

• activeRule：格式化为规则的存储内容
• _directive：用于立即应用该规则的指令

这意味着，在对话中途存储的规则无需重新加载即可立即生效。

存储内容

自动记录（无需手动存储）

当用户说出以下内容时，系统会自动记录：

• “我偏好 X”/“始终使用 X”/“绝不要做 X” -> 偏好
• “我们用 X 做 Y”/“测试放在 X” -> 项目约定
• “这是一个 [类型] 项目” -> 项目背景

需要手动存储

请明确存储以下内容：

纠正内容（优先级最高）：

User: "No, put tests in __tests__/ not tests/"
-> Store: "CORRECTION: Test files go in __tests__/ directory, not tests/"
   metadata: { "type": "correction" }

复杂工作流：

-> Store: "Deploy process: 1) npm test 2) docker build 3) push to ECR 4) kubectl apply"
   metadata: { "type": "devops" }

学习周期（失败 -> 修复 -> 成功）：

-> Store: "REST API failed due to CORS. Solution: Use GraphQL endpoint instead."
   metadata: { "type": "failure" }

记忆优先级

1. 纠正 - 用户明确指出并修正了错误（最高优先级）
2. DevOps - Git、测试、部署、架构模式
3. 偏好 - 代码风格、工具选择、约定
4. 失败 - 学习循环和过往错误

不应存储的内容

绝不存储：

• API 密钥、令牌、密码、机密
• 个人电子邮件、电话号码、地址
• 含凭据的数据库连接字符串
• 任何敏感配置值

可安全存储的内容：

• “我们使用 JWT 进行身份验证”（模式，而非凭据）
• “API 基础 URL 是 https://api.example.com”（非敏感）
• “生产环境使用 PostgreSQL，测试使用 SQLite”（工具选择）

技能凝练

随着记忆不断积累，Claude Recall 会自动在 .claude/skills/auto-*/ 中生成技能文件。 这些文件会在未来的会话中原生加载，无需调用工具。

工作原理： 每次 store_memory 后，系统都会检查某个主题的记忆是否足以形成技能（大多数类型至少需要 3 条，偏好类至少需要 5 条）。如果满足条件，系统就会写入一个 Claude Code 自动加载的 SKILL.md 文件。

CLI 命令：

• claude-recall skills list — 查看生成的技能
• claude-recall skills generate --force — 强制重新生成
• claude-recall skills clean --force — 移除所有自动生成的技能

自动捕获钩子

Claude Recall 会在 Claude Code 的六个事件上注册钩子，用于自动捕获、即时注入规则和跟踪结果——无需调用 MCP 工具：

钩子	事件	功能
correction-detector	UserPromptSubmit	从自然语言中捕获用户的纠正、偏好和项目知识
memory-stop	Stop	从最近 6 条转录记录中捕获纠正、偏好、失败和 DevOps 模式
precompact-preserve	PreCompact	在上下文压缩前，对最多 50 条转录记录进行更全面的扫描
session-end-checkpoint	SessionEnd	当会话以自愿方式结束时（clear、prompt_input_exit、logout），自动保存 {completed, remaining, blockers} 任务检查点。它会启动一个分离的工作进程，使其在 Claude Code 的 1.5s SessionEnd 超时限制内完成。Pi 通过 session_shutdown 事件处理程序实现了等效功能。
rule-injector	PreToolUse	即时注入规则。 每次调用工具前，搜索匹配 tool_name + tool_input 的有效规则，并将排名前 3 的规则（不包括原始失败记录）作为 <system-reminder> 块注入到操作旁。弥补规则加载的时机差距：在做出决策的当下呈现规则，而不是在注意力转移后、上游 50,000 个 token 处呈现。每次注入都会记录到 rule_injection_events，以便关联结果。Pi 通过 before_agent_start 处理程序中的逐轮注入实现了等效功能。
rule-injection-resolver	PostToolUse / PostToolUseFailure	根据工具结果（成功/失败）解析已记录的 rule_injection_events。与注入器配合后，这会成为新的“这条规则是否真正有帮助”信号，取代失效的 (applied from memory: ...) 引用正则表达式。

关键行为：

• 优先使用大模型进行分类，通过 Claude Haiku 检测“这里使用制表符”或“测试放在 __tests__/”等正则表达式可能漏掉的自然语言表述
• 自动且无需配置：从 Claude Code 会话环境中获取 ANTHROPIC_API_KEY
• API 密钥不可用或 API 调用失败时，静默回退到正则表达式
• 批量分类：Stop 和 PreCompact 钩子在一次 API 调用中发送所有文本
• 通过 Jaccard 相似度（阈值为 55%）检测近似重复项，避免重复存储
• 每个事件设有限额：3（Stop）、5（PreCompact），以防数据库被大量写入
• 自动检查点质量门控：当大模型检测到任务已完成时，拒绝保存；手动检查点会保持不变
• 始终以 0 退出——钩子绝不会阻止 Claude

**设置：**运行 claude-recall setup --install，在 .claude/settings.json 中注册钩子。升级后，如果发行说明提到新增或更改的钩子（即 hooksVersion 更新），请在每个正在使用的项目中重新运行该命令——它具有幂等性，因此钩子已是最新版本时不会执行任何操作，也不会修改任何内容。

工作流示例

开始新任务

1. User: "Add user authentication"

2. Load rules first:
   mcp__claude-recall__load_rules({})

3. Response includes:
   ## Preferences
   - auth_method: JWT with httpOnly cookies
   ## Corrections
   - Never use localStorage for auth tokens

4. Implement using JWT + httpOnly cookies (not sessions, not localStorage)

5. User approves -> Done (no need to store, just applied existing knowledge)

用户纠正你的工作

1. You: Created auth with localStorage tokens

2. User: "No, we always use httpOnly cookies for security"

3. Fix the code

4. Ask: "I'd like to remember: always use httpOnly cookies for auth tokens, never localStorage. Store this?"

5. User: "Yes"

6. Store the correction:
   mcp__claude-recall__store_memory({
     "content": "CORRECTION: Always use httpOnly cookies for auth tokens, never localStorage",
     "metadata": { "type": "correction" }
   })

7. Response includes activeRule - apply it immediately

克服挑战

1. Tried: Redis sessions for auth
   Failed: "Session sync issues in k8s cluster"

2. User suggested: "Try stateless JWT"

3. Implemented JWT -> Works!

4. Ask: "I'd like to remember: Redis sessions fail in k8s due to sync issues; use stateless JWT instead. Store this?"

5. User: "Yes"

6. Store the learning:
   mcp__claude-recall__store_memory({
     "content": "Auth in k8s: Redis sessions failed (sync issues). JWT stateless tokens work correctly.",
     "metadata": { "type": "failure", "learning_cycle": true }
   })

故障排除

加载规则时没有返回内容：

• 这可能是一个尚无历史记录的新项目
• 随着了解项目，使用 store_memory 存储规则

自动捕获漏掉了某些内容：

• 使用相应类型手动存储
• 后续调用 load_rules 时就能找到它

---

学习循环：加载规则 -> 应用 -> 执行 -> 捕获结果 -> 下次做得更好