- Published on
OpenClaw 原生长期记忆功能解析
- Authors
- Name
- 卢翔宇
- @y9840836216317
openclaw memory
1. 对外入口与核心类型
index.d.ts：模块总出口（MemoryIndexManager、类型、manager 工厂）。types.d.ts：公共类型（搜索结果、状态、同步进度、manager 接口）。search-manager.d.ts：根据配置创建/返回 memory search manager。
2. 配置与后端选择
backend-config.d.ts：解析 memory backend 配置（builtin/qmd、qmd 集合/更新/限制）。
3. Embedding Provider 抽象与实现
embeddings.d.ts：embedding 抽象接口、provider 选择与回退。embeddings-openai.d.ts：OpenAI provider/client 构建。embeddings-gemini.d.ts：Gemini provider/client 构建。embeddings-voyage.d.ts：Voyage provider/client 构建。embeddings-mistral.d.ts：Mistral provider/client 构建。embeddings-remote-client.d.ts：统一远程鉴权客户端构建。embeddings-remote-provider.d.ts：远程 provider 通用适配。embeddings-remote-fetch.d.ts：远程 embedding 向量请求。embeddings-debug.d.ts：embedding 调试日志。node-llama.d.ts：本地node-llama-cpp动态导入与模型路径解析。embedding-model-limits.d.ts：不同 provider 的输入 token 上限解析。embedding-chunk-limits.d.ts：按 token 限制过滤/裁剪 chunk。embedding-input-limits.d.ts：UTF-8 字节估算与文本切分。
4. Batch Embedding 能力
batch-runner.d.ts：批任务分组、并发执行、轮询、超时控制。batch-provider-common.d.ts：批处理通用状态类型与常量。batch-utils.d.ts：批处理请求头、baseUrl、请求分组工具。batch-http.d.ts：带重试的 JSON POST。batch-upload.d.ts：上传 JSONL 批处理文件。batch-output.d.ts：解析批处理输出行并回填向量。batch-error-utils.d.ts：提取和格式化批处理错误。batch-openai.d.ts：OpenAI 批量 embedding 执行。batch-voyage.d.ts：Voyage 批量 embedding 执行。batch-gemini.d.ts：Gemini 批量 embedding 执行。
5. 检索与排序算法
manager-search.d.ts：SQLite 向量检索、关键词检索、chunk 列举。hybrid.d.ts：向量+关键词混合排序（含权重合并）。mmr.d.ts：MMR 多样性重排。temporal-decay.d.ts：时间衰减打分。query-expansion.d.ts：FTS-only 查询扩展（关键词抽取/可选 LLM）。
6. Index Manager 主流程（builtin backend）
manager-sync-ops.d.ts：索引同步底座（schema、watcher、增量同步、meta、回退）。manager-embedding-ops.d.ts：embedding 相关同步流程（缓存、批量、超时、重试）。manager.d.ts：MemoryIndexManager主类（search/sync/status/read/close）。memory-schema.d.ts：初始化 memory 索引 schema（FTS/缓存表等）。sqlite-vec.d.ts：加载 sqlite-vec 扩展。sqlite.d.ts：node:sqlite引入。
7. QMD Backend 相关
qmd-manager.d.ts：QMD manager（集合管理、update/embed、搜索、session 导出、scope）。qmd-query-parser.d.ts：解析 QMD 查询 JSON 输出。qmd-scope.d.ts：QMD scope 校验与会话通道类型推导。
8. 文件与会话处理工具
internal.d.ts：通用内部工具（文件扫描、hash、markdown chunk、相似度、并发）。fs-utils.d.ts：文件 stat 与 ENOENT 判断。session-files.d.ts：session 文件扫描、文本提取、entry 构建与行号映射。
9. 网络与 HTTP 工具
post-json.d.ts：通用 JSON POST 与 payload 解析。remote-http.d.ts：远程 HTTP 调用包装与 SSRF 策略支持。
系统架构图
OpenClaw Memory Architecture (ASCII)
+--------------------------------------------------------------+
| Caller / Agent |
| (search / sync / status) |
+------------------------------+-------------------------------+
|
v
+--------------------------------------------------------------+
| search-manager.d.ts |
| getMemorySearchManager(cfg, agentId, purpose) |
+------------------------------+-------------------------------+
|
+-------------+-------------+
| |
v v
+-------------------------------+ +---------------------------+
| Builtin Backend Path | | QMD Backend Path |
| manager.d.ts | | qmd-manager.d.ts |
| MemoryIndexManager | | QmdMemoryManager |
+---------------+---------------+ +------------+--------------+
| |
| search/sync/status/read | search/sync/status/read
v v
+-------------------------------+ +---------------------------+
| manager-sync-ops.d.ts | | qmd-query-parser.d.ts |
| - schema/watch/incremental | | qmd-scope.d.ts |
| - source/session sync | | backend-config.d.ts |
+---------------+---------------+ +------------+--------------+
|
v
+-------------------------------+
| manager-embedding-ops.d.ts |
| - cache / retry / timeout |
| - provider batch + fallback |
+---------------+---------------+
|
v
+-------------------------------+
| embeddings.d.ts |
| createEmbeddingProvider(...) |
+-------+-----------+-----------+-------------------------------+
| | | |
v v v v
+-----------+ +-----------+ +-----------+ +---------------------+
| openai | | gemini | | voyage | | mistral / local |
| embeddings| | embeddings| | embeddings| | node-llama |
+-----+-----+ +-----+-----+ +-----+-----+ +----------+----------+
| | | |
+-------------+-------------+-------------------+
|
v
+--------------------------------------------------------------+
| Batch Pipeline (optional) |
| batch-runner / batch-openai / batch-voyage / batch-gemini |
| batch-upload / batch-output / batch-error-utils / batch-http |
+------------------------------+-------------------------------+
|
v
+--------------------------------------------------------------+
| Search + Ranking |
| manager-search (vector/fts) -> hybrid -> mmr -> temporal |
| query-expansion (fts-only helper) |
+------------------------------+-------------------------------+
|
v
+--------------------------------------------------------------+
| Storage Layer |
| sqlite + sqlite-vec + memory-schema |
| Sources: memory files + session-files |
| Utilities: internal / fs-utils / post-json / remote-http |
+--------------------------------------------------------------+
架构总览
+-------------------------+
| index.ts / types.ts |
| 对外 API 与类型导出 |
+------------+------------+
|
+--------------v----------------+
| MemoryIndexManager |
| manager.ts |
+------+---------------+---------+
| |
+--------------v--+ +----v------------------+
| manager-sync-ops | | manager-embedding-ops |
| 扫描/同步/watch | | 向量生成/批处理写入 |
+---------+--------+ +-----------+-----------+
| |
+-----------v-----------+ +---------v-----------------------+
| internal/session-files | | embeddings.ts + provider family |
| 文件发现/分块/会话抽取 | | openai/gemini/voyage/... |
+-----------+-----------+ +---------+-----------------------+
| |
+-----------v-------------+ +----------v----------------+
| sqlite.ts/sqlite-vec.ts | | batch-*.ts / post-json.ts |
| 索引库与向量扩展加载 | | 远端批处理、HTTP 与结果回填 |
+-----------+-------------+ +----------+----------------+
| |
+-----------v----------------------------v---------+
| manager-search.ts + hybrid.ts + mmr.ts + decay.ts |
| 向量检索 + 关键词检索 + 混排重排 + 时间衰减 |
+----------------------+----------------------------+
|
+-------------------v--------------------+
| search-manager.ts / qmd-manager.ts |
| backend 分发（builtin / qmd）与 fallback |
+-----------------------------------------+