Agent 记忆系统

设计并实现记忆系统，使 Agent 能够在上下文窗口轮转时持续存活，并在跨会话场景中保持行为连续性。

核心问题

LLM Agent 的上下文窗口是有限的。以下情况会导致记忆丢失：

• 会话结束或发生轮转
• 上下文在压力下被裁剪或压缩
• 摘要替代了详细历史（有损压缩）

持久化记忆不是锦上添花的功能——它是 Agent 连续性的底层基础。

架构模式

三种主流的持久化 Agent 记忆架构：

1. CMA — Continuous Memory Architecture（连续记忆架构）

Agent 维护扁平或分层的 Markdown 文件，在启动时选择性读取，在状态变更时写入。适用于：运行时状态、进行中的项目、Agent 身份定义。

• ✅ 简单，无需额外基础设施，支持版本控制
• ✅ 人类可读且可审计
• ✅ 可在任意 OpenClaw 部署中运行
• ❌ 若无嵌入器（embedder），不支持语义搜索
• ❌ 不支持时间推理（无法判断事实在不同时间点的有效性）

这是 OpenClaw Agent 的默认模式。

2. 语义 RAG 记忆

Agent 将事实嵌入向量数据库；检索依赖嵌入相似度。OpenClaw 内置记忆使用 node-llama-cpp，采用 768 维嵌入（兼容 all-MiniLM-L6-v2）。

• ✅ 支持对大规模事实集执行 “我对 X 了解什么？” 类查询
• ✅ 相比纯文本搜索，对改写类查询具有更优的召回能力
• ❌ 不具备时间有效性判断能力——过期事实将污染检索结果
• ❌ 需要嵌入器基础设施支持

3. 时序 KG 记忆（Graphiti/Zep 模式）

Agent 构建知识图谱，每条事实边均标注 valid_at/invalid_at 时间戳。Graphiti（开源，封装 Neo4j）是当前主流实现。

• ✅ 正确支持 “在时间 T 时哪些事实为真？” 类查询
• ✅ 通过标记失效而非删除方式覆盖陈旧事实
• ✅ 支持跨 episode 的实体去重
• ❌ 需依赖 Neo4j + LLM 完成事实注入（高延迟，非实时）
• ❌ 最适合异步批量注入，不宜作为内联（inline）工具调用

建议：所有 Agent 均应采用 CMA + 语义 RAG 组合；仅针对高价值、长周期（数月状态跨度）场景，才引入时序 KG。

详见 references/memory-architecture.md 中的详细对比与部署说明。

记忆文件结构（CMA 模式）

workspace/
├── HEARTBEAT.md          # 当前脉冲状态（务必精简 — < 40 行）
├── memory/
│   ├── CORE_MEMORY.md    # 身份与连续性锚点
│   ├── GOALS.md          # 长周期目标
│   ├── OPEN_LOOPS.md     # 待解决任务与承诺事项
│   ├── WORLD_MODEL.md    # 已验证的环境事实
│   ├── CAPABILITIES.md   # 已验证的工具、通道与能力边界
│   ├── RUNTIME_REALITY.md # 实时通道/变更/配置状态
│   └── research/         # 持久化研究产物
└── operator-outbox.jsonl # 异步 Operator 消息

内容归类指南

时序标注规范

在记忆文件的事实条目中添加 [YYYY-MM-DD] 时间戳，并显式标记已被覆盖的事实：

- [2026-03-27] Telegram: enabled, account "Morrow Operator Bot"
  ~~[2026-03-20] Telegram: disabled~~ SUPERSEDED 2026-03-27

这是一种轻量级的时序 KG 实践，无需完整图数据库后端。参见 references/temporal-discipline.md。

启动流程

每次会话启动时，Agent 应执行以下步骤：

1. 读取 HEARTBEAT.md（由系统注入或显式加载）
2. 检查 Operator 收件箱是否有新指令
3. 对于基础设施/通道类问题：读取 RUNTIME_REALITY.md（而非更早的叙述性文本）
4. 对于待办事项：读取 OPEN_LOOPS.md
5. 对于复杂任务：读取 CORE_MEMORY.md 和 GOALS.md

切勿仅依赖会话 transcript 来维护本应存于记忆中的状态——transcript 会被压缩。

压缩防御策略

OpenClaw 的 lossless-claw 插件（或类似 LCM）会对较早的会话历史进行无损压缩。需主动防范有损压缩风险：

1. 勿等遗忘后再写入。 重要事实须立即外化，不可拖延至会话末尾。
2. 严格控制 HEARTBEAT.md 长度。 过长的 heartbeat 将被优先截断。
3. 使用 lcm_grep 与 lcm_expand_query 在回答有关前期工作的提问前，先检索已被压缩的历史。
4. 区分观察与推论。 记忆文件应记录带来源与日期的事实，而非仅呈现结论。

语义记忆（OpenClaw 内置）

若 OpenClaw 本地语义记忆已启用：

• memory_search(query) —— 对全部记忆文件执行语义搜索
• memory_get(path, from, lines) —— 安全的片段读取接口

在直接读取记忆文件前，请优先调用 memory_search。它更快、范围可控，且上下文利用率更高。

验证语义记忆是否启用：检查你的工具表（tool surface）中是否存在 memory_search。若不存在，则必须显式读取记忆文件。

Graphiti 快速搭建

如需启用时序 KG 记忆（高级用法）：

# 1. 安装
pip install graphiti-core --user --break-system-packages

# 2. Neo4j（持久化部署）
docker run -d --name neo4j 
  --restart=unless-stopped 
  -p 7687:7687 -p 7474:7474 
  -v neo4j-data:/data 
  -e NEO4J_AUTH=neo4j/yourpassword 
  neo4j:5.26

# 3. 配置为使用 OpenClaw /v1 作为 LLM + 嵌入器后端
# 具体配置方法请参考 references/memory-architecture.md 中的 OpenClawLLMClient 补丁说明

重要提示：Graphiti 的 add_episode 方法每个 episode 需调用 5–10 次 LLM。请通过 cron 或批处理作业调用，切勿在 Agent 脉冲过程中内联调用。