内容
# 因果记忆
> **适用于 AI 智能体的因果记忆层。** 记录决策及其结果为因果关系，使智能体能够跨会话学习经验，并在压缩后仍然存活。
>
> 目前的记忆框架（Mem0、Zep、Letta、OpenViking、MemOS）存储 *发生了什么*。`因果记忆` 存储 *为什么* —— 决策和结果之间的因果联系。这是其他所有记忆层都忽略的部分。
[](LICENSE)
[](#status)
## 为什么
每个智能体都面临同样的问题：经过 N 次压缩后，它会忘记 *为什么* 做出了过去的决策。它会恢复到一个状态，相同的错误会以相同的方式修复，相同的架构选择会重新被讨论，相同的经验教训会重新学习。
这是因为 **因果信息在文本压缩下是最脆弱的**。真实的LLM基准测试（使用grok-build的生产压缩提示）：
| 压缩次数（k） | 文本回忆率 | 因果表回忆率 |
|---|---|---|
| 1 | 100% | 100% |
| 2 | 85% | 100% |
| 3 | 55% | 100% |
| 5 | **45%** | **100%** |
因果表不会衰减，因为它存在于智能体的上下文窗口之外 —— 压缩无法触及它。参见 [`docs/design.md`](docs/design.md) 和 [完整的基准测试报告](https://github.com/JingxuanC/agent-teardown/blob/main/spike/grok-causal-memory/bench-RESULTS.md)。
## 功能
四个MCP工具。小表面积是重点。
| 工具 | 调用时机 | 功能 |
|---|---|---|
| `record_decision` | 完成操作后 | 记录 `决策 → 结果` 为因果边，附带任务标签和置信度 |
| `search_causal` | 进行非琐碎决策前 | 检索过去的因果事件，按任务或文本排序，置信度优先 |
| `trace_cause` | 出现故障时（简单） | 单跳逆向查找：哪个决策导致了这个结果 |
| `trace_cause_chain` | 出现故障时（复杂） | 通过因果图进行多跳逆向遍历 |
**多跳示例**："服务崩溃" ← "内存溢出" ← "缓存没有 TTL" ← "Redis 配置无过期时间"。`trace_cause` 查找第一跳。`trace_cause_chain` 遍历整个链。
## 快速开始
```bash
git clone https://github.com/JingxuanC/causal-memory.git
cd causal-memory
cargo build --release
```
将以下配置接入任何与MCP兼容的智能体（Claude Code、Cursor、grok-build等）：
```json
{
"mcpServers": {
"causal-memory": {
"command": "/path/to/causal-memory/target/release/causal-memory",
"env": {
"CAUSAL_MEMORY_DB": "~/.local/share/causal-memory/causal.db"
}
}
}
}
```
然后将 [`CLAUDE.md`](CLAUDE.md) 复制到您的项目系统中，以激活主动因果记忆使用。根据 [研究笔记](https://github.com/JingxuanC/agent-teardown/blob/main/insights/13-reconstructive-memory.md#L143)：智能体不会在没有明确提示指令的情况下主动调用记忆工具。
## 与其他记忆类型的比较
| 记忆类型 | 存储内容 | 示例 | 实现者 |
|---|---|---|---|
| 平面事实 | 用户偏好 | "用户偏好 TypeScript" | Mem0 |
| 时间事实 | 状态变化随时间 | "用户在三月使用 Pro 计划" | Zep |
| 自我管理 | 智能体编辑自己的记忆 | 智能体决定记住什么 | Letta |
| 文件系统 | 记忆作为虚拟文件系统 | 目录检索 | OpenViking |
| **因果** | **决策 → 结果链接** | **"互斥锁导致死锁"** | **因果记忆（本项目）** |
**因果记忆是互补的，而不是竞争的。** 一个完整的 7×24 智能体可能需要 Mem0（偏好）+ Zep（状态）+ 因果记忆（经验）。本层填补了其他记忆层无法覆盖的因果部分。
## 数据路径
- 默认：`~/.local/share/causal-memory/causal.db`
- 覆盖：`CAUSAL_MEMORY_DB` 环境变量
SQLite 文件。便携。无服务端进程。您的数据保留在本地机器上。
## 架构
```
智能体 ←（MCP stdio）→ 因果记忆 → SQLite（因果边表）
```
`因果边` 表永远不会被压缩 —— 它在智能体的上下文窗口之外。重点在于：文本压缩无法破坏它无法访问的内容。
## 状态
**v0.2.0 — alpha.** 已实现：
- ✅ 四个 MCP 工具（记录 / 搜索 / 单跳追踪 / **多跳链追踪**）
- ✅ SQLite 持久化，带 CHECK 约束
- ✅ **参数化查询**（无 SQL 注入风险）
- ✅ 置信度级别（时间 / 规则 / 推理 / 用户反馈）
- ✅ 任务感知检索
- ✅ **多跳逆向遍历**，通过递归 CTE
- ✅ 基于规则的 **决策自动提取器**，适用于 grok-build 会话日志
待完成：
- ❌ 语义 / 向量搜索（目前仅支持 LIKE）
- ❌ Python/TS 绑定（仅 Rust 二进制）
- ❌ LongMemEval 基准测试集成
- ❌ 跨智能体共享协议
- ❌ 离线整合 ("睡眠") 周期
- ❌ 尚未与生产智能体端到端集成
路线图：参见 [docs/roadmap.md](docs/roadmap.md)。
## 构建与测试
```bash
cargo build --release # 构建二进制文件
cargo test # 运行单元测试
```
## 研究背景
本项目是 13 个研究笔记的工程输出，关于智能体内存架构：
- [智能体的第二定律 — 抗退化（信息论）](https://github.com/JingxuanC/agent-teardown/blob/main/insights/04-anti-entropy.md)
- [LLM 是无状态函数](https://github.com/JingxuanC/agent-teardown/blob/main/insights/09-stateless-function.md)
- [内存公司格局（Letta/Mem0/Zep/OpenViking/MemOS）](https://github.com/JingxuanC/agent-teardown/blob/main/insights/10-memory-frameworks.md)
- [因果状态存储 — 本项目实现的设计](https://github.com/JingxuanC/agent-teardown/blob/main/insights/11-causal-state-store.md)
- [真实 LLM 压缩基准测试](https://github.com/JingxuanC/agent-teardown/blob/main/papers/02-compaction-degradation.md)
影响特定设计决策的论文： [`docs/research-backdrop.md`](docs/research-backdrop.md)
## 许可证
Apache-2.0。参见 [LICENSE](LICENSE)。
