夜雨聆风01. 为什么AI需要"记忆"？
用过ChatGPT的人都遇到过这个问题：聊着聊着，它突然"失忆"了，上下文全乱了。
这不是AI的bug，是架构问题。
传统AI对话，每一轮都是"全新开始"。
模型只看到当前这一轮的对话，之前的全部丢失。
这就导致了：
每次都要重复说明自己的需求AI不知道你是谁、你的偏好、你的业务背景多轮复杂任务做到一半就"断片"
OpenClaw的解决方案：基于Pi架构的多层记忆系统。
✦
02. OpenClaw的核心架构：Pi集成
在深入记忆系统之前，需要先理解OpenClaw的Pi集成架构。
OpenClaw使用Pi SDK将AI编程智能体嵌入到Gateway架构中。它不是将Pi作为子进程启动，也不是使用RPC模式，而是通过 createAgentSession() 直接导入并实例化Pi的 AgentSession。
这种内嵌方式提供了：
对会话生命周期和事件的完全控制自定义工具注入（消息、沙箱、渠道专属操作）按渠道/上下文定制系统提示词支持分支/压缩的会话持久化多账户认证配置轮换与提供商无关的模型切换
✦
03. 记忆系统的四层架构
OpenClaw的记忆系统分为四个层次，每一层在不同阶段发挥作用：
01 会话历史
• 当前会话的所有消息• JSONL格式持久化• SessionManager管理
02 系统提示词
• buildAgentSystemPrompt() 构建• 包含工具、Skills、工作空间信息• 渠道/上下文动态生成
03 技能文档
• SKILL.md 文件注入• 会话启动时快照• 按需加载到提示词
04 长期记忆
• memory_search 语义检索• memory_get 获取指定文件• 需要时主动调用
✦
04. 第一层：会话历史 (Session History)
这是最基础的一层，存储当前会话的所有对话。
存储机制
会话是具有树状结构（通过 id/parentId 关联）的 JSONL 文件：
Pi的 SessionManager 负责持久化：
const |
历史限制
limitHistoryTurns() 会根据渠道类型（私信 vs 群组）裁剪对话历史。
自动压缩
当上下文溢出时会触发自动压缩。
常见的溢出特征：
request_too_largecontext length exceededinput exceeds the maximum number of tokensinput token count exceeds the maximum number of input tokens
✦
05. 第二层：系统提示词 (System Prompt)
这是记忆系统的核心，通过 buildAgentSystemPrompt() 构建。
构建流程
constsystemPrompt = buildAgentSystemPrompt({tools,// 工具定义toolStyles,// 工具调用风格guardrails,// 安全护栏cliReference,// OpenClaw CLI参考skills,// Skills快照docs,// 文档workspace,// 工作空间信息sandbox,// 沙箱信息messages,// 消息模板replyTags,// 回复标签voice,// 语音配置silentReply,// 静默回复配置heartbeat,// 心跳配置runtimeMeta,// 运行时元数据memory,// 内存（启用时）responses,// 回应（启用时）contextFiles,// 额外上下文文件extraPrompt,// 额外系统提示词});
完整的提示词组成
应用到会话
applySystemPromptOverrideToSession(session, systemPromptOverride);await session.prompt(effectivePrompt, { images: imageResult.images });
✦
06. 第三层：技能系统 (Skills)
Skills是另一类重要的"记忆"来源。
加载位置
技能从三个地方加载，优先级：
会话快照机制
OpenClaw 在会话启动时快照符合条件的技能，并在同一会话的后续轮次中重用该列表。技能和配置的更改在下一个新会话中生效。
这意味着Skills是在会话开始时一次性加载，而不是每轮都重新扫描。
注入方式
当技能符合条件时，OpenClaw将技能的紧凑XML列表注入系统提示：
total = 195 + Σ (97 + len(name) + len(description) + len(location))粗略估算：97字符 ≈ 24 tokens 每技能
SKILL.md 格式
---name: browser-launcherdescription: 快速打开常用电商后台...metadata:{"openclaw": {"requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"] },"primaryEnv": "GEMINI_API_KEY",},}---
✦
07. 第四层：长期记忆 (Long-term Memory)
这是最"深"的一层，通过主动调用实现。
核心工具
OpenClaw提供两个记忆工具：
// 语义搜索记忆memory_search({query: "用户的产品域名",maxResults: 5});// 获取指定记忆文件memory_get({path: "memory/2026-04-05.md",from: 1,lines: 50});
工具所属组
记忆工具属于 group:memory：
使用场景
AI可以在需要时主动检索相关记忆，而不是被动加载所有内容。这减少了token消耗。
✦
08. 完整Prompt组装流程
了解了四层记忆，最后来看完整的Prompt是如何生成的：
// 1. 加载系统基础提示const basePrompt = getBasePrompt();// 2. 构建完整系统提示词 (来自 buildAgentSystemPrompt)const systemPrompt = buildAgentSystemPrompt({tools: getAvailableTools(),// 所有工具skills: snapshotSkills(),// Skills快照workspace: loadWorkspaceRules(),// AGENTS.md/SOUL.mdsandbox: getSandboxInfo(),// 沙箱配置runtimeMeta: { time, model, ... },// 运行时元数据// ... 其他组件});// 3. 加载会话历史 (最近N轮)const history = sessionManager.getHistory(10);// 4. 运行时按需搜索长期记忆const relevantMemory = awaitmemory_search({query: extractKeywords(userMessage)});// 5. 组装最终Promptconst finalPrompt = [systemPrompt,history,relevantMemory,userMessage].join('\n\n');// 6. 发送给模型await session.prompt(finalPrompt);
记忆的"生命周期"
用户发送消息↓① 会话历史 ← 自动从JSONL加载② 系统提示词 ← buildAgentSystemPrompt()③ Skills ← 会话启动时快照④ 长期记忆 ← memory_search按需调用↓组装完整Prompt↓发送给AI模型
✦
09. 为什么这样设计？
核心优势
- 分层解耦：每层独立，修改不影响其他层
- 按需加载：避免每次都加载全部记忆，减少token消耗
- 语义检索：记忆可搜索，不是简单的全量加载
- 会话隔离：不同workspace的记忆互不污染
- Pi集成：通过createAgentSession()实现深度定制
- 自动压缩：上下文溢出时自动裁剪
可配置项
✦
10. 实际应用场景
场景1：连续对话
你：帮我分析昨天的销售数据AI：读取session.jsonl中的历史消息，分析趋势...你：再对比一下前天的AI：（从历史中读取前一天的数据）...
场景2：跨天连续性
4月5日对话：你：记住这个客户叫张三，电话138xxxxAI：使用memory工具记录到memory/2026-04-05.md4月6日对话：你：那个张三客户后来怎么样了？AI：memory_search({query: "张三"})，找到4月5日记录...
场景3：多Agent记忆隔离
main agent → 读 ~/.openclaw/agents/main/sessions/architect agent → 读 ~/.openclaw/agents/architect/sessions/designer agent → 读 ~/.openclaw/agents/designer/sessions/每个Agent有独立的SessionManager，独立存储，互不干扰。
✦
11. 与传统方案的对比
✦
12. 总结
OpenClaw的记忆系统，本质上是把AI从"金鱼记忆"变成了"有记忆的助手"：
第一层：会话历史 → 记住"刚才聊了什么"
第二层：系统提示词 → 记住"应该怎么做"
第三层：Skills → 记住"用什么工具"
第四层：长期记忆 → 记住"过去发生了什么"
这套系统的核心是 buildAgentSystemPrompt() 函数，它像"导演"一样协调所有层次的记忆组件，最终组装成发送给模型的完整Prompt。
再加上Pi的 createAgentSession() 深度集成，OpenClaw实现了比传统方案更智能、更高效的上下文管理。
💬你对OpenClaw的记忆系统有什么问题吗？评论区聊聊。
