乐于分享
好东西不私藏
夜雨聆风 > > 办公文件 > OpenClaw Memory 深入分析

OpenClaw Memory 深入分析

当前时间： 1970-01-01 08:00:00 分类：办公文件 评论(0)
OpenClaw Memory 深入分析

一、Memory 概述

Memory 是 OpenClaw 的记忆系统，负责：

  • 长期记忆存储与检索
  • 向量嵌入与语义搜索
  • 会话日志索引
  • 多源记忆整合（MEMORY.md + 会话日志 + 自定义文档）

二、核心文件结构

src/memory/├── manager.ts               # 记忆索引管理器 (28KB)├── manager-sync-ops.ts      # 同步操作 (46KB)├── manager-embedding-ops.ts # 嵌入操作 (31KB)├── qmd-manager.ts           # QMD 管理器 (70KB)├── backend-config.ts        # 后端配置 (11KB)├── embeddings.ts            # 嵌入提供者 (12KB)├── embeddings-openai.ts     # OpenAI 嵌入├── embeddings-gemini.ts     # Gemini 嵌入├── embeddings-voyage.ts     # Voyage 嵌入├── embeddings-mistral.ts    # Mistral 嵌入├── embeddings-ollama.ts     # Ollama 嵌入├── search-manager.ts        # 搜索管理├── hybrid.ts                # 混合搜索├── mmr.ts                   # MMR 重排序├── temporal-decay.ts        # 时间衰减├── query-expansion.ts       # 查询扩展├── session-files.ts         # 会话文件处理├── internal.ts              # 内部工具└── types.ts                 # 类型定义

三、核心架构

┌─────────────────────────────────────────────────────────────┐│                     Memory 系统架构                          │├─────────────────────────────────────────────────────────────┤│  记忆源 (Memory Sources)                                    ││  ├── MEMORY.md              # 长期记忆                      ││  ├── memory/YYYY-MM-DD.md   # 每日日志                       ││  └── sessions/*.jsonl       # 会话日志                       │├─────────────────────────────────────────────────────────────┤│  MemoryIndexManager                                         ││  ├── 嵌入提供者 (OpenAI/Gemini/Voyage/Mistral/Ollama/Local) ││  ├── SQLite + sqlite-vec   # 向量存储                       ││  └── FTS5                   # 全文搜索                       │├─────────────────────────────────────────────────────────────┤│  搜索流程                                                    ││  1. query → embedQuery() → 向量搜索                         ││  2. query → extractKeywords() → FTS 搜索                    ││  3. mergeHybridResults() → MMR 重排序                       ││  4. temporalDecay() → 时间衰减调整                           │└─────────────────────────────────────────────────────────────┘

四、MemoryIndexManager 核心类

4.1 类结构

class MemoryIndexManager extends MemoryManagerEmbeddingOps {// 配置protected cfg: OpenClawConfig;protected agentId: string;protected workspaceDir: string;protected settings: ResolvedMemorySearchConfig;// 嵌入提供者protected provider: EmbeddingProvider | null;protected openAi?: OpenAiEmbeddingClient;protected gemini?: GeminiEmbeddingClient;protected voyage?: VoyageEmbeddingClient;protected mistral?: MistralEmbeddingClient;protected ollama?: OllamaEmbeddingClient;// 存储protected db: DatabaseSync;           // SQLiteprotected sources: Set<MemorySource>; // 记忆源// 搜索能力protected vector: { enabled: boolean; dims?: number; };protected fts: { enabled: boolean; available: boolean; };// 同步状态protected dirty: boolean;protected sessionsDirty: boolean;protected watcher: FSWatcher | null;}

4.2 获取实例

// 缓存管理器实例const INDEX_CACHE = new Map<string, MemoryIndexManager>();staticasyncget(params: {  cfg: OpenClawConfig;  agentId: string;}): Promise<MemoryIndexManager | null> {const settings = resolveMemorySearchConfig(cfg, agentId);if (!settings) returnnull;const key = `${agentId}:${workspaceDir}:${JSON.stringify(settings)}`;if (INDEX_CACHE.has(key)) {return INDEX_CACHE.get(key);  }// 创建新实例const manager = new MemoryIndexManager(/* ... */);  INDEX_CACHE.set(key, manager);return manager;}

五、搜索流程

5.1 search 方法

async search(  query: string,  opts?: { maxResults?: number; minScore?: number; sessionKey?: string; }): Promise<MemorySearchResult[]> {// 1. 触发同步（如果 dirty）if (this.settings.sync.onSearch && this.dirty) {voidthis.sync({ reason: "search" });  }// 2. 无提供者时降级为 FTS-onlyif (!this.provider) {const keywords = extractKeywords(query);returnawaitthis.searchKeyword(keywords, maxResults);  }// 3. 向量搜索const queryVec = awaitthis.embedQueryWithTimeout(query);const vectorResults = awaitthis.searchVector(queryVec, candidates);// 4. FTS 搜索const keywordResults = awaitthis.searchKeyword(query, candidates);// 5. 混合合并 + MMR 重排序const merged = awaitthis.mergeHybridResults({    vector: vectorResults,    keyword: keywordResults,    vectorWeight: 0.7,    textWeight: 0.3,    mmr: { enabled: true, lambda: 0.5 },    temporalDecay: { enabled: true, halfLifeDays: 30 }  });return merged.filter(r => r.score >= minScore);}

5.2 向量搜索

privateasync searchVector(  queryVec: number[],  limit: number): Promise<MemorySearchResult[]> {// 使用 sqlite-vec 进行向量相似度搜索const results = await searchVector({    db: this.db,    vectorTable: "chunks_vec",    queryVec,    limit,    snippetMaxChars: 700,  });return results;}

5.3 FTS 搜索

privateasync searchKeyword(  query: string,  limit: number): Promise<MemorySearchResult[]> {// 构建 FTS5 查询const ftsQuery = buildFtsQuery(query);// 执行全文搜索const results = await searchKeyword({    db: this.db,    ftsTable: "chunks_fts",    query: ftsQuery,    limit,  });return results;}

5.4 混合合并

// src/memory/hybrid.tsasyncfunctionmergeHybridResults(params: {  vector: SearchResult[];  keyword: SearchResult[];  vectorWeight: number;  textWeight: number;  mmr?: { enabled: boolean; lambda: number };  temporalDecay?: { enabled: boolean; halfLifeDays: number };}): Promise<SearchResult[]> {// 1. 归一化分数// 2. 加权合并// 3. MMR 重排序（减少冗余）// 4. 时间衰减return merged;}

六、嵌入系统

6.1 嵌入提供者接口

type EmbeddingProvider = {  id: string;  model: string;  maxInputTokens?: number;// 单条查询嵌入  embedQuery(text: string): Promise<number[]>;// 批量嵌入  embedBatch(texts: string[]): Promise<number[][]>;// 带输入类型的批量嵌入  embedBatchInputs?(inputs: EmbeddingInput[]): Promise<number[][]>;};

6.2 支持的提供者

提供者
模型示例
特点
OpenAItext-embedding-3-small
, text-embedding-3-large
高质量，需 API Key
Geminitext-embedding-004
支持多维度 (768/1536/3072)
Voyagevoyage-3-large
高性能，支持批量
Mistralmistral-embed
开源模型
Ollamanomic-embed-text
本地部署
Localembeddinggemma-300m
CPU 可运行，无需网络

6.3 创建提供者

asyncfunctioncreateEmbeddingProvider(options: {  config: OpenClawConfig;  provider: "openai" | "gemini" | "voyage" | "mistral" | "ollama" | "local" | "auto";  model: string;  fallback: EmbeddingProviderId | "none";}): Promise<EmbeddingProviderResult> {switch (options.provider) {case"openai":return createOpenAiEmbeddingProvider(options);case"gemini":return createGeminiEmbeddingProvider(options);case"voyage":return createVoyageEmbeddingProvider(options);// ...case"auto":// 自动选择：尝试 OpenAI → Gemini → Voyage → localreturn tryAutoSelect(options);  }}

七、同步机制

7.1 记忆文件同步

// manager-sync-ops.tsprivateasync syncMemoryFiles(params: {  sources: MemorySource[];  progress?: MemorySyncProgressState;}): Promise<void> {// 1. 列出所有记忆文件const files = await listMemoryFiles({    workspaceDir: this.workspaceDir,    sources: params.sources,  });// 2. 计算文件哈希，检测变更for (const file of files) {const hash = await hashText(content);if (hash !== storedHash) {      changedFiles.push(file);    }  }// 3. 处理变更文件for (const file of changedFiles) {awaitthis.processFile(file);  }// 4. 更新索引awaitthis.updateIndex();}

7.2 会话文件同步

privateasync syncSessionFiles(params: {  agentId: string;}): Promise<void> {// 1. 列出会话日志文件const files = await listSessionFilesForAgent({    agentId: params.agentId,    config: this.cfg,  });// 2. 读取增量内容for (const file of files) {const delta = awaitthis.readSessionDelta(file);if (delta.pendingBytes > 0) {awaitthis.processSessionDelta(file, delta);    }  }// 3. 更新会话索引awaitthis.updateSessionIndex();}

7.3 监听文件变更

// 使用 chokidar 监听protected watcher: FSWatcher | null = null;private startWatcher() {this.watcher = chokidar.watch(this.workspaceDir, {    ignored: /node_modules|\.git/,    persistent: true,  });this.watcher.on("change", (path) => {if (isMemoryPath(path)) {this.dirty = true;this.scheduleSync();    }  });}

八、QMD (Query-Memory-Document) 管理器

8.1 概述

QMD 是一个外部记忆后端，通过 CLI 工具实现高级搜索功能：

  • 语义搜索
  • 混合检索
  • 重排序

8.2 配置

type ResolvedQmdConfig = {  command: string;              // QMD CLI 命令  searchMode: "search" | "query";  collections: ResolvedQmdCollection[];  sessions: ResolvedQmdSessionConfig;  update: ResolvedQmdUpdateConfig;  limits: ResolvedQmdLimitsConfig;  mcporter: ResolvedQmdMcporterConfig;};

8.3 搜索流程

async search(query: string): Promise<MemorySearchResult[]> {// 1. 构建 QMD 查询const qmdQuery = {    query: normalizeHanBm25Query(query),    collections: this.collections,    mode: this.searchMode,  };// 2. 执行 CLI 命令const output = await runCliCommand({    command: this.command,    args: ["search", JSON.stringify(qmdQuery)],    timeout: this.limits.timeoutMs,  });// 3. 解析结果const results = parseQmdQueryJson(output);return results;}

九、MMR 重排序

9.1 Maximal Marginal Relevance

// src/memory/mmr.tsfunctionmmr(params: {  query: number[];  docs: { id: string; vector: number[]; score: number }[];  lambda: number;  // 0.0-1.0, 相关性与多样性权衡  k: number;       // 返回数量}): string[] {const selected: string[] = [];const remaining = [...docs];while (selected.length < k && remaining.length > 0) {let bestScore = -Infinity;let bestIdx = 0;for (let i = 0; i < remaining.length; i++) {const relevance = cosineSimilarity(query, remaining[i].vector);// 计算与已选文档的最大相似度（冗余度）let maxSimilarity = 0;for (const sel of selected) {const sim = cosineSimilarity(          remaining[i].vector,          docs.find(d => d.id === sel)!.vector        );        maxSimilarity = Math.max(maxSimilarity, sim);      }// MMR 分数const mmrScore = lambda * relevance - (1 - lambda) * maxSimilarity;if (mmrScore > bestScore) {        bestScore = mmrScore;        bestIdx = i;      }    }    selected.push(remaining[bestIdx].id);    remaining.splice(bestIdx, 1);  }return selected;}

十、时间衰减

// src/memory/temporal-decay.tsfunctionapplyTemporalDecay(params: {  results: SearchResult[];  halfLifeDays: number;}): SearchResult[] {const now = Date.now();const halfLifeMs = params.halfLifeDays * 24 * 60 * 60 * 1000;return params.results.map(result => {const ageMs = now - result.timestamp;const decay = Math.pow(0.5, ageMs / halfLifeMs);return {      ...result,      score: result.score * decay,    };  });}

十一、查询扩展

// src/memory/query-expansion.tsfunctionextractKeywords(query: string): string[] {// 1. 清理文本const cleaned = query    .toLowerCase()    .replace(/[^\w\s\u4e00-\u9fff]/g, ' ')    .trim();// 2. 分词const tokens = cleaned.split(/\s+/);// 3. 过滤停用词const filtered = tokens.filter(t => !STOPWORDS.has(t));// 4. 提取关键词return filtered.slice(0, 10);}

十二、配置示例

# openclaw.json{"memory":{"backend":"builtin",//or"qmd""citations":"auto","provider":"auto","model":"text-embedding-3-small","query":{"maxResults":10,"minScore":0.35,"hybrid":{"enabled":true,"vectorWeight":0.7,"textWeight":0.3,"mmr":{"enabled":true,"lambda":0.5},"temporalDecay":{"enabled":true,"halfLifeDays":30}}},"sync":{"onBoot":true,"onSearch":true,"interval":"5m"}}}

十三、总结

Memory 是 OpenClaw 的长期记忆系统：

  1. 多源整合：MEMORY.md + 每日日志 + 会话日志
  2. 混合搜索：向量搜索 + FTS + MMR 重排序
  3. 多提供者：OpenAI/Gemini/Voyage/Mistral/Ollama/Local
  4. 增量同步：文件监听 + 定时同步
  5. 时间感知：时间衰减调整相关性

关键特性：

  • 语义搜索（向量嵌入）
  • 全文搜索（FTS5）
  • MMR 重排序（减少冗余）
  • 时间衰减（近期优先）
  • 多后端支持（builtin / QMD）