夜雨聆风
一、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 支持的提供者
| OpenAI | text-embedding-3-smalltext-embedding-3-large | |
| Gemini | text-embedding-004 | |
| Voyage | voyage-3-large | |
| Mistral | mistral-embed | |
| Ollama | nomic-embed-text | |
| Local | embeddinggemma-300m |
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 的长期记忆系统：
多源整合：MEMORY.md + 每日日志 + 会话日志 混合搜索：向量搜索 + FTS + MMR 重排序 多提供者：OpenAI/Gemini/Voyage/Mistral/Ollama/Local 增量同步：文件监听 + 定时同步 时间感知：时间衰减调整相关性
关键特性：
语义搜索（向量嵌入） 全文搜索（FTS5） MMR 重排序（减少冗余） 时间衰减（近期优先） 多后端支持（builtin / QMD）
