memory-pipeline

核心用法

memory-pipeline 是一套双轨制 AI 代理增强系统，包含 Memory Pipeline（Python） 和 Performance Routine（TypeScript） 两大子系统。

Memory Pipeline 在会话间隙运行三阶段流程：
1. Extract — 使用 LLM 从每日笔记和会话记录中提取结构化事实（决策、偏好、学习、承诺）
2. Link — 构建嵌入向量知识图谱，建立事实间的双向链接，检测矛盾并标记过时信息
3. Briefing — 生成紧凑的 BRIEFING.md，包含个性提醒、活跃项目、近期决策等上下文

Performance Routine 在会话内通过四个生命周期钩子执行：

• before_agent_start：注入预组装简报包（检查清单+记忆+约束）
• before_tool_call：执行工具策略（拒绝列表、参数规范化）
• tool_result_persist：头尾压缩大型工具结果，防止上下文膨胀
• agent_end：撰写行动后审查，为下次运行积累记忆

系统支持 OpenAI、Anthropic、Gemini 三家 API，自动检测工作区，可集成到 HEARTBEAT.md 实现自动化。

显著优点

1. 跨会话连续性：解决 LLM 无状态的核心痛点，代理能"记住"用户偏好和项目历史
2. 执行纪律性：借鉴运动心理学"分离思考与执行"原则，避免中运行时的指令冲突
3. 上下文效率：智能压缩（头60%+尾30%）和 2000 字符简报限制，适配长上下文模型
4. 知识可解释性：生成人类可读的知识摘要和矛盾检测报告，便于人工审计
5. 零侵入集成：通过 OpenClaw 钩子系统工作，无需修改代理核心逻辑

潜在缺点与局限性

1. 外部依赖重：必须配置至少一家 LLM API 密钥，离线环境无法运行
2. 延迟成本：完整管道运行需多次 LLM 调用，可能增加会话启动时间
3. 嵌入质量敏感：无 OpenAI 密钥时退化为关键词匹配，链接准确性下降
4. 版本较新：v0.1.0 尚未经过大规模生产验证，API 可能变动
5. OpenClaw 绑定：Performance Routine 依赖尚未完全发布的 OpenClaw 上下文加载功能

适合的目标群体

• 长期项目型代理用户：需要代理持续数周/数月处理复杂任务的开发者
• 多会话工作流团队：多人共享代理上下文的企业场景
• AI 代理框架开发者：研究记忆架构和工具执行纪律的研究者
• 高可靠性要求场景：金融、医疗等需要决策可追溯性的领域

使用风险

• API 成本累积：每日自动运行可能产生持续的 Token 消耗
• 记忆漂移：长期运行后知识图谱可能积累矛盾，需定期人工审查
• 隐私边界模糊：会话记录自动上传至第三方 LLM API，敏感数据需预处理
• 文件系统膨胀：extracted.jsonl 为追加写入，长期运行需归档策略

核心用法

Memory Pipeline 提供三段式记忆管理：

• Extract：从会话记录和笔记中提取结构化事实（决策、偏好、承诺等），输出为 extracted.jsonl
• Link：构建知识图谱，生成嵌入向量，建立事实间双向链接，检测矛盾
• Briefing：生成每日 BRIEFING.md，整合人格设定、活跃项目和关键上下文

Performance Routine 提供四个生命周期钩子：

• before_agent_start：预注入简报包，分离思考与执行
• before_tool_call：工具调用策略管控，支持拒绝列表
• tool_result_persist：头尾压缩大型工具结果，防止上下文膨胀
• agent_end：写入行动后回顾，为下次运行积累记忆

显著优点

1. 架构清晰：Python脚本负责离线记忆处理，TypeScript钩子负责在线执行管控，职责分离明确
2. 设计原则先进：借鉴运动心理学"预演-执行-回顾"模式，禁止执行中干预，避免指令冲突
3. 多模型兼容：支持 OpenAI/Anthropic/Gemini 三家 API，自动降级容错
4. 安全可控：文件操作严格限制在用户工作区，无危险代码模式，获安全认证 A 级
5. 可扩展：提供完整的配置接口和自定义模型选项

潜在局限

• 云端依赖：核心功能依赖外部 LLM API，用户数据需离境传输，隐私敏感场景受限
• 数据持久化未明确：extracted.jsonl 等文件无限追加，缺乏自动清理机制
• 开发中特性：BRIEFING.md 的自动加载依赖 "OpenClaw context loading" 开发中功能
• 错误恢复薄弱：API 调用失败仅打印错误，无重试机制
• 无本地模型支持：当前不支持 Ollama/vLLM 等本地部署方案

适合人群

• 需要 AI 代理跨会话保持一致性的长期项目用户
• 追求执行质量可控性的专业场景（研究、写作、编程辅助）
• 使用 OpenClaw 或兼容生命周期钩子架构的 Agent 框架开发者
• 愿意接受云端 LLM 数据处理政策的个人或团队用户

常规风险

| 风险类别 | 说明 | 缓解措施 |

|---------|------|---------|

| 数据出境 | 会话内容传输至 OpenAI/Anthropic/Google | 审阅各服务商数据处理政策，考虑敏感信息脱敏 |

| 记忆文件膨胀 | JSONL/图谱文件随时间增长 | 定期手动清理或设置 cron 任务归档旧数据 |

| API 可用性 | 功能依赖外部服务商稳定性 | 配置多 API key 备用，关键场景保留本地副本 |

| 隐私合规缺口 | 缺乏明确的数据保留策略和用户同意机制 | 自建数据治理文档，明确记忆文件生命周期 |