OpenClaw Memory

核心用法

openclaw-mem 是 OpenClaw 代理的记忆基础设施管理技能，解决 LLM 上下文窗口有限导致的"遗忘"问题。核心架构分为两层：

• 每日日志层（memory/YYYY-MM-DD.md）：追加式会话记录，自动加载今昨两日内容
• 长期记忆层（MEMORY.md）：经人工策展的持久化事实，私聊会话启动时加载

显著优点

1. 文件即真理：纯 Markdown 存储，无黑盒数据库，可版本控制、人工审计
2. 混合检索：向量相似度 + BM25 关键词的加权融合，兼顾语义理解与精确匹配
3. 防压容错：自动 memory flush 机制在上下文压缩前静默写入 durable notes
4. 模块化扩展：支持 Mem0/Cognee/Supermemory 等外接记忆插件
5. 精细调优：Temporal Decay（时间衰减）和 MMR（最大边缘相关性）解决陈旧信息霸榜与结果冗余问题

潜在缺点与局限性

• 冷启动成本：首次配置需理解两层架构的取舍，易误把临时指令存错位置
• Embedding 依赖：语义搜索需额外 API key（Codex OAuth 不覆盖），本地模型需手动配置路径
• 文件大小硬限制：MEMORY.md >20k 字符自动截断，大项目需主动分片维护
• 群组会话降级：MEMORY.md 仅在私聊加载，群聊场景记忆能力显著削弱
• QMD 实验性：高性能本地检索需额外安装 Bun 环境与 GGUF 模型，首次运行下载耗时

适合人群

• 长期项目协作者（需跨周/月保持上下文）
• 多代理工作流设计者（依赖 AGENTS.md 规则持久化）
• 对"可解释 AI"有要求的用户（文件级透明审计）

常规风险

| 风险场景 | 缓释措施 |

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

| 规则仅存于聊天，压缩后丢失 | 强制 AGENTS.md 写入 "search memory before acting" |

| Embedding 配置错误导致检索失效 | 校验 API key，优先使用 OpenAI/Gemini 等主流端点 |

| MEMORY.md 膨胀致关键信息截断 | 月度蒸馏，将成熟规则迁移至 Skill 文件 |

| 敏感信息随日志持久化 | 排除 credentials/ 与 openclaw.json 于版本控制外 |

关键配置检查项

# 健康诊断三命令
openclaw /context list          # 确认 MEMORY.md 加载状态与截断情况
wc -c ~/.openclaw/workspace/*.md # 审计文件体积
openclaw config get agents.defaults.compaction.memoryFlush  # 确认 flush 启用

核心概述

openclaw-mem 是一套针对 OpenClaw agent 记忆系统的专业配置与运维指南，以纯 Markdown 文档形式提供。它覆盖了从基础架构理解到高级优化调优的完整知识体系，帮助用户构建可靠、可扩展的 agent 长期记忆能力。

核心用法

双层记忆架构

• Daily Logs (`memory/YYYY-MM-DD.md`)：仅加载今天和昨天的日志，用于会话上下文延续
• Long-Term Memory (`MEMORY.md`)：精简的持久事实库，仅在私有会话启动时加载，20K 字符上限

关键配置操作

1. 强制检索协议：在 AGENTS.md 中添加规则，确保 agent 执行任务前必须先 memory_search
2. Compaction 防护：启用 memoryFlush 自动 flush 机制，在上下文压缩前将关键信息写入磁盘
3. 混合搜索调优：配置 vector + BM25 权重、时间衰减、MMR 去重等高级参数
4. 外部记忆扩展：可选接入 Mem0、Cognee、Supermemory 等插件突破原生限制

故障排查流程

运行 /context list 诊断 → 检查文件加载状态 → 验证 embedding 提供商配置 → 确认 memoryFlush 启用 → 审查文件大小是否超限

显著优点

• 架构清晰：双层设计平衡了即时上下文与长期记忆，避免单一文件膨胀
• 无 vendor lock-in：纯 Markdown 存储，可版本控制、人工审计、随时迁移
• 灵活的检索策略：hybrid search 结合语义相似度与精确关键词匹配，覆盖多样化查询场景
• 完善的防护机制：compaction flush + 文件生存规则双重保障关键信息不丢失
• 丰富的扩展生态：支持 QMD 高性能后端、多种 embedding 提供商、第三方记忆插件

潜在局限

• 文件大小硬性限制：MEMORY.md 超 20K 字符即被截断，需要主动维护精简
• 无自动事实提取：原生系统不会自动从对话中提取记忆，依赖用户手动写入或配置 Mem0 等插件
• embedding 成本：使用 OpenAI/Gemini 等云服务需额外 API key，Codex OAuth 不覆盖 embeddings
• QMD 后端门槛高：需要单独安装 Bun 运行环境和下载 GGUF 模型，初次使用体验较重
• T3 来源信任度：由个人开发者维护，虽经安全扫描但仍需社区持续验证

适合人群

• OpenClaw 重度用户，需要 agent 跨会话保持上下文和记忆
• 多项目并行开发者，需要精细控制不同会话的记忆加载策略
• 对 RAG/向量检索有一定了解，希望调优搜索质量的技术用户
• 遇到 agent"遗忘"问题、需要系统性排查和加固记忆架构的运维人员

常规风险

• 配置错误导致记忆失效：embedding 提供商未配置、API key 无效、文件路径错误等常见问题
• 过度依赖聊天上下文：未将关键规则写入文件，compaction 后信息丢失
• 隐私与数据驻留：使用云 embedding 服务时，记忆内容会发送至第三方 API
• 外部代码依赖：QMD 后端和第三方插件引入额外的供应链风险，需自行审计