Memory

Moltbot 的 memory 是 agent workspace 中的纯 Markdown 文件。这些文件是唯一事实来源；模型只会“记住”被写入磁盘的内容。

memory 搜索工具由当前启用的 memory plugin 提供（默认：memory-core）。可通过 plugins.slots.memory = "none" 禁用 memory plugins。

Memory files（Markdown）

默认 workspace 布局使用两层 memory：

memory/YYYY-MM-DD.md
- 每日日志（只追加）。
- session 启动时会读取今天 + 昨天。
MEMORY.md（可选）
- 经过整理的长期记忆。
- 只会在主私聊 session 中加载（绝不会在群聊上下文中加载）。

这些文件位于 workspace（agents.defaults.workspace，默认 ~/clawd）之下。完整目录结构参见 Agent workspace。

何时写入 memory

决策、偏好与稳定事实写入 MEMORY.md。
日常笔记与运行中的上下文写入 memory/YYYY-MM-DD.md。
如果有人说“记住这个”，就把它写下来（不要只放在 RAM 里）。
这块仍在演进。提醒模型写 memory 会有帮助；模型会知道该做什么。
如果你希望某件事能长期生效，让 bot 把它写入 memory。

自动 memory flush（compaction 前的 ping）

当一个 session 接近 auto-compaction 时，Moltbot 会触发一次静默的 agentic 回合，提醒模型在 context 被 compaction 之前把可持久化的 memory 写入磁盘。默认 prompts 会明确说模型 可以回复，但通常正确的做法是回复 NO_REPLY，这样用户不会看到这次回合。

该行为由 agents.defaults.compaction.memoryFlush 控制：

json5

{
  agents: {
    defaults: {
      compaction: {
        reserveTokensFloor: 20000,
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 4000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store."
        }
      }
    }
  }
}

细节：

Soft threshold：当 session token 估算值跨过 contextWindow - reserveTokensFloor - softThresholdTokens 时触发 flush。
默认 Silent：prompts 会包含 NO_REPLY，因此不会投递任何内容。
两段 prompts：一个 user prompt + 一个 system prompt 追加提醒。
每个 compaction 周期只 flush 一次（在 sessions.json 中跟踪）。
workspace 必须可写：如果 session 在 sandbox 下以 workspaceAccess: "ro" 或 "none" 运行，则会跳过 flush。

完整 compaction 生命周期参见 Session management + compaction。

向量化 memory 搜索（Vector memory search）

Moltbot 可以对 MEMORY.md 与 memory/*.md 构建一个小型向量索引，使语义查询即使在措辞不同的情况下也能找到相关笔记。

默认行为：

默认启用。
监控 memory files 的变更（带 debounce）。
默认使用远端 embeddings。如果未设置 memorySearch.provider，Moltbot 会按以下顺序自动选择：
1. 如果配置了 memorySearch.local.modelPath 且文件存在，则使用 local。
2. 如果能解析出 OpenAI key，则使用 openai。
3. 如果能解析出 Gemini key，则使用 gemini。
4. 否则 memory search 保持禁用，直到配置完成。
Local 模式使用 node-llama-cpp，可能需要 pnpm approve-builds。
可用时使用 sqlite-vec，以加速 SQLite 内的向量搜索。

远端 embeddings 必须为 embedding provider 提供 API key。Moltbot 会从 auth profiles、models.providers.*.apiKey 或环境变量解析 key。Codex OAuth 只覆盖 chat/completions，不能满足 memory search 的 embeddings。Gemini 请使用 GEMINI_API_KEY 或 models.providers.google.apiKey。使用自定义 OpenAI 兼容端点时，请设置 memorySearch.remote.apiKey（以及可选的 memorySearch.remote.headers）。

Gemini embeddings（原生）

将 provider 设为 gemini 可直接使用 Gemini embeddings API：

json5

agents: {
  defaults: {
    memorySearch: {
      provider: "gemini",
      model: "gemini-embedding-001",
      remote: {
        apiKey: "YOUR_GEMINI_API_KEY"
      }
    }
  }
}

备注：

remote.baseUrl 可选（默认使用 Gemini API base URL）。
如有需要可用 remote.headers 追加 headers。
默认模型：gemini-embedding-001。

如果你想使用 自定义 OpenAI 兼容端点（OpenRouter、vLLM 或代理），可以在 OpenAI provider 下使用 remote 配置：

json5

agents: {
  defaults: {
    memorySearch: {
      provider: "openai",
      model: "text-embedding-3-small",
      remote: {
        baseUrl: "https://api.example.com/v1/",
        apiKey: "YOUR_OPENAI_COMPAT_API_KEY",
        headers: { "X-Custom-Header": "value" }
      }
    }
  }
}

如果你不想设置 API key，请使用 memorySearch.provider = "local" 或设置 memorySearch.fallback = "none"。

Fallbacks：

memorySearch.fallback 可选 openai、gemini、local 或 none。
fallback provider 只会在主 embedding provider 失败时使用。

批量索引（OpenAI + Gemini）：

对 OpenAI 与 Gemini embeddings 默认启用。设置 agents.defaults.memorySearch.remote.batch.enabled = false 可禁用。
默认行为会等待 batch 完成；必要时可调 remote.batch.wait、remote.batch.pollIntervalMs 与 remote.batch.timeoutMinutes。
使用 remote.batch.concurrency 控制并行提交的 batch jobs 数（默认：2）。
Batch 模式在 memorySearch.provider = "openai" 或 "gemini" 时生效，并使用对应 API key。
Gemini batch jobs 使用异步 embeddings batch 端点，要求 Gemini Batch API 可用。

为什么 OpenAI batch 又快又便宜：

对大规模回填（backfills），OpenAI 往往是我们支持的最快选项，因为我们可以把大量 embedding 请求提交为一个 batch job，让 OpenAI 异步处理。
OpenAI 为 Batch API 提供折扣定价，因此大规模索引通常比同步发送同样请求更便宜。
详情参见 OpenAI Batch API 文档与定价：
- https://platform.openai.com/docs/api-reference/batch
- https://platform.openai.com/pricing

配置示例：

json5

agents: {
  defaults: {
    memorySearch: {
      provider: "openai",
      model: "text-embedding-3-small",
      fallback: "openai",
      remote: {
        batch: { enabled: true, concurrency: 2 }
      },
      sync: { watch: true }
    }
  }
}

工具：

memory_search — 返回带 file + line ranges 的 snippets。
memory_get — 按路径读取 memory 文件内容。

Local 模式：

设置 agents.defaults.memorySearch.provider = "local"。
提供 agents.defaults.memorySearch.local.modelPath（GGUF 或 hf: URI）。
可选：设置 agents.defaults.memorySearch.fallback = "none" 以避免远端 fallback。

memory tools 如何工作

memory_search 会对 MEMORY.md + memory/**/*.md 的 Markdown chunks 做语义搜索（目标约 400 token、80 token overlap）。它返回 snippet 文本（上限约 700 chars）、文件路径、行号范围、score、provider/model，以及是否从 local → remote embeddings fallback。不会返回整个文件 payload。
memory_get 读取一个特定的 memory Markdown 文件（workspace-relative），可选从某行开始读取 N 行。会拒绝 MEMORY.md / memory/ 之外的路径。
两个工具都只在 memorySearch.enabled 对该 agent 解析为 true 时启用。

会被索引的内容（以及何时索引）

文件类型：仅 Markdown（MEMORY.md、memory/**/*.md）。
索引存储：每个 agent 一份 SQLite，位于 ~/.openclaw/memory/<agentId>.sqlite（可通过 agents.defaults.memorySearch.store.path 配置，支持 {agentId} token）。
新鲜度：对 MEMORY.md + memory/ 的 watcher 会把索引标记为 dirty（debounce 1.5s）。sync 会在 session start、search、或按 interval 调度，并异步运行。session transcripts 使用 delta thresholds 触发后台 sync。
重建索引触发：索引会存储 embedding 的 provider/model + endpoint fingerprint + chunking params。其中任意项变化时，Moltbot 会自动 reset 并重建整个索引。

混合检索（BM25 + vector）

启用时，Moltbot 会组合：

向量相似度（语义匹配，措辞可不同）
BM25 关键词相关性（精确 token，例如 IDs、env vars、code symbols）

如果你的平台无法使用 full-text search，Moltbot 会回退为纯向量检索。

为什么要混合？

向量检索擅长“意思相同”：

“Mac Studio gateway host” vs “the machine running the gateway”
“debounce file updates” vs “avoid indexing on every write”

但对精确、高信号 token 可能较弱：

IDs（a828e60、b3b9895a…）
code symbols（memorySearch.query.hybrid）
错误字符串（“sqlite-vec unavailable”）

BM25（全文检索）则相反：对精确 token 很强，但对改写/同义表达较弱。混合检索是折中方案：同时利用两种检索信号，从而既适合自然语言查询，也适合“大海捞针”的精确查询。

我们如何合并结果（当前设计）

实现草图：

从两侧取候选集合：

Vector：按余弦相似度取 top maxResults * candidateMultiplier。
BM25：按 FTS5 BM25 rank 取 top maxResults * candidateMultiplier（越小越好）。

将 BM25 rank 转换为一个约 0..1 的分数：

textScore = 1 / (1 + max(0, bm25Rank))

按 chunk id 合并候选，并计算加权分数：

finalScore = vectorWeight * vectorScore + textWeight * textScore

备注：

在配置解析时会把 vectorWeight + textWeight 归一化到 1.0，因此 weight 的行为像百分比。
如果 embeddings 不可用（或 provider 返回了 zero-vector），我们仍会运行 BM25 并返回关键词匹配。
如果 FTS5 无法创建，则保留 vector-only（不硬失败）。

这不是“IR 理论最完美”的方案，但它足够简单、够快，并且通常能提升真实笔记的召回率/精度。如果未来想做得更复杂，常见方向是 Reciprocal Rank Fusion（RRF）或在混合前做分数归一化（min/max 或 z-score）。

配置：

json5

agents: {
  defaults: {
    memorySearch: {
      query: {
        hybrid: {
          enabled: true,
          vectorWeight: 0.7,
          textWeight: 0.3,
          candidateMultiplier: 4
        }
      }
    }
  }
}

Embedding cache

Moltbot 可以在 SQLite 中缓存 chunk embeddings，这样重建索引与频繁更新（尤其是 session transcripts）就不会对未变化文本重复做 embedding。

配置：

json5

agents: {
  defaults: {
    memorySearch: {
      cache: {
        enabled: true,
        maxEntries: 50000
      }
    }
  }
}

Session memory search（实验性）

你也可以选择性地索引 session transcripts，并通过 memory_search 暴露出来。该功能受实验性开关保护。

json5

agents: {
  defaults: {
    memorySearch: {
      experimental: { sessionMemory: true },
      sources: ["memory", "sessions"]
    }
  }
}

备注：

Session 索引是 opt-in（默认关闭）。
Session 更新会被 debounce，并在跨过 delta thresholds 后以异步方式做索引（best-effort）。
memory_search 从不阻塞等待索引完成；在后台 sync 结束前，结果可能略有滞后。
结果仍只包含 snippets；memory_get 仍只允许读取 memory files。
Session 索引按 agent 隔离（只索引该 agent 的 session logs）。
Session logs 存在磁盘上（~/.openclaw/agents/<agentId>/sessions/*.jsonl）。任何具备文件系统访问权限的进程/用户都能读取它们，因此应把“磁盘访问”视为信任边界。需要更严格隔离时，请把 agents 运行在不同 OS 用户或不同主机上。

Delta thresholds（默认值示例）：

json5

agents: {
  defaults: {
    memorySearch: {
      sync: {
        sessions: {
          deltaBytes: 100000,   // ~100 KB
          deltaMessages: 50     // JSONL lines
        }
      }
    }
  }
}

SQLite 向量加速（sqlite-vec）

当 sqlite-vec 扩展可用时，Moltbot 会把 embeddings 存在 SQLite 虚拟表（vec0）里，并在数据库中执行向量距离查询。这样无需把每个 embedding 加载进 JS，也能保持搜索速度。

配置（可选）：

json5

agents: {
  defaults: {
    memorySearch: {
      store: {
        vector: {
          enabled: true,
          extensionPath: "/path/to/sqlite-vec"
        }
      }
    }
  }
}

备注：

enabled 默认 true；禁用时会回退为在进程内对已存 embeddings 做余弦相似度。
如果 sqlite-vec 缺失或加载失败，Moltbot 会记录错误并继续使用 JS fallback（无 vector table）。
extensionPath 可覆盖内置 sqlite-vec 路径（适用于自定义构建或非标准安装路径）。

Local embedding 自动下载

默认本地 embedding 模型：hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf（约 0.6 GB）。
当 memorySearch.provider = "local" 时，node-llama-cpp 会解析 modelPath；若 GGUF 缺失，则会自动下载到 cache（或 local.modelCacheDir 指定目录），然后加载。下载支持断点续传。
Native 构建要求：运行 pnpm approve-builds，选择 node-llama-cpp，然后执行 pnpm rebuild node-llama-cpp。
Fallback：如果本地配置失败且 memorySearch.fallback = "openai"，我们会自动切换到远端 embeddings（默认 openai/text-embedding-3-small，除非覆盖），并记录原因。

自定义 OpenAI 兼容端点示例

json5

agents: {
  defaults: {
    memorySearch: {
      provider: "openai",
      model: "text-embedding-3-small",
      remote: {
        baseUrl: "https://api.example.com/v1/",
        apiKey: "YOUR_REMOTE_API_KEY",
        headers: {
          "X-Organization": "org-id",
          "X-Project": "project-id"
        }
      }
    }
  }
}

备注：

remote.* 优先于 models.providers.openai.*。
remote.headers 会与 OpenAI headers 合并；key 冲突时以 remote 为准。不设置 remote.headers 则使用 OpenAI 默认值。

Memory ​

Memory files（Markdown） ​

何时写入 memory ​

自动 memory flush（compaction 前的 ping） ​

向量化 memory 搜索（Vector memory search） ​

Gemini embeddings（原生） ​

memory tools 如何工作 ​

会被索引的内容（以及何时索引） ​

混合检索（BM25 + vector） ​

为什么要混合？ ​

我们如何合并结果（当前设计） ​

Embedding cache ​

Session memory search（实验性） ​

SQLite 向量加速（sqlite-vec） ​

Local embedding 自动下载 ​

自定义 OpenAI 兼容端点示例 ​

Memory

Memory files（Markdown）

何时写入 memory

自动 memory flush（compaction 前的 ping）

向量化 memory 搜索（Vector memory search）

Gemini embeddings（原生）

memory tools 如何工作

会被索引的内容（以及何时索引）

混合检索（BM25 + vector）

为什么要混合？

我们如何合并结果（当前设计）

Embedding cache

Session memory search（实验性）

SQLite 向量加速（sqlite-vec）

Local embedding 自动下载

自定义 OpenAI 兼容端点示例