OpenClaw记忆重构：从单体MEMORY.md到微服务化存储架构

1. 项目概述：为什么我们需要重构记忆结构

如果你和我一样，长期使用像OpenClaw这类基于大语言模型的智能体进行项目开发或知识管理，那你一定对那个不断膨胀的MEMORY.md文件又爱又恨。它就像一个忠实的伙伴，记录着每一次对话、每一个决策和每一段代码片段。但随着项目推进，这个文件会变得无比臃肿，动辄上万行，每次启动智能体时，光是加载这个文件就要消耗掉海量的上下文令牌（Token）。更糟糕的是，当你使用Memory_Search这类工具去检索一个具体的函数实现时，系统不得不扫描整个庞大的文件，效率低下，成本高昂。

这正是openclaw-memory-compact这个技能诞生的背景。它不是一个花哨的新功能，而是一个解决实际痛点的“外科手术刀”。它的核心目标非常明确：通过重构记忆的存储结构，将单一的、冗长的MEMORY.md文件，拆解为一个目录索引加多个细节文件的格式，从而显著降低令牌消耗，并提升长期上下文的工作效率。

简单来说，它把一本厚重的“百科全书”拆成了“目录”和按章节分册的“分卷”。当你需要查找“如何配置数据库连接”时，你不再需要搬出整本百科全书，而只需翻开目录，找到对应的“数据库”分册即可。这种设计完美契合了OpenClaw底层基于EmbeddingModel（嵌入模型）的检索工具（如Memory_Search,Memory_Get）的工作方式。这些工具本身就是为了“按需取用”而生的，它们擅长从海量信息中精准定位相关片段。openclaw-memory-compact所做的，就是为这些工具准备一份更友好、更高效的“食材”。

2. 核心设计思路与架构解析

2.1 从“单体仓库”到“微服务化”存储

传统的MEMORY.md文件是一个典型的“单体应用”。所有信息，无论是核心的项目架构决策，还是某次调试的临时日志，都堆积在同一个文件里。这种模式在初期简单直接，但随着信息量增长，其弊端暴露无遗：

1. 加载成本高：每次会话初始化，整个文件内容都必须作为上下文输入，占用大量令牌。
2. 检索效率低：检索工具需要遍历整个文本海洋，即使有向量索引，处理大文件本身也是一种开销。
3. 维护困难：信息混杂，难以进行主题化的归类和整理。

openclaw-memory-compact提出的解决方案，可以类比为将“单体应用”重构为“微服务架构”。

• MEMORY.md (索引服务)：这个文件不再承载具体内容，而是蜕变为一个纯粹的索引目录。它只记录记忆条目的标题和其对应的详细文件路径。它的体积变得非常小，可能只有几十行，确保了极低的初始加载成本。
• memory/details/ (微服务集群)：这里是具体记忆内容的“家”。每个文件代表一个独立的主题或领域，例如角色定位.md、API设计规范.md、数据库连接池配置.md。这些文件是“自治”的，包含了该主题下所有详细、结构化的信息。
• memory/_import/Start_Memory.md (启动引导服务)：这是一个特殊的文件，包含了每次新会话开始时必须加载的核心记忆。通常，这里会放置智能体的基础角色设定、当前最重要的项目目标、以及本次会话需要优先关注的上下文。它确保了智能体能够快速进入工作状态。
• memory/YYYY-MM-DD.md (原始日志流)：这里存放未经加工的每日原始记录，类似于开发日志。它们可能杂乱，但保留了最原始的过程信息，供后续提炼和归档到details/目录。
• .learnings/ (知识加工车间)：这是一个暂存区，用于存放从原始日志或对话中提取的“学习心得”、“错误复盘”和“功能请求”。这里的文件是待处理的“原材料”，经过验证和整理后，有价值的部分会被“晋升”到memory/details/成为正式知识。

2.2 与Embedding检索工具的协同原理

这个架构设计的精妙之处在于，它与OpenClaw的检索工具形成了完美闭环。

1. 检索阶段 (Memory_Search)：当用户提出一个问题，例如“我们项目的用户认证流程是怎样的？”，Memory_Search工具会首先在向量数据库中搜索最相关的记忆片段。由于我们的记忆已经被主题化存储在details/下，向量索引可以更精确地建立在这些独立的、高内聚的文件上。检索结果返回的很可能就是memory/details/用户认证系统.md这个文件的路径或其中的特定段落。
2. 获取阶段 (Memory_Get)：接着，Memory_Get工具会根据Memory_Search返回的路径，去精准读取memory/details/用户认证系统.md这个文件。它不需要去读取整个庞大的、旧的MEMORY.md，也不需要读取不相关的其他细节文件（如数据库配置.md）。这就实现了“按需取用”，极大地减少了每次交互中需要注入上下文的令牌数量。
3. 成本与效率收益：假设旧的MEMORY.md有10万字，而用户认证系统.md只有2000字。在旧模式下，即使只需要认证信息，系统也可能被迫携带整个10万字的上下文（取决于设置）。在新模式下，系统可能只需要携带MEMORY.md索引（500字） +Start_Memory.md（1000字） + 精准检索到的用户认证系统.md（2000字），总计约3500字。令牌消耗可能降低一个数量级，响应速度也会因为处理更小的文本块而提升。

注意：这种优化效果的前提是，你的智能体工作流确实依赖于Memory_Search和Memory_Get这类工具进行上下文管理。如果你总是让智能体读取全部记忆，那么这个技能的价值将大打折扣。

3. 技能部署与初始化实操

3.1 环境准备与技能获取

首先，你需要一个正在运行中的OpenClaw环境。openclaw-memory-compact是一个技能（SKILL），因此它需要被放置在OpenClaw的技能目录下。

通常，OpenClaw的技能目录位于~/.openclaw/skills/（Linux/macOS）或C:\Users\<你的用户名>\.openclaw\skills\（Windows）。如果你不确定，可以查看OpenClaw的配置文件或文档。

获取技能有两种常见方式：

1. 从Git仓库克隆：如果该技能已开源在GitHub等平台，你可以直接克隆到技能目录。

   cd ~/.openclaw/skills/ git clone <技能的git仓库地址> memory-compact

2. 手动放置：如果技能以压缩包形式提供，解压后，将包含SKILL.md的文件夹（例如memory-compact）整个复制到上述技能目录下。

完成后，你的目录结构应该类似于：

~/.openclaw/skills/ ├── other-skill-1/ ├── other-skill-2/ └── memory-compact/ # 这就是我们新添加的技能 ├── SKILL.md # 技能的核心说明文档 ├── __init__.py # 可能存在的Python入口文件 ├── docs/ # 可能存在的额外文档 └── ... # 其他资源文件

3.2 首次运行与记忆迁移

这是最关键的一步：将你现有的、庞杂的MEMORY.md文件进行拆分和重构。

重要警告：在操作前，请务必备份你原始的MEMORY.md文件！重构过程涉及文件读写，虽然技能设计时应考虑安全性，但备份是防止意外的最佳实践。

根据SKILL.md的指引，运行该技能。通常，技能会提供一个命令或一个可执行的函数。例如，在OpenClaw的对话中，你可能需要输入类似!run_skill memory-compact或调用特定的函数。

技能执行时，预期会完成以下工作：

1. 解析现有MEMORY.md：技能会读取你当前的MEMORY.md文件，分析其内容结构。一个设计良好的技能应该能识别出不同层级的标题（如#,##）作为潜在的主题分割点。
2. 创建目录结构：在memory/目录下（通常与MEMORY.md同级），创建details/和_import/等子目录。
3. 内容拆分：
   • 将MEMORY.md中识别出的各个主题模块（例如，以## 项目背景、## API设计开头的部分）提取出来，分别保存为memory/details/项目背景.md、memory/details/API设计.md等文件。
   • 原MEMORY.md文件的内容将被重写。新的MEMORY.md将只包含一个索引列表，每一项大概是这样的格式：

     - [项目背景](./memory/details/项目背景.md) - [API设计](./memory/details/API设计.md) - [用户认证系统](./memory/details/用户认证系统.md)

4. 生成Start_Memory.md：技能可能会根据某些规则（例如，将#一级标题下的内容，或标记为“重要”的部分）提取出核心信息，生成memory/_import/Start_Memory.md。这个文件需要你后续手动审阅和调整，确保它包含了智能体快速启动所需的最关键信息，比如：“我是项目X的AI助手，当前核心任务是完成Y模块的开发，需要特别注意Z规范。”
5. 处理原始日志：技能可能会检查是否存在按日期命名的日志文件，或建议你建立这样的习惯。

实操心得：

• 首次运行建议在测试副本上进行：你可以先将你的MEMORY.md复制到一个临时目录，在该目录下运行技能，检查生成的文件结构和内容拆分是否符合预期，再应用到正式环境。
• 拆分粒度是关键：自动拆分可能不完美。你可能需要手动调整details/下的文件。一个主题应该多大？原则是“高内聚，低耦合”。如果一个主题下的内容超过500行或涉及多个完全不相关的子话题，考虑进一步拆分。反之，如果多个只有几行的小主题高度相关，可以合并。
• 精心雕琢 Start_Memory.md：这个文件是每次会话的“第一印象”。不要把所有东西都塞进去。只放绝对必要的、能定义本次会话基调和范围的信息。通常包括：智能体角色、当前核心目标、1-3个最重要的约束条件或规范。

4. 日常使用工作流与最佳实践

重构完成后，你的工作方式需要适应新的结构。下面是一个推荐的高效日常使用流程。

4.1 记忆的写入：从日志到知识库

你的记忆增长源头主要是每日的对话和操作。建议采用“日志 -> 提炼 -> 归档”的三段式流程。

1. 原始记录 (Raw Logging)：

   • 每天（或每个会话）开始时，在memory/目录下创建一个以当天日期命名的文件，如2024-05-27.md。
   • 在整个工作过程中，所有零散的、未经过滤的对话摘要、代码片段、错误信息、临时想法，都追加到这个日期文件中。你可以使用简单的模板：

     ## 会话记录 (2024-05-27 14:00) **用户请求**：实现一个用户登录的API端点。 **AI响应**：建议使用JWT，提供了初步的代码框架。 **执行结果**：代码已编写，待测试。

   • 关键点：这个阶段追求全面和速度，不要纠结于格式和归类。

2. 每日复盘与提炼 (Daily Curation)：

   • 在一天工作结束时，花10-15分钟浏览当天的2024-05-27.md。
   • 将其中有长期价值的“知识点”提取出来。例如：
     • 学习 (Learning)：发现bcrypt比md5更适合密码哈希，并记录了原因。 -> 将此条复制到.learnings/LEARNINGS.md。
     • 错误 (Error)：在配置数据库连接池时，因为参数max_connections设置过高导致内存溢出。 -> 将此条复制到.learnings/ERRORS.md，并记录解决方案。
     • 功能请求 (Feature Request)：用户提到需要一个导出报表的功能。 -> 将此条复制到.learnings/FEATURE_REQUESTS.md。
   • 对于已经非常成熟、可以直接归档的完整主题内容，可以直接在memory/details/下创建或更新对应的文件。

3. 定期归档 (Periodic Archiving)：

   • 每周或每两周，系统性地处理.learnings/目录下的内容。
   • 将LEARNINGS.md中经过验证的最佳实践，整理成文，合并到memory/details/开发规范.md或memory/details/技术选型.md中。
   • 将ERRORS.md中的典型错误和解决方案，分类归档到memory/details/故障排查指南.md。
   • 清空或标记已处理的.learnings/内容。

4.2 记忆的读取：高效检索与上下文构建

当智能体需要回答问题时，理想的工作流如下：

1. 会话初始化：OpenClaw自动加载memory/_import/Start_Memory.md。这为智能体提供了本次任务的“战略背景”。
2. 用户提问：用户提出具体问题，例如：“我们之前是怎么处理分页查询的？”
3. 触发检索：智能体（或配置的工作流）自动调用Memory_Search工具，以“分页查询”为查询词进行搜索。
4. 获取片段：Memory_Search返回相关性最高的结果，比如指向memory/details/数据库操作规范.md#分页的链接或片段。
5. 注入上下文：智能体调用Memory_Get工具，精准地将数据库操作规范.md文件中关于分页的那一部分内容（可能只有十几行）拉取到当前对话上下文中。
6. 生成回答：智能体基于精准的、小范围的上下文，生成准确且成本低廉的回答。

为了让这个流程更顺畅，你需要：

• 为细节文件起好名字：memory/details/下的文件名应该清晰、具有描述性，最好使用名词短语，如用户模型设计.md、第三方支付集成（支付宝）.md。这有助于你和检索工具理解文件内容。
• 在文件内部使用清晰的标题：在细节文件内部，使用Markdown标题（#,##,###）来组织内容。这不仅能提高可读性，也能让Memory_Get工具在需要时定位到更细粒度的章节。
• 维护好索引：虽然MEMORY.md是自动生成的，但偶尔检查一下是必要的。确保索引项能准确反映details/目录下的内容，没有死链接。

5. 高级技巧、问题排查与优化

5.1 性能调优与成本控制

• 监控令牌使用：定期关注你的OpenClaw API调用日志，对比使用新记忆结构前后的平均每次交互的令牌消耗（特别是输入令牌）。你应该能看到显著下降。
• 优化Start_Memory.md：这是降低固定成本的关键。定期审视这个文件，移除过时的信息，只保留最核心、最通用的指引。可以尝试不同的内容，观察对智能体初期理解任务的影响。
• 细节文件的“冷热”分离：对于极少访问的历史档案类记忆，可以考虑将其从memory/details/移动到另一个归档目录（如memory/archive/），并在MEMORY.md索引中备注。这样可以保持活跃记忆库的紧凑。Memory_Search的索引范围需要相应调整。

5.2 常见问题与解决方案

5.3 技能的扩展与定制

openclaw-memory-compact提供了一个基础框架。你可以根据自身项目特点进行定制：

• 自定义拆分规则：如果你项目的MEMORY.md有独特的格式（比如使用特定的标签<!-- topic: xxx -->），你可以修改技能的解析逻辑，使其能更智能地识别和拆分主题。
• 集成自动化工具：将“每日复盘”和“定期归档”的步骤脚本化。例如，写一个Python脚本，每天晚上自动扫描当天的日志文件，根据关键词将内容初步分类到.learnings/下的不同文件。
• 调整目录结构：如果你的项目涉及多个完全独立的子模块，可以考虑在memory/details/下再创建子目录，如memory/details/module_a/,memory/details/module_b/。相应地，需要调整技能以支持这种嵌套索引。

重构记忆系统，从短期看是一项需要投入的工程，但从长期看，它是提升与AI智能体协作效率、控制成本、并构建可长期演进的项目知识库的基石。它迫使你以更结构化的方式思考知识的积累，这本身对项目管理就是极大的益处。开始可能会有些磕绊，但一旦这套流程运转起来，你会发现自己和智能体的“对话”将变得更加聚焦、高效和富有成果。