OpenClaw 核心架构系统研究报告：结构化记忆与检索机制深度解析

一、 核心理念：结论先行与三层记忆模型

关于 OpenClaw 架构最大的认知误区，是将其等同于“挂载了 Chroma/Milvus 的大模型”。实际上，OpenClaw 的记忆不是模型内部的隐式状态，也不是黑盒向量库，而是工作区里的 Markdown 文件 [Docs: Memory]。

官方文档直接写明：memory/YYYY-MM-DD.md 与 MEMORY.md 是默认记忆层，“Files are the source of truth”（文件就是唯一的真相来源）。模型真正“记住”的只有被写回磁盘的内容。所有的检索、向量索引、BM25 融合、QMD 引擎等，仅仅是围绕这些文件建立的加速召回层。

基于技术白皮书和开发者社区讨论，OpenClaw 的基础架构被抽象为相互独立但可组合的 三层记忆模型 [Tech Article]：

• Context（当前上下文）：每次 LLM 调用时实际能看到的 prompt 上下文，由 Context Engine 负责装配。
• Compaction（压缩层）：当上下文窗口逼近上限时，触发的旧历史摘要压缩机制。
• Memory Files（持久记忆层）：跨会话保留的本地 Markdown 文件。

二、 深度解码：五层结构化记忆机制 (Structured Memory)

OpenClaw 的“结构化”并非预先定义强 schema 的知识图谱，而是先用固定文件布局建立记忆容器，再用检索工具和上下文规则赋予文件结构 [Docs: Workspace]。

1. Workspace 文件系统约定

官方将 Workspace 定义为 Agent 的 Home 目录。标准文件矩阵包括：AGENTS.md, SOUL.md, USER.md, IDENTITY.md, TOOLS.md 等核心设定文件。而真正的“动态记忆”被严格划分：

• memory/YYYY-MM-DD.md：每日追加的日志笔记（Append-only）。
• MEMORY.md：经过 Agent 自主整理的持久偏好与核心事实。

2. 作用域与会话隔离边界

记忆并非“所有会话共享的一锅粥”。MEMORY.md 只在主私聊 session 中注入，绝不污染 group/shared context [Docs: Memory]。Direct chat 状态可汇聚到主 session，而群组拥有独立的隔离状态，保障了多任务处理的安全边界。

3. Context Injection 截断与防污染策略

OpenClaw 不鼓励将全部记忆粗暴塞进 prompt。单文件默认有 20,000 字符注入上限，大文件会被强制截断 [Docs: Context]。这一限制从根本上解释了“为什么必须使用检索机制”：它降低了 Token 成本，并防止了长期记忆直接灌入导致的“大海捞针”噪声风险。

4. 记忆写回机制 (Write-back & Pre-compaction)

系统明确区分“Durable facts”和“日常上下文”。当当前会话逼近 auto-compaction（自动压缩）阈值前，OpenClaw 会触发一次静默的 pre-compaction memory flush（预压缩记忆落盘）。系统甚至默认使用 NO_REPLY 指令，让模型在用户无感知的情况下，先把值得长期保留的内容写入磁盘，完美衔接了“短期上下文丢失”与“长期记忆落盘”的缝隙 [Docs: Memory]。

5. Prompt 级检索规约 (Behavioral Guardrails)

在 memory-core 的源码中，系统硬性注入了 “Memory Recall” 指令。要求 Agent 在回答“过去做过什么、决策、偏好”时，必须先对文件运行 memory_search，再用 memory_get 拉取具体行 [GitHub: memory-core/index.ts]。这标志着检索机制被上升为 AI 代理不可违背的行为规范。

三、 双轨检索机制：内置引擎与高级 QMD 后端

为了支持海量 Markdown 文件的召回，OpenClaw 提供了两套不同复杂度的检索引擎：

轨一：内置轻量级混合检索 (Built-in SQLite)

默认启用，自动监听 MEMORY.md 与 memory/ 变更。索引以 per-agent 形式存放在 ~/.openclaw/memory/<agentId>.sqlite 中。

• 两阶段 Recall：memory_search 先在约 400 token / 80 token overlap 的块上做语义与关键词召回（返回 snippet、路径、行号），随后 LLM 再调用 memory_get 精确读取行。这种“粗召回+精读取”大幅提升了上下文利用率。
• 混合排序公式：结合向量与 BM25 分数，使用 vectorWeight * vectorScore + textWeight * textScore 融合。默认支持本地 sqlite-vec 向量检索 [Docs: Config]。
• 后处理旋钮：提供 Temporal Decay（时间衰减）（如 lambda=0.7, halfLifeDays=30）使新记忆权重更高，以及 MMR（最大边界相关性）利用 Jaccard 相似度减少重复片段。
• 实验性 Transcript 检索：支持对历史 Session JSONL 进行异步最佳尽力（best-effort）检索。

轨二：QMD 高级检索后挂载 (Research-Grade Sidecar)

在配置中开启 memory.backend = "qmd" 后，系统将切换到更强大的 QMD sidecar 进程 [GitHub: QMD]。

• 底层特性：它仍保持 Local-first，运行于独立环境 ~/.openclaw/agents/<agentId>/qmd/，并在失败时可自动降级至 SQLite [Docs: Config]。
• Markdown 感知智能分块：Chunking 极为激进（约 900 token, 15% overlap），且具备 Markdown-aware 特性，能寻找自然断点以保留标题、代码块等完整语义单元。
• Context Tree：支持 qmd context add，在搜索结果中返回树状上下文描述，帮助 LLM 更精准地过滤信息。
• 完整的 RAG Pipeline：包含查询扩展 → 并行 FTS/Vector 检索 → RRF Fusion (倒数排序融合) → LLM Reranking (重排) → 返回融合片段。

四、 社区生态演进与已知风险 (Limitations & Risks)

1. 生态向结构化图谱演进

尽管基础盘是“File-first”，但官方技能库中已出现名为 Structured Memory 的插件。该技能在保持 Markdown 事实源的同时，在其之上构建按日期、模块、实体的重建索引与 Critical fact cards（关键事实卡片）[GitHub: Skills]。这标志着生态正向结构化检索（Structured Retrieval）深度演进。

2. 工程局限与配置陷阱

• 参数过滤陷阱：GitHub Issue #25183 揭露，当 hybrid search 默认 vectorWeight=0.7 / textWeight=0.3 且 minScore=0.35 时，纯粹的精确关键词命中（如特定 ID、项目名）最高分只能到 0.30，从而被系统静默过滤 [GitHub Issue: #25183]。
• QMD 系统稳定性：在 Apple Silicon (macOS Metal) 上，QMD 的 query 模式在 rerank 后偶发 SIGABRT 崩溃，导致 OpenClaw 获取空结果 [QMD Issue: #368]。目前官方推荐 searchMode=search 作为求稳配置。
• 记忆污染风险：因为记忆最终落地为文件，任何注入的错误或 Prompt Injection 痕迹都会被保留并随检索放大。近期的安全论文将 Memory Integrity Validation (记忆完整性校验) 列为 OpenClaw 部署的必选项 [arXiv: 2603.11619]。

五、 研究研判与系统落地建议

宏观研判： OpenClaw 并非追求极致的数据库架构创新，而是巧妙地将 Agent 的记忆打造成一个“人类可见、检索可插拔、上下文可治理、AI 行为受规约”的系统。它的护城河在于其工作流的优雅解耦和文件基石底座。

工程落地建议：

1. 数据隔离规范：严格遵守 MEMORY.md 仅存核心法则（Durable facts），而 memory/YYYY-MM-DD.md 必须保持 Append-only（仅追加日志）以防核心状态崩溃。
2. 渐进式后端升级：小型系统或开发初期，坚守轻量级的内置 SQLite/sqlite-vec 后端。只有当遇到数百个 Markdown 跨文件组合长逻辑查询时，再启用 QMD Sidecar 引擎。
3. 参数调优：优先调整混合检索权重 (vectorWeight/textWeight) 和时间衰减 (lambda)，而非盲目更换更庞大的 Embedding 模型。善用 openclaw memory status --deep 和 memory index --force 进行 CLI 排错。
4. CJK 多语种部署警告：对于处理中文/日韩文的企业，QMD 默认的 embeddinggemma-300M 严重偏向英文。强烈建议替换为 Qwen3-Embedding 等原生多语模型，并强制重建索引 [GitHub: QMD CJK Note]。