内容
# 失败记忆
> 为 AI 代理提供失败记忆。记住哪些地方出错了，以免重复犯错。
失败记忆会挖掘 AI 代理的会话记录，找出失败的案例，存储在本地 SQLite 数据库中，并在每个新会话开始时提供简报。您的代理在开始工作时已经知道之前哪些地方出了问题。
两个界面：
- **钩子**（推荐）：会话开始时的简报 + 会话结束时的记录挖掘。被动、自动，无需代理采取任何行动。
- **MCP 服务器**（可选）：主动工具（`scar_log`、`scar_recall`、`scar_context`）供希望在会话中查询失败历史的代理使用。
实际上，大部分价值来自于简报。MCP 层为高级用户提供，他们希望代理在进行高风险操作之前主动查询过去的失败案例。
## 安装（精简版，推荐）
```bash
npm install -g @bambushu/scar
scar init --claude-code
```
这将设置：
- SQLite 数据库在 `~/.cognitive/cognitive.db`
- 会话开始钩子在 `~/.claude/settings.json` 中，运行简报
- 会话结束钩子，挖掘刚刚结束的会话记录中的失败案例
您将在每个新 Claude Code 会话的顶部看到简报，列出之前工作中未解决的失败模式。
## 安装（完整版，带 MCP）
如果您还想要主动查询工具：
```bash
npm install -g @bambushu/scar
scar init --claude-code --with-mcp
```
这还额外注册了 MCP 服务器，以便 Claude Code 暴露 `scar_log`、`scar_recall`、`scar_context` 等可调用工具。如果您希望代理在部署、数据库更改或其他高风险操作之前查询失败记忆，则此功能非常有用。
## 命令行界面
```bash
# 手动记录失败案例
scar log -r 我的项目 -l TypeScript -t Bash \
-e "TypeError: Cannot read properties of undefined" \
--tried "运行测试套件" \
--wrong "解析器中的空访问"
# 查询过去的失败案例
scar recall -r 我的项目 -l TypeScript
# 查看模式
scar stats
scar stats --stale
# 删除噪声
scar forget <失败记忆ID>
# 导出调试
scar export
```
## MCP 工具（可选安装）
| 工具 | 用途 |
|------|---------|
| `scar_log` | 记录带有上下文的失败案例 |
| `scar_update` | 更新失败记忆 - 记录成功的操作，改变解决方案 |
| `scar_recall` | 查找相关的过去失败案例 |
| `scar_forget` | 删除失败记忆 |
| `scar_stats` | 聚合失败模式 |
| `scar_context` | 相关的失败记忆的轻量级计数（廉价的预检查） |
## 工作原理
1. 当 Claude Code 会话结束时，会话结束钩子触发，挖掘会话记录 JSONL 中的 Bash/Edit/Write/Read 失败案例，写入 SQLite 数据库
2. 下一个会话开始时，会话开始钩子触发，读取最近未解决的模式，将简报打印到代理的上下文中
3. 在 5 分钟窗口内自动去重相同的错误
4. （可选，MCP）代理在进行高风险操作之前调用 `scar_context` 或在调查一类错误时调用 `scar_recall`
## 存储
SQLite 数据库在 `~/.cognitive/cognitive.db`。是共享的认知工具包基础的一部分 - 未来的工具（自我信任校准，直觉/专注）共享同一个数据库。
## 许可证
MIT
