记忆 (Memory)

Clawdbot 的记忆是智能体工作区中的纯 Markdown 文件。这些文件是事实的唯一来源；模型只能“记住”写入磁盘的内容。

记忆搜索工具由活动的记忆插件提供（默认：memory-core）。使用 plugins.slots.memory = "none" 禁用记忆插件。

记忆文件 (Markdown)

默认的工作区布局使用两个记忆层：

memory/YYYY-MM-DD.md
- 每日日志（仅限追加）。
- 在会话开始时读取今天 + 昨天的内容。
MEMORY.md（可选）
- 精选的长期记忆。
- 仅在主私聊会话中加载（绝不在群组上下文中加载）。

这些文件位于工作区下（agents.defaults.workspace，默认为 ~/clawd）。有关完整布局，请参阅智能体工作区 (Agent workspace)。

何时写入记忆

决策、偏好和持久的事实应放入 MEMORY.md。
日常笔记和运行中的上下文应放入 memory/YYYY-MM-DD.md。
如果有人说“记住这一点”，请将其写下来（不要仅保留在 RAM 中）。
这个领域仍在不断发展。提醒模型存储记忆会有所帮助；它会知道该怎么做。
如果您想让某些内容持久化，请要求机器人将其写入记忆中。

自动记忆刷新（预压缩提醒）

当会话接近自动压缩时，Clawdbot 会触发一个静默的、代理性的轮次，提醒模型在上下文被压缩之前写入持久记忆。默认提示明确表示模型可以回复，但通常 NO_REPLY 是正确的响应，这样用户永远不会看到这个轮次。

这由 agents.defaults.compaction.memoryFlush 控制：

{
  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)：当会话令牌估计值超过 contextWindow - reserveTokensFloor - softThresholdTokens 时触发刷新。
默认静默：提示词中包含 NO_REPLY，因此不会向用户交付任何内容。
两个提示词：一个用户提示词加上一个系统提示词追加提醒。
每个压缩周期一次刷新（在 sessions.json 中跟踪）。
工作区必须可写：如果会话以 workspaceAccess: "ro" 或 "none" 的沙箱模式运行，则跳过刷新。

有关完整的压缩生命周期，请参阅会话管理 + 压缩 (Session management + compaction)。

向量记忆搜索

Clawdbot 可以对 MEMORY.md 和 memory/*.md 构建小型向量索引，以便语义查询可以找到相关的笔记，即使措辞不同。

默认值：

默认启用。
监听记忆文件的更改（防抖处理）。
默认使用远程嵌入 (Embeddings)。如果未设置 memorySearch.provider，Clawdbot 会自动选择：
1. 如果配置了 memorySearch.local.modelPath 且文件存在，则使用 local。
2. 如果可以解析出 OpenAI 密钥，则使用 openai。
3. 如果可以解析出 Gemini 密钥，则使用 gemini。
4. 否则，记忆搜索保持禁用状态，直到配置完成。
本地模式使用 node-llama-cpp，可能需要运行 pnpm approve-builds。
使用 sqlite-vec（可用时）在 SQLite 内部加速向量搜索。

远程嵌入需要嵌入提供商的 API 密钥。Clawdbot 从身份认证配置文件、models.providers.*.apiKey 或环境变量中解析密钥。ChatGPT OAuth 仅涵盖聊天/补全，不满足记忆搜索的嵌入需求。对于 Gemini，请使用 GEMINI_API_KEY 或 models.providers.google.apiKey。使用自定义的 OpenAI 兼容端点时，请设置 memorySearch.remote.apiKey（以及可选的 memorySearch.remote.headers）。

Gemini 嵌入（原生）

将提供商设置为 `gemini" 以直接使用 Gemini 嵌入 API：

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

注意：

remote.baseUrl 是可选的（默认为 Gemini API 基础 URL）。
remote.headers 允许您根据需要添加额外的标头。
默认模型：gemini-embedding-001。

如果您想使用自定义的 OpenAI 兼容端点（如 OpenRouter、vLLM 或代理），可以将 remote 配置与 OpenAI 提供商配合使用：

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 密钥，请使用 memorySearch.provider = "local" 或设置 memorySearch.fallback = "none"。

回退机制 (Fallbacks)：

memorySearch.fallback 可以是 openai、gemini、local 或 none。
仅当主嵌入提供商失败时才使用回退提供商。

批量索引（OpenAI + Gemini）：

默认对 OpenAI 和 Gemini 嵌入启用。设置 agents.defaults.memorySearch.remote.batch.enabled = false 以禁用。
默认行为会等待批处理完成；如果需要，请调整 remote.batch.wait、remote.batch.pollIntervalMs 和 remote.batch.timeoutMinutes。
设置 remote.batch.concurrency 以控制我们并行提交的批处理作业数量（默认：2）。
当 memorySearch.provider = "openai" 或 "gemini" 时适用批处理模式，并使用相应的 API 密钥。
Gemini 批处理作业使用异步嵌入批处理端点，并需要 Gemini Batch API 可用。

为什么 OpenAI 批处理既快又便宜：

对于大型回填，OpenAI 通常是我们支持的最快选项，因为我们可以在单个批处理作业中提交许多嵌入请求，并让 OpenAI 异步处理它们。
OpenAI 为批处理 API 工作负载提供折扣定价，因此大型索引运行通常比同步发送相同请求更便宜。
有关详细信息，请参阅 OpenAI 批处理 API 文档和定价：
- https://platform.openai.com/docs/api-reference/batch
- https://platform.openai.com/pricing

配置示例：

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

工具：

memory_search — 返回包含文件和行范围的代码片段。
memory_get — 通过路径读取记忆文件内容。

本地模式：

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

记忆工具的工作原理

memory_search 对来自 MEMORY.md + memory/**/*.md 的 Markdown 块（目标约 400 令牌，80 令牌重叠）进行语义搜索。它返回片段文本（限制约 700 字符）、文件路径、行范围、分数、提供商/模型，以及我们是否从本地回退到远程嵌入。不返回完整的文件负载。
memory_get 读取特定的记忆 Markdown 文件（相对于工作区），可选起始行和读取行数。拒绝 MEMORY.md / memory/ 之外的路径。
仅当代理的 memorySearch.enabled 解析为 true 时，这两个工具才会被启用。

索引什么（以及何时索引）

文件类型：仅限 Markdown（MEMORY.md, memory/**/*.md）。
索引存储：每个代理的 SQLite 位于 ~/.clawdbot/memory/<agentId>.sqlite（可通过 agents.defaults.memorySearch.store.path 配置，支持 {agentId} 令牌）。
新鲜度：MEMORY.md + memory/ 上的监听器会将索引标记为脏（防抖 1.5 秒）。同步计划在会话开始、搜索或按间隔进行，并异步运行。会话转录使用增量阈值触发后台同步。
重新索引触发器：索引存储了嵌入提供商/模型 + 端点指纹 + 分块参数。如果其中任何一个发生更改，Clawdbot 会自动重置并重新索引整个存储。

混合搜索 (BM25 + 向量)

启用后，Clawdbot 结合了：

向量相似度（语义匹配，措辞可以不同）
BM25 关键词相关性（精确令牌，如 ID、环境变量、代码符号）

如果您的平台上无法使用全文搜索，Clawdbot 将回退到仅向量搜索。

为什么使用混合搜索？

向量搜索擅长“这表达了同样的意思”：

“Mac Studio 网关主机” vs “运行网关的机器”
“防抖文件更新” vs “避免在每次写入时索引”

但在精确、高信号令牌方面可能较弱：

ID (a828e60, b3b9895a…)
代码符号 (memorySearch.query.hybrid)
错误字符串 (“sqlite-vec unavailable”)

BM25（全文搜索）则相反：擅长精确令牌，不擅长释义。混合搜索是务实的折中方案：同时使用两种检索信号，从而在“自然语言”查询和“大海捞针”查询中都能获得良好结果。

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

实现草图：

从两边检索候选池：

向量：按余弦相似度排名前 maxResults * candidateMultiplier 的结果。
BM25：按 FTS5 BM25 排名（越低越好）排名前 maxResults * candidateMultiplier 的结果。

将 BM25 排名转换为 0..1 左右的分数：

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

按块 ID 合并候选结果并计算加权分数：

finalScore = vectorWeight * vectorScore + textWeight * textScore

注意：

vectorWeight + textWeight 在配置解析中被归一化为 1.0，因此权重表现为百分比。
如果嵌入不可用（或提供商返回零向量），我们仍会运行 BM25 并返回关键词匹配结果。
如果无法创建 FTS5，我们保留仅向量搜索（不会发生硬故障）。

这虽然不是“信息检索理论上的完美”，但它简单、快速，且往往能提高真实笔记的召回率/精确度。如果我们以后想做得更复杂，常见的后续步骤是倒数排名融合 (RRF) 或在混合前进行分数归一化（最小/最大或 z-score）。

配置：

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

嵌入缓存

Clawdbot 可以在 SQLite 中缓存块嵌入，这样重新索引和频繁更新（特别是会话转录）就不会重新嵌入未更改的文本。

配置：

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

会话记忆搜索（实验性）

您可以选择索引会话转录并通过 memory_search 呈现它们。这由一个实验性标志控制。

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

注意：

会话索引是选择性加入 (Opt-in) 的（默认关闭）。
会话更新会进行防抖处理，并在超过增量阈值后异步索引（尽力而为）。
memory_search 绝不会在索引时阻塞；结果可能在后台同步完成前略显陈旧。
结果仍仅包含代码片段；memory_get 仍仅限于记忆文件。
会话索引在每个代理之间是隔离的（仅索引该代理的会话日志）。
会话日志存储在磁盘上 (~/.clawdbot/agents/<agentId>/sessions/*.jsonl)。任何具有文件系统访问权限的进程/用户都可以读取它们，因此请将磁盘访问视为信任边界。为了更严格的隔离，请在不同的操作系统用户或主机下运行代理。

增量阈值（显示默认值）：

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

SQLite 向量加速 (sqlite-vec)

当 sqlite-vec 扩展可用时，Clawdbot 将嵌入存储在 SQLite 虚表 (vec0) 中，并在数据库中执行向量距离查询。这可以保持搜索速度，而无需将每个嵌入都加载到 JS 中。

配置（可选）：

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

注意：

enabled 默认为 true；禁用时，搜索将回退到对存储嵌入的进程内余弦相似度计算。
如果 sqlite-vec 扩展缺失或加载失败，Clawdbot 会记录错误并继续使用 JS 回退（不使用向量表）。
extensionPath 覆盖绑定的 sqlite-vec 路径（适用于自定义构建或非标准安装位置）。

本地嵌入自动下载

默认本地嵌入模型：hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf (~0.6 GB)。
当 memorySearch.provider = "local" 时，node-llama-cpp 会解析 modelPath；如果 GGUF 缺失，它会自动下载到缓存（或 local.modelCacheDir，如果已设置），然后加载。下载会在重试时恢复。
原生构建要求：运行 pnpm approve-builds，选择 node-llama-cpp，然后运行 pnpm rebuild node-llama-cpp。
回退机制：如果本地设置失败且 memorySearch.fallback = "openai"，我们会自动切换到远程嵌入（除非覆盖，否则为 openai/text-embedding-3-small）并记录原因。

自定义 OpenAI 兼容端点示例

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 标头合并；键冲突时远程配置胜出。省略 remote.headers 以使用 OpenAI 默认值。

记忆 (Memory)

记忆文件 (Markdown)​

何时写入记忆​

自动记忆刷新（预压缩提醒）​

向量记忆搜索​

Gemini 嵌入（原生）​

记忆工具的工作原理​

索引什么（以及何时索引）​

混合搜索 (BM25 + 向量)​

为什么使用混合搜索？​

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

嵌入缓存​

会话记忆搜索（实验性）​

SQLite 向量加速 (sqlite-vec)​

本地嵌入自动下载​

自定义 OpenAI 兼容端点示例​