OpenClaw记忆系统基石 —— memory-search.ts 中的 RAG 配置解析与合并逻辑

关键词：RAG｜配置合并｜向量检索｜全文搜索｜路径解析｜数值校验

在 AI 智能体系统中，“记忆”是实现上下文延续性与知识个性化的关键能力。OpenClaw 的记忆系统不仅支持长期会话回溯，还能接入企业知识库、个人笔记甚至实时文件，形成一个动态、可扩展的混合检索引擎。

这一切的起点，是 src/agents/memory-search.ts —— 一个看似简单却高度灵活的配置解析与检索调度器。本文将揭示其如何通过四层配置合并、路径占位符解析与安全数值校验，为每个智能体构建专属的记忆策略。

一、记忆系统的三层数据源

OpenClaw 的 RAG 引擎可同时从以下来源检索信息：

image

所有数据在检索前被统一嵌入（embedding），存入 SQLite 向量数据库。

二、配置分层：四重覆盖机制

与全局配置类似，记忆系统也采用分层覆盖模型，优先级从低到高：

image

默认配置示例（L1）

// src/agents/memory-search.ts
const DEFAULT_MEMORY_CONFIG = {
  enabled: false,
  vectorWeight: 0.7,
  textWeight: 0.3,
  minSimilarity: 0.25,
  candidateMultiplier: 3,
  maxResults: 5,
  sessionMemory: {
    enabled: true,
    pathTemplate: "sessions/{sessionKey}.jsonl"
  },
  knowledgeBase: {
    enabled: false,
    pathTemplate: "knowledge/{agentId}/"
  }
}

即使用户未配置，系统也有合理默认行为。

三、配置合并与路径解析：resolveMemoryConfig()

核心函数 resolveMemoryConfig(agentId: string, sessionKey: string) 负责：

1. 合并四层配置
2. 解析路径中的占位符
3. 校验数值合法性

占位符替换

配置中的路径支持动态变量：

• {agentId} → 当前智能体 ID（如 dev-assistant）
• {sessionKey} → 会话唯一标识（如 wa:+1234567890）

# agents/dev-assistant/config.yaml
memory:
  knowledgeBase:
    enabled: true
    pathTemplate: "knowledge/{agentId}/"  # → knowledge/dev-assistant/

这使得每个 Agent 可拥有独立知识库，实现多租户隔离。

数值校验：clampNumber() 防御非法输入

为防止用户误配导致系统异常，关键参数被严格限制：

function clampNumber(value: number, min: number, max: number, fallback: number): number {
  if (isNaN(value) || value < min || value > max) {
    console.warn(`Invalid value ${value}, using fallback ${fallback}`);
    return fallback;
  }
  return value;
}

// 使用示例
const vectorWeight = clampNumber(config.vectorWeight, 0, 1, 0.7);

image

防御性编程：不让配置错误拖垮整个检索流程。

四、混合检索权重：为什么是 70% 向量 + 30% 全文？

OpenClaw 采用加权混合检索（Hybrid Search）：

• 向量检索：基于语义相似度（使用 ONNX / OpenAI / Gemini Embedding）
• 全文检索：基于关键词匹配（SQLite FTS5）

最终得分 = vectorScore × vectorWeight + textScore × textWeight

为何默认 0.7 / 0.3？

• 向量主导：LLM 更擅长理解语义，而非关键词
• 全文兜底：防止向量漂移（如“苹果” vs “Apple Inc.”）
• 可调：用户可根据场景调整（技术文档可提高全文权重）

实测表明，该比例在多数场景下召回率与精度最佳。

五、运行时决策：何时启用记忆？

即使配置启用，memory-search.ts 也会动态判断是否执行检索：

触发条件

• 用户问题包含指代性词汇（如“上次”、“之前提到的”）
• 或明确请求知识库查询（如“根据文档…”）
• 或启用了 alwaysEnableMemory（调试模式）

性能保护

• 单次检索超时：2 秒
• 结果过大自动截断（防 OOM）
• 冷启动时异步构建索引，不影响首响应

记忆是增强，不是负担。

六、配置示例：企业知识库实战

# agents/hr-bot/config.yaml
memory:
  enabled: true
  vectorWeight: 0.6
  textWeight: 0.4          # HR 政策需精确关键词匹配
  knowledgeBase:
    enabled: true
    pathTemplate: "knowledge/hr-policies/"  # 公司政策库
  sessionMemory:
    enabled: true          # 也记住员工个人咨询历史

效果： 员工问：“我的产假有多少天？” → AI 同时检索：

1. 公司《HR 政策手册.pdf》
2. 该员工过往关于“生育保险”的对话 → 综合回答，精准且个性化。

结语：配置即策略，记忆即能力

memory-search.ts 的设计哲学是：让记忆策略可声明、可组合、可安全运行。通过精细的配置分层与运行时保护，OpenClaw 既满足了开发者对灵活性的需求，又保障了生产环境的稳定性。

在下一篇中，我们将深入向量检索实现，解析 OpenClaw 如何高效融合向量与全文搜索。

下一篇预告： 第 8 篇：向量检索实战 —— OpenClaw 如何实现混合搜索（向量 + 全文）