乐于分享
好东西不私藏

一文看透!OpenClaw 记忆系统:这是目前最优雅的 Prompt 组装逻辑

一文看透!OpenClaw 记忆系统:这是目前最优雅的 Prompt 组装逻辑
 Greate Agent Session

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 文件:

      ~/.openclaw/agents/<agentId>/sessions/
      ├── session-1.jsonl # 会话1的所有消息
      ├── session-2.jsonl # 会话2的所有消息
      └── ...

      Pi的 SessionManager 负责持久化:

      const
       sessionManager = SessionManager.open(params.sessionFile);

      历史限制

      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() 构建。

        构建流程

        const systemPrompt = buildAgentSystemPrompt({tools, // 工具定义toolStyles, // 工具调用风格guardrails, // 安全护栏cliReference, // OpenClaw CLI参考skills, // Skills快照docs, // 文档workspace, // 工作空间信息sandbox, // 沙箱信息messages, // 消息模板replyTags, // 回复标签voice, // 语音配置silentReply, // 静默回复配置heartbeat, // 心跳配置runtimeMeta, // 运行时元数据memory, // 内存(启用时)responses, // 回应(启用时)contextFiles, // 额外上下文文件extraPrompt, // 额外系统提示词});

        完整的提示词组成

        组成部分
        说明
        工具定义
        所有可用工具的schema
        工具调用风格
        如何调用工具的规范
        安全护栏
        安全策略和限制
        Skills
        按需加载的技能文档
        工作空间信息
        workspace配置
        沙箱信息
        沙箱环境详情
        运行时元数据
        当前时间、模型等
        内存/回应
        可选的长期记忆

        应用到会话

        applySystemPromptOverrideToSession(session, systemPromptOverride);await session.prompt(effectivePrompt, { images: imageResult.images });

        06. 第三层:技能系统 (Skills)

        Skills是另一类重要的"记忆"来源。

        加载位置

        技能从三个地方加载,优先级:

        位置
        优先级
        范围
        <workspace>/skills/
        最高
        仅该Agent
        ~/.openclaw/skills/
        所有Agent
        Bundled 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"用户的产品域名",maxResults5});// 获取指定记忆文件memory_get({path"memory/2026-04-05.md",from1,lines50});

        工具所属组

        记忆工具属于 group:memory

        工具
        功能
        memory_search
        语义搜索长期记忆
        memory_get
        获取指定记忆文件

        使用场景

        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. 为什么这样设计?

        核心优势

        1. 分层解耦:每层独立,修改不影响其他层
        2. 按需加载:避免每次都加载全部记忆,减少token消耗
        3. 语义检索:记忆可搜索,不是简单的全量加载
        4. 会话隔离:不同workspace的记忆互不污染
        5. Pi集成:通过createAgentSession()实现深度定制
        6. 自动压缩:上下文溢出时自动裁剪

        可配置项

        配置项
        说明
        agents.defaults.contextWindow
        会话历史保留轮数
        skills.load.watch
        是否监视Skills文件变化
        skills.load.extraDirs
        额外加载目录
        agents.defaults.sandbox.mode
        沙箱模式 (off/non-main/all)
        agents.defaults.compaction.mode
        压缩模式 (safeguard/hot/restart/off)

        10. 实际应用场景

        场景1:连续对话

        你:帮我分析昨天的销售数据AI:读取session.jsonl中的历史消息,分析趋势...你:再对比一下前天的AI:(从历史中读取前一天的数据)...

        场景2:跨天连续性

        45日对话:你:记住这个客户叫张三,电话138xxxxAI:使用memory工具记录到memory/2026-04-05.md46日对话:你:那个张三客户后来怎么样了?AI:memory_search({query: "张三"}),找到45日记录...

        场景3:多Agent记忆隔离

        main agent  读 ~/.openclaw/agents/main/sessions/architect agent  读 ~/.openclaw/agents/architect/sessions/designer agent  读 ~/.openclaw/agents/designer/sessions/每个Agent有独立的SessionManager,独立存储,互不干扰

        11. 与传统方案的对比

        特性
        传统方案
        OpenClaw方案
        历史管理
        手动维护
        SessionManager自动
        上下文加载
        全量加载
        按需裁剪
        记忆检索
        被动注入
        memory_search主动
        Skills加载
        每轮扫描
        会话快照
        提示词构建
        静态模板
        buildAgentSystemPrompt动态
        会话隔离
        按workspace隔离

        12. 总结

        OpenClaw的记忆系统,本质上是把AI从"金鱼记忆"变成了"有记忆的助手":

        第一层:会话历史 → 记住"刚才聊了什么"

        第二层:系统提示词 → 记住"应该怎么做"

        第三层:Skills → 记住"用什么工具"

        第四层:长期记忆 → 记住"过去发生了什么"

        这套系统的核心是 buildAgentSystemPrompt() 函数,它像"导演"一样协调所有层次的记忆组件,最终组装成发送给模型的完整Prompt。

        再加上Pi的 createAgentSession() 深度集成,OpenClaw实现了比传统方案更智能、更高效的上下文管理。


        💬你对OpenClaw的记忆系统有什么问题吗?评论区聊聊。