JohnnyFiv3r/Core-Memory
GitHub: JohnnyFiv3r/Core-Memory
Core Memory 是一个面向 AI Agent 的确定性记忆层，通过结构化的因果事件存储和有界的上下文注入，解决传统向量记忆召回不确定和对话历史无限膨胀的问题。
Stars: 2 | Forks: 0
Core Memory 是一个面向 Agent 的确定性记忆层。它存储结构化的记忆事件和显式链接，从而确保在上下文重置后，回忆过程依然可检查且可重复。
- 文档索引：`docs/index.md`
- 规范接口：`docs/canonical_surfaces.md`
## 为什么需要 Core Memory
大多数记忆方法因不同原因而失败：
| 方法 | 问题 |
|---|---|
| 聊天记录回放 | 上下文大小会不受控制地增长 |
| 向量记忆 | 召回具有非确定性 |
| 工具日志 | 缺乏因果推理 |
Core Memory 存储显式的因果记忆事件和关系，因此检索是确定且可调试的。
典型的 bead 类型包括：
- `lesson`（教训）
- `decision`（决策）
- `outcome`（结果）
- `hypothesis`（假设）
- `association`（关联）
## 快速示例
```
from core_memory import MemoryStore
memory = MemoryStore("./memory")
memory.add_bead(type="lesson", title="Redis timeouts under high load", summary=["Worker count exceeded Redis connection pool"])
memory.add_bead(type="outcome", title="Increased Redis connection pool", summary=["Raising max connections resolved timeouts"])
packet = memory.query(limit=5)
print("Relevant Memory")
for bead in packet:
print(f"- [{bead['type']}] {bead['title']}")
```
示例输出：
```
Relevant Memory
- [lesson] Redis timeouts under high load
- [outcome] Increased Redis connection pool
```
## 核心概念
### Bead
一个 bead 是一个结构化的记忆事件。
示例：
```
Type: lesson
Title: Redis pool exhaustion
Summary: Worker count exceeded connection pool limit
```
### Association（关联）
Association 将 bead 与显式的因果关系或关系链接起来。
示例：
```
lesson -> outcome
Redis pool exhaustion -> Increased Redis connection pool
```
### Context Packet（上下文数据包）
Context Packet 是一组有边界的 bead 集合，用于准备注入到 prompt 中。
示例：
```
Relevant Memory
- Redis pool exhaustion caused timeouts previously
- Increasing max connections resolved the issue
```
### Compaction（压缩）
Compaction 在保留持久历史的同时，缩减面向 prompt 的细节。
示例：
```
Before: full incident narrative + logs
After: compact summary + causal links retained
```
Core Memory 在 Agent 会话的生命周期中运行。
### Session Lifecycle（会话生命周期）
Core Memory 并不将记忆视为静态检索系统，而是将其视为随着 Agent 与环境交互而不断演变的存储。
一个会话遵循一个简单的循环：
- 将一个有边界的记忆窗口注入到 prompt 中
- 执行一轮 Agent 交互
- 提取记忆事件
- 将事件追加到记忆日志
- 运行压缩和提升
- 构建下一个记忆窗口
这个循环在会话的每一轮中重复。
#### Session Start（会话开始）
当会话开始时，Core Memory 从记忆存储中构建一个初始 context packet。该数据包被限制在一个固定的 token 预算内（通常约 10k tokens）。
该数据包包含：
- 最近相关的 bead
- 已提升的长期记忆
- 相关事件之间的因果关联
该数据包在第一轮 Agent 交互之前被注入到系统 prompt 中。
#### During a Turn（在一轮交互中）
当 Agent 与用户或工具交互时，Core Memory 从交互中捕获结构化事件。这些事件被记录为 bead，代表有意义的记忆单元，例如：
- 吸取的教训
- 做出的决策
- 行动的结果
- 假设或观察
Sidecar hook 在该轮交互结束时提取这些事件，并将它们追加到记忆日志中。记忆存储是仅追加的，这意味着完整的事件历史会被保留。
#### Compaction（压缩）
在每一轮交互后，Core Memory 运行一个压缩步骤。压缩确保 context packet 保持有界，同时保留重要知识。
边缘或低信号 bead 会逐渐降级为包含以下内容的最小表示：
- bead 类型
- 标题
- 因果关联
这允许系统保留结构知识，同时减少 token 使用量。重要的 bead 保持完整。
#### Promotion（提升）
一些 bead 会成为提升的记忆。提升表示一个记忆事件被认为是未来推理的承重上下文。
被提升的 bead 在压缩期间保留完整细节，并在未来的 context packet 中保持可见。提升决策通常由 Agent 本身根据系统 prompt 指令做出。
例如，Agent 可能会提升：
- 重要的教训
- 稳定的系统行为
- 已解决的事件
- 持续存在的约束
提升允许 Core Memory 区分：
- 短暂的对话上下文
- 持久的知识
#### Bead Query Tool（Bead 查询工具）
除了通过 context packet 进行自动召回外，Agent 还可以直接查询记忆存储。Bead 查询工具允许 Agent 基于以下条件检索特定的记忆事件：
- bead 类型
- 状态（已提升、已归档等）
- 范围（会话、项目、全局）
这允许对先前事件进行显式推理。
例如，Agent 可能会查询：
- 检索关于数据库故障的已提升教训
- 检索与部署事件相关的近期结果
该工具返回结构化的 bead 数据，Agent 可将其用于推理、规划或解释。此机制补充了自动记忆注入，并提供了通往长期记忆的确定性接口。
#### Memory Budget（记忆预算）
Core Memory 为注入的记忆使用有界的 token 预算（通常约 10k tokens）。此约束确保无论系统运行多久，prompt 上下文都保持可预测且稳定。
随着新 bead 被追加到记忆日志：
- 近期事件进入上下文窗口
- 较旧的事件逐渐压缩
- 已提升的记忆保持保留
这创建了一个自然的滚动记忆窗口，其中重要的知识得以持久化，而低信号上下文则随时间淡出。不需要显式的 TTL 或过期逻辑。
#### Why This Matters（这为什么重要）
大多数 Agent 记忆系统依赖于：
- 原始对话回放
- 向量相似度检索
这两种方法都难以推断哪些知识会随时间持久化。
Core Memory 相反将记忆视为结构化的因果历史。系统随着 Agent 与环境交互而演变，在保持有界 prompt 上下文的同时保留重要知识。
## 概念与行为
- **存储是持久且受锁保护的**。
- **从索引状态进行的召回是确定性的**。
- **压缩对于归档是无损的，对于 prompt 渲染是有损的**。
- **因果链接保持可查询，以便审计/调试**。
## 安装
```
python3 -m venv .venv
.venv/bin/python -m pip install -e .
```
配置存储根目录：
```
export CORE_MEMORY_ROOT="$PWD/memory"
```
## 集成
第一波（Wave 1）适配器是对一个稳定端口的轻量封装：
- `core_memory.integrations.api.emit_turn_finalized(...)`
当前集成：
- OpenClaw
- PydanticAI
- SpringAI (HTTP 入口)
隐私模式：
- `store_full_text=true`：存储内联助手文本
- `store_full_text=false`：存储 `assistant_final_ref` + 哈希值
检索模型：
- 滚动窗口注入，用于有界、始终在线的上下文
- 深度召回路径（`retrieve-context`）可在检测到记忆意图时搜索完整历史和有界未压缩的归档 bead
## 路线图
- 关联推断
- 记忆压缩策略
- 基于图的存储后端
- 多 Agent 共享记忆
- 框架集成
Core Memory 处于有意为之的早期阶段，开放进行实验。
另请参阅：
- [Graph 检索架构](docs/graph_memory.md)
## 贡献
参见：
- [CONTRIBUTING.md](CONTRIBUTING.md)
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
- [LICENSE](LICENSE)
## 灵感
“Beads”作为因果记忆小单元的概念部分灵感来自于 Steve Yegge 关于软件架构和记忆系统的文章。该项目在 AI Agent 和确定性 prompt 记忆的背景下探索了该想法的不同应用。
你可以在 https://github.com/steveyegge/beads 找到他的作品。
标签：AI 基础设施, DLL 劫持, LLM, Python, Python脚本, Recall, Unmanaged PE, 上下文窗口, 上下文管理, 事件存储, 人工智能, 仅追加, 关联分析, 可解释性, 向量数据库替代, 因果记忆, 大语言模型, 提示注入, 无后门, 用户模式Hook绕过, 确定性, 结构化数据, 记忆层, 逆向工具, 集群管理