chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
c82db49060
commit
12cac6125c
580
docs/zh-CN/concepts/active-memory.md
Normal file
580
docs/zh-CN/concepts/active-memory.md
Normal file
@ -0,0 +1,580 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想了解活跃记忆的用途
|
||||
- 你想为一个对话式智能体启用活跃记忆
|
||||
- 你想调整活跃记忆的行为，而不在所有地方都启用它
|
||||
summary: 一个由插件拥有的、用于阻塞式记忆的子智能体，会将相关记忆注入交互式聊天会话中
|
||||
title: 活跃记忆
|
||||
x-i18n:
|
||||
generated_at: "2026-04-09T16:29:19Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 6a51437df4ae4d9d57764601dfcfcdadb269e2895bf49dc82b9f496c1b3cb341
|
||||
source_path: concepts/active-memory.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 活跃记忆
|
||||
|
||||
活跃记忆是一个可选的、由插件拥有的阻塞式记忆子智能体，会在符合条件的对话会话中于主回复之前运行。
|
||||
|
||||
之所以存在它，是因为大多数记忆系统虽然能力很强，但都是被动响应式的。它们要么依赖主智能体来决定何时搜索记忆，要么依赖用户说出像“记住这个”或“搜索记忆”这样的话。等到了那时，原本可以让回复显得自然的记忆介入时机，往往已经过去了。
|
||||
|
||||
活跃记忆为系统提供了一次受限的机会，让它在生成主回复之前先呈现相关记忆。
|
||||
|
||||
## 将这段内容粘贴到你的智能体中
|
||||
|
||||
如果你想让你的智能体通过一个自包含、默认安全的配置来启用活跃记忆，请将以下内容粘贴进去：
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"active-memory": {
|
||||
enabled: true,
|
||||
config: {
|
||||
enabled: true,
|
||||
agents: ["main"],
|
||||
allowedChatTypes: ["direct"],
|
||||
modelFallbackPolicy: "default-remote",
|
||||
queryMode: "recent",
|
||||
promptStyle: "balanced",
|
||||
timeoutMs: 15000,
|
||||
maxSummaryChars: 220,
|
||||
persistTranscripts: false,
|
||||
logging: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
这会为 `main` 智能体启用该插件，默认将其限制在私信风格的会话中，优先让它继承当前会话模型，并且当没有显式模型或继承模型可用时，仍允许使用内置远程回退。
|
||||
|
||||
之后，重启 Gateway 网关：
|
||||
|
||||
```bash
|
||||
node scripts/run-node.mjs gateway --profile dev
|
||||
```
|
||||
|
||||
如果你想在对话中实时检查它：
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
```
|
||||
|
||||
## 启用活跃记忆
|
||||
|
||||
最安全的配置方式是：
|
||||
|
||||
1. 启用插件
|
||||
2. 指定一个对话式智能体
|
||||
3. 仅在调优期间保持日志开启
|
||||
|
||||
先在 `openclaw.json` 中加入以下内容：
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"active-memory": {
|
||||
enabled: true,
|
||||
config: {
|
||||
agents: ["main"],
|
||||
allowedChatTypes: ["direct"],
|
||||
modelFallbackPolicy: "default-remote",
|
||||
queryMode: "recent",
|
||||
promptStyle: "balanced",
|
||||
timeoutMs: 15000,
|
||||
maxSummaryChars: 220,
|
||||
persistTranscripts: false,
|
||||
logging: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
然后重启 Gateway 网关：
|
||||
|
||||
```bash
|
||||
node scripts/run-node.mjs gateway --profile dev
|
||||
```
|
||||
|
||||
这意味着：
|
||||
|
||||
- `plugins.entries.active-memory.enabled: true` 会启用该插件
|
||||
- `config.agents: ["main"]` 只让 `main` 智能体使用活跃记忆
|
||||
- `config.allowedChatTypes: ["direct"]` 默认只在私信风格的会话中启用活跃记忆
|
||||
- 如果未设置 `config.model`，活跃记忆会优先继承当前会话模型
|
||||
- `config.modelFallbackPolicy: "default-remote"` 会在没有显式模型或继承模型可用时，保留内置远程回退这一默认行为
|
||||
- `config.promptStyle: "balanced"` 会为 `recent` 模式使用默认的通用提示风格
|
||||
- 活跃记忆仍然只会在符合条件的交互式持久聊天会话中运行
|
||||
|
||||
## 如何查看它
|
||||
|
||||
活跃记忆会为模型注入隐藏的系统上下文。它不会向客户端暴露原始的 `<active_memory_plugin>...</active_memory_plugin>` 标签。
|
||||
|
||||
## 会话开关
|
||||
|
||||
如果你想在不编辑配置的情况下，为当前聊天会话暂停或恢复活跃记忆，请使用插件命令：
|
||||
|
||||
```text
|
||||
/active-memory status
|
||||
/active-memory off
|
||||
/active-memory on
|
||||
```
|
||||
|
||||
这是会话级别的。它不会更改
|
||||
`plugins.entries.active-memory.enabled`、智能体目标设置或其他全局配置。
|
||||
|
||||
如果你希望这个命令写入配置，并为所有会话暂停或恢复活跃记忆，请使用显式的全局形式：
|
||||
|
||||
```text
|
||||
/active-memory status --global
|
||||
/active-memory off --global
|
||||
/active-memory on --global
|
||||
```
|
||||
|
||||
全局形式会写入 `plugins.entries.active-memory.config.enabled`。它会保持
|
||||
`plugins.entries.active-memory.enabled` 为开启状态，以便该命令之后仍可用于重新启用活跃记忆。
|
||||
|
||||
如果你想查看活跃记忆在实时会话中的具体行为，请为该会话开启详细模式：
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
```
|
||||
|
||||
启用详细模式后，OpenClaw 可以显示：
|
||||
|
||||
- 一行活跃记忆状态，例如 `Active Memory: ok 842ms recent 34 chars`
|
||||
- 一条可读的调试摘要，例如 `Active Memory Debug: Lemon pepper wings with blue cheese.`
|
||||
|
||||
这些行源自同一次活跃记忆过程，该过程也会为隐藏系统上下文提供内容，但这里是面向人类格式化后的结果，而不是暴露原始提示标记。
|
||||
|
||||
默认情况下，这个阻塞式记忆子智能体的转录是临时的，并会在运行完成后删除。
|
||||
|
||||
示例流程：
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
what wings should i order?
|
||||
```
|
||||
|
||||
预期可见回复形式：
|
||||
|
||||
```text
|
||||
...normal assistant reply...
|
||||
|
||||
🧩 Active Memory: ok 842ms recent 34 chars
|
||||
🔎 Active Memory Debug: Lemon pepper wings with blue cheese.
|
||||
```
|
||||
|
||||
## 它何时运行
|
||||
|
||||
活跃记忆使用两个门槛条件：
|
||||
|
||||
1. **配置选择启用**
|
||||
必须启用该插件，且当前智能体 id 必须出现在
|
||||
`plugins.entries.active-memory.config.agents` 中。
|
||||
2. **严格的运行时资格**
|
||||
即使已启用并已指定目标，活跃记忆也只会在符合条件的交互式持久聊天会话中运行。
|
||||
|
||||
实际规则是：
|
||||
|
||||
```text
|
||||
plugin enabled
|
||||
+
|
||||
agent id targeted
|
||||
+
|
||||
allowed chat type
|
||||
+
|
||||
eligible interactive persistent chat session
|
||||
=
|
||||
active memory runs
|
||||
```
|
||||
|
||||
如果其中任一条件失败，活跃记忆都不会运行。
|
||||
|
||||
## 会话类型
|
||||
|
||||
`config.allowedChatTypes` 控制哪些类型的对话可以运行活跃记忆。
|
||||
|
||||
默认值是：
|
||||
|
||||
```json5
|
||||
allowedChatTypes: ["direct"]
|
||||
```
|
||||
|
||||
这意味着，默认情况下活跃记忆会在私信风格的会话中运行，但不会在群组或渠道会话中运行，除非你显式将它们加入。
|
||||
|
||||
示例：
|
||||
|
||||
```json5
|
||||
allowedChatTypes: ["direct"]
|
||||
```
|
||||
|
||||
```json5
|
||||
allowedChatTypes: ["direct", "group"]
|
||||
```
|
||||
|
||||
```json5
|
||||
allowedChatTypes: ["direct", "group", "channel"]
|
||||
```
|
||||
|
||||
## 它在哪些地方运行
|
||||
|
||||
活跃记忆是一项对话增强功能，而不是一个平台范围内的推理功能。
|
||||
|
||||
| 界面 | 会运行活跃记忆吗？ |
|
||||
| ------------------------------------------------------------------- | ------------------------------------------------------- |
|
||||
| Control UI / web chat 持久会话 | 是，前提是插件已启用且智能体已被指定为目标 |
|
||||
| 同一持久聊天路径上的其他交互式渠道会话 | 是，前提是插件已启用且智能体已被指定为目标 |
|
||||
| 无头单次运行 | 否 |
|
||||
| 心跳/后台运行 | 否 |
|
||||
| 通用内部 `agent-command` 路径 | 否 |
|
||||
| 子智能体/内部辅助执行 | 否 |
|
||||
|
||||
## 为什么使用它
|
||||
|
||||
在以下情况下，请使用活跃记忆：
|
||||
|
||||
- 会话是持久的且面向用户
|
||||
- 智能体拥有有意义的长期记忆可供搜索
|
||||
- 连续性与个性化比纯粹的提示确定性更重要
|
||||
|
||||
它尤其适合：
|
||||
|
||||
- 稳定偏好
|
||||
- 重复习惯
|
||||
- 应该自然浮现的长期用户上下文
|
||||
|
||||
它不适合：
|
||||
|
||||
- 自动化
|
||||
- 内部工作器
|
||||
- 单次 API 任务
|
||||
- 那些隐藏式个性化会让人感到意外的场景
|
||||
|
||||
## 它如何工作
|
||||
|
||||
运行时形态如下：
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
U["User Message"] --> Q["Build Memory Query"]
|
||||
Q --> R["Active Memory Blocking Memory Sub-Agent"]
|
||||
R -->|NONE or empty| M["Main Reply"]
|
||||
R -->|relevant summary| I["Append Hidden active_memory_plugin System Context"]
|
||||
I --> M["Main Reply"]
|
||||
```
|
||||
|
||||
这个阻塞式记忆子智能体只能使用：
|
||||
|
||||
- `memory_search`
|
||||
- `memory_get`
|
||||
|
||||
如果连接较弱，它应返回 `NONE`。
|
||||
|
||||
## 查询模式
|
||||
|
||||
`config.queryMode` 控制阻塞式记忆子智能体能看到多少对话内容。
|
||||
|
||||
## 提示风格
|
||||
|
||||
`config.promptStyle` 控制阻塞式记忆子智能体在决定是否返回记忆时有多积极或多严格。
|
||||
|
||||
可用风格：
|
||||
|
||||
- `balanced`：适用于 `recent` 模式的通用默认值
|
||||
- `strict`：最不积极；适合你希望尽量减少附近上下文外溢影响时使用
|
||||
- `contextual`：最有利于连续性；适合对话历史应当更重要时使用
|
||||
- `recall-heavy`：即使匹配较弱但仍合理时，也更愿意呈现记忆
|
||||
- `precision-heavy`：除非匹配非常明显，否则会强烈偏向返回 `NONE`
|
||||
- `preference-only`：针对收藏、习惯、例行模式、口味和重复性个人事实进行优化
|
||||
|
||||
当未设置 `config.promptStyle` 时，默认映射为：
|
||||
|
||||
```text
|
||||
message -> strict
|
||||
recent -> balanced
|
||||
full -> contextual
|
||||
```
|
||||
|
||||
如果你显式设置了 `config.promptStyle`，则以该覆盖值为准。
|
||||
|
||||
示例：
|
||||
|
||||
```json5
|
||||
promptStyle: "preference-only"
|
||||
```
|
||||
|
||||
## 模型回退策略
|
||||
|
||||
如果未设置 `config.model`，活跃记忆会按以下顺序尝试解析模型：
|
||||
|
||||
```text
|
||||
explicit plugin model
|
||||
-> current session model
|
||||
-> agent primary model
|
||||
-> optional built-in remote fallback
|
||||
```
|
||||
|
||||
`config.modelFallbackPolicy` 控制最后这一步。
|
||||
|
||||
默认值：
|
||||
|
||||
```json5
|
||||
modelFallbackPolicy: "default-remote"
|
||||
```
|
||||
|
||||
另一个选项：
|
||||
|
||||
```json5
|
||||
modelFallbackPolicy: "resolved-only"
|
||||
```
|
||||
|
||||
如果你希望在没有显式模型或继承模型可用时，活跃记忆跳过召回，而不是回退到内置远程默认值，请使用 `resolved-only`。
|
||||
|
||||
## 高级逃生舱选项
|
||||
|
||||
这些选项有意不属于推荐配置的一部分。
|
||||
|
||||
`config.thinking` 可以覆盖阻塞式记忆子智能体的思考级别：
|
||||
|
||||
```json5
|
||||
thinking: "medium"
|
||||
```
|
||||
|
||||
默认值：
|
||||
|
||||
```json5
|
||||
thinking: "off"
|
||||
```
|
||||
|
||||
默认不要启用它。活跃记忆运行在回复路径上，因此额外的思考时间会直接增加用户可感知的延迟。
|
||||
|
||||
`config.promptAppend` 会在默认活跃记忆提示之后、对话上下文之前，附加额外的操作员指令：
|
||||
|
||||
```json5
|
||||
promptAppend: "Prefer stable long-term preferences over one-off events."
|
||||
```
|
||||
|
||||
`config.promptOverride` 会替换默认的活跃记忆提示。OpenClaw 仍会在其后附加对话上下文：
|
||||
|
||||
```json5
|
||||
promptOverride: "You are a memory search agent. Return NONE or one compact user fact."
|
||||
```
|
||||
|
||||
除非你是在有意测试不同的召回契约，否则不建议自定义提示。默认提示已针对返回 `NONE` 或适用于主模型的紧凑用户事实上下文进行了调优。
|
||||
|
||||
### `message`
|
||||
|
||||
只发送最新一条用户消息。
|
||||
|
||||
```text
|
||||
Latest user message only
|
||||
```
|
||||
|
||||
适用场景：
|
||||
|
||||
- 你想要最快的行为
|
||||
- 你希望对稳定偏好召回有最强的偏向
|
||||
- 后续轮次不需要对话上下文
|
||||
|
||||
推荐超时：
|
||||
|
||||
- 从 `3000` 到 `5000` ms 左右开始
|
||||
|
||||
### `recent`
|
||||
|
||||
发送最新一条用户消息以及少量最近的对话尾部内容。
|
||||
|
||||
```text
|
||||
Recent conversation tail:
|
||||
user: ...
|
||||
assistant: ...
|
||||
user: ...
|
||||
|
||||
Latest user message:
|
||||
...
|
||||
```
|
||||
|
||||
适用场景：
|
||||
|
||||
- 你希望在速度和对话语境之间取得更好的平衡
|
||||
- 后续问题通常依赖最近几轮对话
|
||||
|
||||
推荐超时：
|
||||
|
||||
- 从 `15000` ms 左右开始
|
||||
|
||||
### `full`
|
||||
|
||||
将完整对话发送给阻塞式记忆子智能体。
|
||||
|
||||
```text
|
||||
Full conversation context:
|
||||
user: ...
|
||||
assistant: ...
|
||||
user: ...
|
||||
...
|
||||
```
|
||||
|
||||
适用场景：
|
||||
|
||||
- 你更看重最强的召回质量，而不是延迟
|
||||
- 对话中在线程较早位置包含重要铺垫信息
|
||||
|
||||
推荐超时：
|
||||
|
||||
- 与 `message` 或 `recent` 相比，应显著增加
|
||||
- 根据线程大小，从 `15000` ms 或更高开始
|
||||
|
||||
一般来说，超时时间应随上下文大小增加而增加：
|
||||
|
||||
```text
|
||||
message < recent < full
|
||||
```
|
||||
|
||||
## 转录持久化
|
||||
|
||||
活跃记忆阻塞式记忆子智能体运行时，会在该阻塞式记忆子智能体调用期间创建一个真实的 `session.jsonl` 转录。
|
||||
|
||||
默认情况下，该转录是临时的：
|
||||
|
||||
- 它会被写入临时目录
|
||||
- 它仅用于阻塞式记忆子智能体运行
|
||||
- 运行结束后会立即删除
|
||||
|
||||
如果你想出于调试或检查目的，将这些阻塞式记忆子智能体转录保留在磁盘上，请显式启用持久化：
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"active-memory": {
|
||||
enabled: true,
|
||||
config: {
|
||||
agents: ["main"],
|
||||
persistTranscripts: true,
|
||||
transcriptDir: "active-memory",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
启用后，活跃记忆会将转录存储在目标智能体会话文件夹下的单独目录中，而不是主用户对话转录路径中。
|
||||
|
||||
默认布局在概念上是：
|
||||
|
||||
```text
|
||||
agents/<agent>/sessions/active-memory/<blocking-memory-sub-agent-session-id>.jsonl
|
||||
```
|
||||
|
||||
你可以使用 `config.transcriptDir` 更改这个相对子目录。
|
||||
|
||||
请谨慎使用：
|
||||
|
||||
- 在繁忙会话中，阻塞式记忆子智能体转录可能会快速累积
|
||||
- `full` 查询模式可能会复制大量对话上下文
|
||||
- 这些转录包含隐藏提示上下文和已召回的记忆
|
||||
|
||||
## 配置
|
||||
|
||||
所有活跃记忆配置都位于：
|
||||
|
||||
```text
|
||||
plugins.entries.active-memory
|
||||
```
|
||||
|
||||
最重要的字段有：
|
||||
|
||||
| 键名 | 类型 | 含义 |
|
||||
| --------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
||||
| `enabled` | `boolean` | 启用插件本身 |
|
||||
| `config.agents` | `string[]` | 可使用活跃记忆的智能体 id |
|
||||
| `config.model` | `string` | 可选的阻塞式记忆子智能体模型引用；未设置时，活跃记忆会使用当前会话模型 |
|
||||
| `config.queryMode` | `"message" \| "recent" \| "full"` | 控制阻塞式记忆子智能体能看到多少对话内容 |
|
||||
| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | 控制阻塞式记忆子智能体在决定是否返回记忆时有多积极或多严格 |
|
||||
| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | 阻塞式记忆子智能体的高级思考覆盖设置；默认值为 `off` 以提高速度 |
|
||||
| `config.promptOverride` | `string` | 高级完整提示替换；不建议正常使用 |
|
||||
| `config.promptAppend` | `string` | 附加到默认或覆盖提示后的高级额外指令 |
|
||||
| `config.timeoutMs` | `number` | 阻塞式记忆子智能体的硬超时时间 |
|
||||
| `config.maxSummaryChars` | `number` | 活跃记忆摘要允许的最大总字符数 |
|
||||
| `config.logging` | `boolean` | 在调优期间输出活跃记忆日志 |
|
||||
| `config.persistTranscripts` | `boolean` | 将阻塞式记忆子智能体转录保留在磁盘上，而不是删除临时文件 |
|
||||
| `config.transcriptDir` | `string` | 智能体会话文件夹下的相对阻塞式记忆子智能体转录目录 |
|
||||
|
||||
有用的调优字段：
|
||||
|
||||
| 键名 | 类型 | 含义 |
|
||||
| ----------------------------- | -------- | ------------------------------------------------------------- |
|
||||
| `config.maxSummaryChars` | `number` | 活跃记忆摘要允许的最大总字符数 |
|
||||
| `config.recentUserTurns` | `number` | 当 `queryMode` 为 `recent` 时要包含的先前用户轮次数 |
|
||||
| `config.recentAssistantTurns` | `number` | 当 `queryMode` 为 `recent` 时要包含的先前助手轮次数 |
|
||||
| `config.recentUserChars` | `number` | 每个最近用户轮次的最大字符数 |
|
||||
| `config.recentAssistantChars` | `number` | 每个最近助手轮次的最大字符数 |
|
||||
| `config.cacheTtlMs` | `number` | 对重复且相同查询的缓存复用时间 |
|
||||
|
||||
## 推荐设置
|
||||
|
||||
从 `recent` 开始。
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"active-memory": {
|
||||
enabled: true,
|
||||
config: {
|
||||
agents: ["main"],
|
||||
queryMode: "recent",
|
||||
promptStyle: "balanced",
|
||||
timeoutMs: 15000,
|
||||
maxSummaryChars: 220,
|
||||
logging: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
如果你想在调优时检查实时行为，请在会话中使用 `/verbose on`，而不要寻找单独的活跃记忆调试命令。
|
||||
|
||||
然后再转向：
|
||||
|
||||
- 如果你想降低延迟，使用 `message`
|
||||
- 如果你认为额外上下文值得更慢的阻塞式记忆子智能体，则使用 `full`
|
||||
|
||||
## 调试
|
||||
|
||||
如果活跃记忆没有出现在你预期的位置：
|
||||
|
||||
1. 确认已在 `plugins.entries.active-memory.enabled` 下启用该插件。
|
||||
2. 确认当前智能体 id 已列在 `config.agents` 中。
|
||||
3. 确认你是在通过交互式持久聊天会话进行测试。
|
||||
4. 打开 `config.logging: true` 并查看 Gateway 网关日志。
|
||||
5. 使用 `openclaw memory status --deep` 验证记忆搜索本身是否正常工作。
|
||||
|
||||
如果记忆命中过于嘈杂，请收紧：
|
||||
|
||||
- `maxSummaryChars`
|
||||
|
||||
如果活跃记忆太慢：
|
||||
|
||||
- 降低 `queryMode`
|
||||
- 降低 `timeoutMs`
|
||||
- 减少最近轮次数
|
||||
- 降低每轮字符上限
|
||||
|
||||
## 相关页面
|
||||
|
||||
- [记忆搜索](/zh-CN/concepts/memory-search)
|
||||
- [记忆配置参考](/zh-CN/reference/memory-config)
|
||||
- [插件 SDK 设置](/zh-CN/plugins/sdk-setup)
|
||||
@ -1,26 +1,26 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想了解 `memory_search` 的工作方式
|
||||
- 你想了解 `memory_search` 的工作原理
|
||||
- 你想选择一个嵌入提供商
|
||||
- 你想调整搜索质量
|
||||
summary: Memory 搜索如何使用嵌入和混合检索查找相关笔记
|
||||
title: Memory 搜索
|
||||
- 你想调优搜索质量
|
||||
summary: 内存搜索如何使用嵌入和混合检索来查找相关笔记
|
||||
title: 内存搜索
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T00:33:17Z"
|
||||
generated_at: "2026-04-09T16:29:12Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: b6541cd702bff41f9a468dad75ea438b70c44db7c65a4b793cbacaf9e583c7e9
|
||||
source_hash: ca0237f4f1ee69dcbfb12e6e9527a53e368c0bf9b429e506831d4af2f3a3ac6f
|
||||
source_path: concepts/memory-search.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Memory 搜索
|
||||
# 内存搜索
|
||||
|
||||
`memory_search` 可以从你的 memory 文件中找到相关笔记，即使措辞与原始文本不同也是如此。它的工作方式是将 memory 索引为小块，然后使用嵌入、关键词或两者结合进行搜索。
|
||||
`memory_search` 会从你的内存文件中查找相关笔记，即使措辞与原始文本不同也能找到。它的工作方式是将内存索引为小块，然后使用嵌入、关键词或两者结合进行搜索。
|
||||
|
||||
## 快速开始
|
||||
|
||||
如果你已配置 OpenAI、Gemini、Voyage 或 Mistral API 密钥，memory 搜索会自动工作。要显式设置提供商：
|
||||
如果你已配置 OpenAI、Gemini、Voyage 或 Mistral API 密钥，内存搜索会自动工作。要显式设置提供商：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -34,19 +34,19 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
如需在没有 API 密钥的情况下使用本地嵌入，请使用 `provider: "local"`（需要 `node-llama-cpp`）。
|
||||
对于不使用 API 密钥的本地嵌入，请使用 `provider: "local"`（需要 `node-llama-cpp`）。
|
||||
|
||||
## 支持的提供商
|
||||
|
||||
| 提供商 | ID | 需要 API 密钥 | 说明 |
|
||||
| -------- | --------- | ------------- | ---------------------------------------------------- |
|
||||
| OpenAI | `openai` | 是 | 自动检测，速度快 |
|
||||
| Gemini | `gemini` | 是 | 支持图像/音频索引 |
|
||||
| Voyage | `voyage` | 是 | 自动检测 |
|
||||
| Mistral | `mistral` | 是 | 自动检测 |
|
||||
| Bedrock | `bedrock` | 否 | 当 AWS 凭证链可解析时自动检测 |
|
||||
| Ollama | `ollama` | 否 | 本地，必须显式设置 |
|
||||
| Local | `local` | 否 | GGUF 模型，下载约 0.6 GB |
|
||||
| ------ | --------- | ------------- | ---- |
|
||||
| OpenAI | `openai` | 是 | 自动检测，速度快 |
|
||||
| Gemini | `gemini` | 是 | 支持图像/音频索引 |
|
||||
| Voyage | `voyage` | 是 | 自动检测 |
|
||||
| Mistral | `mistral` | 是 | 自动检测 |
|
||||
| Bedrock | `bedrock` | 否 | 当 AWS 凭证链可解析时自动检测 |
|
||||
| Ollama | `ollama` | 否 | 本地，必须显式设置 |
|
||||
| Local | `local` | 否 | GGUF 模型，下载大小约 0.6 GB |
|
||||
|
||||
## 搜索如何工作
|
||||
|
||||
@ -63,29 +63,29 @@ flowchart LR
|
||||
M --> R["Top Results"]
|
||||
```
|
||||
|
||||
- **向量搜索** 会查找含义相近的笔记（“Gateway 网关主机”可匹配“运行 OpenClaw 的机器”）。
|
||||
- **向量搜索** 会查找语义相近的笔记（“gateway host” 可以匹配 “the machine running OpenClaw”）。
|
||||
- **BM25 关键词搜索** 会查找精确匹配项（ID、错误字符串、配置键）。
|
||||
|
||||
如果只有一条路径可用（没有嵌入或没有 FTS），则仅运行另一条路径。
|
||||
如果只有一条路径可用（没有嵌入或没有 FTS），则只运行另一条路径。
|
||||
|
||||
## 提升搜索质量
|
||||
|
||||
当你有大量笔记历史时，有两个可选功能会很有帮助：
|
||||
当你有大量笔记历史时，有两个可选功能可以提供帮助：
|
||||
|
||||
### 时间衰减
|
||||
|
||||
旧笔记会逐渐失去排序权重，因此最近的信息会优先显示。使用默认的 30 天半衰期时，上个月的笔记得分会降至原始权重的 50%。像 `MEMORY.md` 这样的常青文件永远不会衰减。
|
||||
旧笔记的排名权重会逐渐降低，因此较新的信息会优先显示。使用默认的 30 天半衰期时，上个月的笔记得分会降为原始权重的 50%。像 `MEMORY.md` 这样的常青文件永远不会衰减。
|
||||
|
||||
<Tip>
|
||||
如果你的智能体积累了数月的每日笔记，而过时信息总是排在最近上下文之前，请启用时间衰减。
|
||||
如果你的智能体拥有数月的每日笔记，且过时信息总是排在最近上下文之前，请启用时间衰减。
|
||||
</Tip>
|
||||
|
||||
### MMR（多样性）
|
||||
|
||||
减少重复结果。如果有五条笔记都提到同一个路由器配置，MMR 会确保顶部结果覆盖不同主题，而不是重复同类内容。
|
||||
可减少重复结果。如果五条笔记都提到了相同的路由器配置，MMR 会确保顶部结果覆盖不同主题，而不是重复相同内容。
|
||||
|
||||
<Tip>
|
||||
如果 `memory_search` 总是从不同的每日笔记中返回近似重复的片段，请启用 MMR。
|
||||
如果 `memory_search` 总是从不同的每日笔记中返回几乎重复的片段，请启用 MMR。
|
||||
</Tip>
|
||||
|
||||
### 同时启用两者
|
||||
@ -107,23 +107,24 @@ flowchart LR
|
||||
}
|
||||
```
|
||||
|
||||
## 多模态 memory
|
||||
## 多模态内存
|
||||
|
||||
借助 Gemini Embedding 2，你可以将图像和音频文件与 Markdown 一起建立索引。搜索查询仍然是文本，但会匹配视觉和音频内容。有关设置，请参阅[Memory 配置参考](/zh-CN/reference/memory-config)。
|
||||
使用 Gemini Embedding 2 时，你可以在 Markdown 之外一并索引图像和音频文件。搜索查询仍然是文本，但会与视觉和音频内容进行匹配。有关设置，请参阅 [内存配置参考](/zh-CN/reference/memory-config)。
|
||||
|
||||
## 会话 memory 搜索
|
||||
## 会话内存搜索
|
||||
|
||||
你还可以选择为会话转录建立索引，这样 `memory_search` 就可以回忆更早的对话。这是通过 `memorySearch.experimental.sessionMemory` 选择启用的。详情请参阅[配置参考](/zh-CN/reference/memory-config)。
|
||||
你还可以选择为会话转录建立索引，这样 `memory_search` 就能回忆更早的对话。这是通过 `memorySearch.experimental.sessionMemory` 选择启用的。详情请参阅[配置参考](/zh-CN/reference/memory-config)。
|
||||
|
||||
## 故障排除
|
||||
|
||||
**没有结果？** 运行 `openclaw memory status` 检查索引。如果为空，运行 `openclaw memory index --force`。
|
||||
|
||||
**只有关键词匹配？** 你的嵌入提供商可能尚未配置。请检查 `openclaw memory status --deep`。
|
||||
**只有关键词匹配？** 你的嵌入提供商可能尚未配置。检查 `openclaw memory status --deep`。
|
||||
|
||||
**找不到 CJK 文本？** 使用 `openclaw memory index --force` 重建 FTS 索引。
|
||||
|
||||
## 延伸阅读
|
||||
|
||||
- [Memory](/zh-CN/concepts/memory) -- 文件布局、后端、工具
|
||||
- [Memory 配置参考](/zh-CN/reference/memory-config) -- 所有配置项
|
||||
- [Active Memory](/zh-CN/concepts/active-memory) -- 用于交互式聊天会话的子智能体内存
|
||||
- [内存](/zh-CN/concepts/memory) -- 文件布局、后端、工具
|
||||
- [内存配置参考](/zh-CN/reference/memory-config) -- 所有配置选项
|
||||
|
||||
@ -1,83 +1,91 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想配置内存搜索提供商或嵌入模型
|
||||
- 你想设置 QMD 后端
|
||||
- 你想调整混合搜索、MMR 或时间衰减
|
||||
- 你想启用多模态内存索引
|
||||
- 你想要配置内存搜索提供商或嵌入模型
|
||||
- 你想要设置 QMD 后端
|
||||
- '你想要调优混合搜索、MMR 或时间衰减】【。analysis to=none code વિચાર: Need translate only. user says sentence. output Chinese. MMR probably keep? not glossary but acronym maybe keep. final only.'
|
||||
- 你想要启用多模态内存索引】【。
|
||||
summary: 内存搜索、嵌入提供商、QMD、混合搜索和多模态索引的所有配置项
|
||||
title: 内存配置参考
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T00:47:57Z"
|
||||
generated_at: "2026-04-09T16:29:14Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 0de0b85125443584f4e575cf673ca8d9bd12ecd849d73c537f4a17545afa93fd
|
||||
source_hash: 5f9076bdfad95b87bd70625821bf401326f8eaeb53842b70823881419dbe43cb
|
||||
source_path: reference/memory-config.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 内存配置参考
|
||||
|
||||
本页列出了 OpenClaw 内存搜索的所有配置项。概念性概览请参见：
|
||||
本页列出了 OpenClaw 内存搜索的所有配置项。有关概念性概览，请参阅：
|
||||
|
||||
- [内存概览](/zh-CN/concepts/memory) -- 内存的工作方式
|
||||
- [内置引擎](/zh-CN/concepts/memory-builtin) -- 默认的 SQLite 后端
|
||||
- [QMD 引擎](/zh-CN/concepts/memory-qmd) -- 本地优先的 sidecar
|
||||
- [内存搜索](/zh-CN/concepts/memory-search) -- 搜索流水线与调优
|
||||
- [内存搜索](/zh-CN/concepts/memory-search) -- 搜索流水线和调优
|
||||
- [主动记忆](/zh-CN/concepts/active-memory) -- 为交互式会话启用内存子智能体
|
||||
|
||||
除非另有说明，所有内存搜索设置都位于 `openclaw.json` 中的
|
||||
`agents.defaults.memorySearch` 下。
|
||||
除非另有说明，所有内存搜索设置都位于 `openclaw.json` 中的 `agents.defaults.memorySearch` 下。
|
||||
|
||||
如果你要查找 **主动记忆** 功能开关和子智能体配置，它位于 `plugins.entries.active-memory` 下，而不是 `memorySearch`。
|
||||
|
||||
主动记忆使用双门控模型：
|
||||
|
||||
1. 插件必须已启用，并且目标指向当前智能体 id
|
||||
2. 请求必须是符合条件的交互式持久聊天会话
|
||||
|
||||
有关激活模型、插件自有配置、转录持久化以及安全发布模式，请参阅 [主动记忆](/zh-CN/concepts/active-memory)。
|
||||
|
||||
---
|
||||
|
||||
## 提供商选择
|
||||
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ---------- | --------- | ---------------- | -------------------------------------------------------------------------------------- |
|
||||
| Key | Type | Default | Description |
|
||||
| ---------- | --------- | ---------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `provider` | `string` | 自动检测 | 嵌入适配器 ID：`openai`、`gemini`、`voyage`、`mistral`、`bedrock`、`ollama`、`local` |
|
||||
| `model` | `string` | 提供商默认值 | 嵌入模型名称 |
|
||||
| `fallback` | `string` | `"none"` | 主适配器失败时使用的回退适配器 ID |
|
||||
| `enabled` | `boolean` | `true` | 启用或禁用内存搜索 |
|
||||
| `model` | `string` | 提供商默认值 | 嵌入模型名称 |
|
||||
| `fallback` | `string` | `"none"` | 主适配器失败时使用的后备适配器 ID |
|
||||
| `enabled` | `boolean` | `true` | 启用或禁用内存搜索 |
|
||||
|
||||
### 自动检测顺序
|
||||
|
||||
当未设置 `provider` 时，OpenClaw 会选择第一个可用项：
|
||||
|
||||
1. `local` -- 如果已配置 `memorySearch.local.modelPath` 且文件存在。
|
||||
2. `openai` -- 如果可以解析出 OpenAI 密钥。
|
||||
3. `gemini` -- 如果可以解析出 Gemini 密钥。
|
||||
4. `voyage` -- 如果可以解析出 Voyage 密钥。
|
||||
5. `mistral` -- 如果可以解析出 Mistral 密钥。
|
||||
6. `bedrock` -- 如果 AWS SDK 凭证链可以解析成功（实例角色、访问密钥、profile、SSO、web identity 或共享配置）。
|
||||
2. `openai` -- 如果可以解析 OpenAI key。
|
||||
3. `gemini` -- 如果可以解析 Gemini key。
|
||||
4. `voyage` -- 如果可以解析 Voyage key。
|
||||
5. `mistral` -- 如果可以解析 Mistral key。
|
||||
6. `bedrock` -- 如果 AWS SDK 凭证链可以解析（实例角色、访问密钥、profile、SSO、web identity 或共享配置）。
|
||||
|
||||
支持 `ollama`，但不会自动检测（请显式设置）。
|
||||
|
||||
### API 密钥解析
|
||||
|
||||
远程嵌入需要 API 密钥。Bedrock 则改用 AWS SDK 默认凭证链
|
||||
（实例角色、SSO、访问密钥）。
|
||||
远程嵌入需要 API 密钥。Bedrock 则改用 AWS SDK 默认凭证链（实例角色、SSO、访问密钥）。
|
||||
|
||||
| 提供商 | 环境变量 | 配置键 |
|
||||
| ------ | ------------------------------ | --------------------------------- |
|
||||
| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
|
||||
| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
|
||||
| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
|
||||
| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` |
|
||||
| Bedrock | AWS 凭证链 | 不需要 API 密钥 |
|
||||
| Ollama | `OLLAMA_API_KEY`（占位符） | -- |
|
||||
| Provider | Env var | Config key |
|
||||
| -------- | ------------------------------ | --------------------------------- |
|
||||
| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
|
||||
| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
|
||||
| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
|
||||
| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` |
|
||||
| Bedrock | AWS 凭证链 | 不需要 API 密钥 |
|
||||
| Ollama | `OLLAMA_API_KEY`（占位符） | -- |
|
||||
|
||||
Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求。
|
||||
Codex OAuth 仅覆盖聊天/completions，不满足嵌入请求的要求。
|
||||
|
||||
---
|
||||
|
||||
## 远程端点配置
|
||||
|
||||
用于自定义兼容 OpenAI 的端点或覆盖提供商默认值：
|
||||
用于自定义 OpenAI 兼容端点或覆盖提供商默认值：
|
||||
|
||||
| 键 | 类型 | 说明 |
|
||||
| ---------------- | -------- | ------------------------------------ |
|
||||
| `remote.baseUrl` | `string` | 自定义 API 基础 URL |
|
||||
| `remote.apiKey` | `string` | 覆盖 API 密钥 |
|
||||
| `remote.headers` | `object` | 额外的 HTTP 标头（与提供商默认值合并） |
|
||||
| Key | Type | Description |
|
||||
| ---------------- | -------- | -------------------------------------------- |
|
||||
| `remote.baseUrl` | `string` | 自定义 API 基础 URL |
|
||||
| `remote.apiKey` | `string` | 覆盖 API 密钥 |
|
||||
| `remote.headers` | `object` | 额外的 HTTP headers（与提供商默认值合并） |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -100,13 +108,13 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求。
|
||||
|
||||
## Gemini 专用配置
|
||||
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| Key | Type | Default | Description |
|
||||
| ---------------------- | -------- | ---------------------- | ------------------------------------------ |
|
||||
| `model` | `string` | `gemini-embedding-001` | 也支持 `gemini-embedding-2-preview` |
|
||||
| `outputDimensionality` | `number` | `3072` | 对于 Embedding 2：可为 768、1536 或 3072 |
|
||||
| `outputDimensionality` | `number` | `3072` | 对于 Embedding 2：768、1536 或 3072 |
|
||||
|
||||
<Warning>
|
||||
更改模型或 `outputDimensionality` 会触发自动全量重建索引。
|
||||
更改模型或 `outputDimensionality` 会触发自动全量重新索引。
|
||||
</Warning>
|
||||
|
||||
---
|
||||
@ -114,8 +122,7 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求。
|
||||
## Bedrock 嵌入配置
|
||||
|
||||
Bedrock 使用 AWS SDK 默认凭证链 -- 不需要 API 密钥。
|
||||
如果 OpenClaw 运行在启用了 Bedrock 实例角色的 EC2 上，只需设置
|
||||
提供商和模型：
|
||||
如果 OpenClaw 运行在具有 Bedrock 权限实例角色的 EC2 上，只需设置提供商和模型：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -130,30 +137,29 @@ Bedrock 使用 AWS SDK 默认凭证链 -- 不需要 API 密钥。
|
||||
}
|
||||
```
|
||||
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ---------------------- | -------- | ------------------------------ | --------------------------- |
|
||||
| `model` | `string` | `amazon.titan-embed-text-v2:0` | 任意 Bedrock 嵌入模型 ID |
|
||||
| Key | Type | Default | Description |
|
||||
| ---------------------- | -------- | ------------------------------ | ------------------------------ |
|
||||
| `model` | `string` | `amazon.titan-embed-text-v2:0` | 任意 Bedrock 嵌入模型 ID |
|
||||
| `outputDimensionality` | `number` | 模型默认值 | 对于 Titan V2：256、512 或 1024 |
|
||||
|
||||
### 支持的模型
|
||||
|
||||
支持以下模型（带有系列检测和默认维度）：
|
||||
支持以下模型（带系列检测和维度默认值）：
|
||||
|
||||
| 模型 ID | 提供商 | 默认维度 | 可配置维度 |
|
||||
| ------------------------------------------ | ---------- | -------- | -------------------- |
|
||||
| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256、512、1024 |
|
||||
| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- |
|
||||
| `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- |
|
||||
| `amazon.titan-embed-image-v1` | Amazon | 1024 | -- |
|
||||
| `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256、384、1024、3072 |
|
||||
| `cohere.embed-english-v3` | Cohere | 1024 | -- |
|
||||
| `cohere.embed-multilingual-v3` | Cohere | 1024 | -- |
|
||||
| `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 |
|
||||
| `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- |
|
||||
| `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- |
|
||||
| Model ID | Provider | Default Dims | Configurable Dims |
|
||||
| ------------------------------------------ | ---------- | ------------ | -------------------- |
|
||||
| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 |
|
||||
| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- |
|
||||
| `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- |
|
||||
| `amazon.titan-embed-image-v1` | Amazon | 1024 | -- |
|
||||
| `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 |
|
||||
| `cohere.embed-english-v3` | Cohere | 1024 | -- |
|
||||
| `cohere.embed-multilingual-v3` | Cohere | 1024 | -- |
|
||||
| `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 |
|
||||
| `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- |
|
||||
| `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- |
|
||||
|
||||
带吞吐量后缀的变体（例如 `amazon.titan-embed-text-v1:2:8k`）会继承
|
||||
基础模型的配置。
|
||||
带吞吐量后缀的变体（例如 `amazon.titan-embed-text-v1:2:8k`）会继承基础模型的配置。
|
||||
|
||||
### 身份验证
|
||||
|
||||
@ -161,12 +167,11 @@ Bedrock 身份验证使用标准 AWS SDK 凭证解析顺序：
|
||||
|
||||
1. 环境变量（`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`）
|
||||
2. SSO 令牌缓存
|
||||
3. Web identity 令牌凭证
|
||||
3. Web identity token 凭证
|
||||
4. 共享凭证和配置文件
|
||||
5. ECS 或 EC2 元数据凭证
|
||||
|
||||
区域从 `AWS_REGION`、`AWS_DEFAULT_REGION`、`amazon-bedrock`
|
||||
提供商的 `baseUrl` 中解析，或默认使用 `us-east-1`。
|
||||
区域会从 `AWS_REGION`、`AWS_DEFAULT_REGION`、`amazon-bedrock` 提供商的 `baseUrl` 中解析，或默认使用 `us-east-1`。
|
||||
|
||||
### IAM 权限
|
||||
|
||||
@ -180,7 +185,7 @@ IAM 角色或用户需要：
|
||||
}
|
||||
```
|
||||
|
||||
为实现最小权限，请将 `InvokeModel` 限定到特定模型：
|
||||
为了实现最小权限，应将 `InvokeModel` 限定到特定模型：
|
||||
|
||||
```
|
||||
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
|
||||
@ -190,10 +195,10 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
|
||||
|
||||
## 本地嵌入配置
|
||||
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| --------------------- | -------- | ---------------------- | ------------------------ |
|
||||
| `local.modelPath` | `string` | 自动下载 | GGUF 模型文件路径 |
|
||||
| `local.modelCacheDir` | `string` | node-llama-cpp 默认值 | 已下载模型的缓存目录 |
|
||||
| Key | Type | Default | Description |
|
||||
| --------------------- | -------- | ---------------------- | -------------------------- |
|
||||
| `local.modelPath` | `string` | 自动下载 | GGUF 模型文件路径 |
|
||||
| `local.modelCacheDir` | `string` | node-llama-cpp 默认值 | 已下载模型的缓存目录 |
|
||||
|
||||
默认模型：`embeddinggemma-300m-qat-Q8_0.gguf`（约 0.6 GB，自动下载）。
|
||||
需要原生构建：`pnpm approve-builds`，然后执行 `pnpm rebuild node-llama-cpp`。
|
||||
@ -204,28 +209,28 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
|
||||
|
||||
全部位于 `memorySearch.query.hybrid` 下：
|
||||
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| --------------------- | --------- | ------- | ---------------------------------- |
|
||||
| `enabled` | `boolean` | `true` | 启用 BM25 + 向量混合搜索 |
|
||||
| `vectorWeight` | `number` | `0.7` | 向量分数权重（0-1） |
|
||||
| `textWeight` | `number` | `0.3` | BM25 分数权重（0-1） |
|
||||
| `candidateMultiplier` | `number` | `4` | 候选池大小乘数 |
|
||||
| Key | Type | Default | Description |
|
||||
| --------------------- | --------- | ------- | ------------------------------ |
|
||||
| `enabled` | `boolean` | `true` | 启用混合 BM25 + 向量搜索 |
|
||||
| `vectorWeight` | `number` | `0.7` | 向量分数权重（0-1） |
|
||||
| `textWeight` | `number` | `0.3` | BM25 分数权重（0-1） |
|
||||
| `candidateMultiplier` | `number` | `4` | 候选池大小乘数 |
|
||||
|
||||
### MMR（多样性）
|
||||
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ------------- | --------- | ------- | ------------------------------------ |
|
||||
| `mmr.enabled` | `boolean` | `false` | 启用 MMR 重排序 |
|
||||
| `mmr.lambda` | `number` | `0.7` | 0 = 最大多样性，1 = 最大相关性 |
|
||||
| Key | Type | Default | Description |
|
||||
| ------------- | --------- | ------- | -------------------------------- |
|
||||
| `mmr.enabled` | `boolean` | `false` | 启用 MMR 重排序 |
|
||||
| `mmr.lambda` | `number` | `0.7` | 0 = 最大多样性，1 = 最大相关性 |
|
||||
|
||||
### 时间衰减（新近性）
|
||||
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ---------------------------- | --------- | ------- | ------------------------- |
|
||||
| `temporalDecay.enabled` | `boolean` | `false` | 启用新近性加权 |
|
||||
| `temporalDecay.halfLifeDays` | `number` | `30` | 分数每 N 天减半 |
|
||||
| Key | Type | Default | Description |
|
||||
| ---------------------------- | --------- | ------- | -------------------- |
|
||||
| `temporalDecay.enabled` | `boolean` | `false` | 启用新近性加权 |
|
||||
| `temporalDecay.halfLifeDays` | `number` | `30` | 分数每 N 天减半 |
|
||||
|
||||
常青文件（`MEMORY.md`、`memory/` 中无日期的文件）永不衰减。
|
||||
常青文件（`MEMORY.md`、`memory/` 中非日期命名的文件）永远不会衰减。
|
||||
|
||||
### 完整示例
|
||||
|
||||
@ -250,11 +255,11 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
|
||||
|
||||
---
|
||||
|
||||
## 额外内存路径
|
||||
## 其他内存路径
|
||||
|
||||
| 键 | 类型 | 说明 |
|
||||
| ------------ | ---------- | -------------------------------------- |
|
||||
| `extraPaths` | `string[]` | 要建立索引的额外目录或文件 |
|
||||
| Key | Type | Description |
|
||||
| ------------ | ---------- | ------------------------------ |
|
||||
| `extraPaths` | `string[]` | 要索引的其他目录或文件 |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -268,149 +273,134 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
|
||||
}
|
||||
```
|
||||
|
||||
路径可以是绝对路径或相对于工作区的路径。目录会被递归扫描，
|
||||
查找 `.md` 文件。符号链接处理取决于当前后端：
|
||||
内置引擎会忽略符号链接，而 QMD 会遵循底层 QMD
|
||||
扫描器的行为。
|
||||
路径可以是绝对路径，也可以是相对于工作区的路径。目录会递归扫描其中的 `.md` 文件。符号链接的处理取决于当前使用的后端：内置引擎会忽略符号链接，而 QMD 会遵循底层 QMD 扫描器的行为。
|
||||
|
||||
对于按智能体作用域进行的跨智能体转录搜索，请使用
|
||||
`agents.list[].memorySearch.qmd.extraCollections`，而不是 `memory.qmd.paths`。
|
||||
这些额外集合遵循相同的 `{ path, name, pattern? }` 结构，但会按智能体合并，
|
||||
并且当路径指向当前工作区之外时，可以保留显式共享名称。
|
||||
如果同一个解析后的路径同时出现在 `memory.qmd.paths` 和
|
||||
`memorySearch.qmd.extraCollections` 中，QMD 会保留第一条条目并跳过
|
||||
重复项。
|
||||
对于按智能体范围进行的跨智能体转录搜索，请使用 `agents.list[].memorySearch.qmd.extraCollections`，而不是 `memory.qmd.paths`。这些额外集合遵循相同的 `{ path, name, pattern? }` 结构，但它们会按智能体进行合并，并且当路径指向当前工作区外部时，可以保留显式共享名称。
|
||||
如果同一个解析后的路径同时出现在 `memory.qmd.paths` 和 `memorySearch.qmd.extraCollections` 中，QMD 会保留第一条记录并跳过重复项。
|
||||
|
||||
---
|
||||
|
||||
## 多模态内存（Gemini）
|
||||
|
||||
使用 Gemini Embedding 2 将图像和音频与 Markdown 一起建立索引：
|
||||
使用 Gemini Embedding 2 将图片和音频与 Markdown 一起建立索引：
|
||||
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ------------------------- | ---------- | ---------- | -------------------------------------- |
|
||||
| `multimodal.enabled` | `boolean` | `false` | 启用多模态索引 |
|
||||
| `multimodal.modalities` | `string[]` | -- | `["image"]`、`["audio"]` 或 `["all"]` |
|
||||
| `multimodal.maxFileBytes` | `number` | `10000000` | 建立索引的最大文件大小 |
|
||||
| Key | Type | Default | Description |
|
||||
| ------------------------- | ---------- | ---------- | ------------------------------------- |
|
||||
| `multimodal.enabled` | `boolean` | `false` | 启用多模态索引 |
|
||||
| `multimodal.modalities` | `string[]` | -- | `["image"]`、`["audio"]` 或 `["all"]` |
|
||||
| `multimodal.maxFileBytes` | `number` | `10000000` | 索引文件大小上限 |
|
||||
|
||||
仅适用于 `extraPaths` 中的文件。默认内存根目录仍然只处理 Markdown。
|
||||
仅适用于 `extraPaths` 中的文件。默认内存根目录仍然只支持 Markdown。
|
||||
需要 `gemini-embedding-2-preview`。`fallback` 必须为 `"none"`。
|
||||
|
||||
支持的格式：`.jpg`、`.jpeg`、`.png`、`.webp`、`.gif`、`.heic`、`.heif`
|
||||
（图像）；`.mp3`、`.wav`、`.ogg`、`.opus`、`.m4a`、`.aac`、`.flac`（音频）。
|
||||
（图片）；`.mp3`、`.wav`、`.ogg`、`.opus`、`.m4a`、`.aac`、`.flac`（音频）。
|
||||
|
||||
---
|
||||
|
||||
## 嵌入缓存
|
||||
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ------------------ | --------- | ------- | --------------------------------- |
|
||||
| `cache.enabled` | `boolean` | `false` | 在 SQLite 中缓存分块嵌入 |
|
||||
| `cache.maxEntries` | `number` | `50000` | 最大缓存嵌入条目数 |
|
||||
| Key | Type | Default | Description |
|
||||
| ------------------ | --------- | ------- | ------------------------------ |
|
||||
| `cache.enabled` | `boolean` | `false` | 在 SQLite 中缓存分块嵌入 |
|
||||
| `cache.maxEntries` | `number` | `50000` | 最大缓存嵌入条目数 |
|
||||
|
||||
可防止在重建索引或转录更新期间，对未更改文本重复生成嵌入。
|
||||
可防止在重新索引或转录更新期间，对未变化的文本重复生成嵌入。
|
||||
|
||||
---
|
||||
|
||||
## 批量索引
|
||||
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ----------------------------- | --------- | ------- | ------------------------ |
|
||||
| `remote.batch.enabled` | `boolean` | `false` | 启用批量嵌入 API |
|
||||
| `remote.batch.concurrency` | `number` | `2` | 并行批处理任务数 |
|
||||
| `remote.batch.wait` | `boolean` | `true` | 等待批处理完成 |
|
||||
| `remote.batch.pollIntervalMs` | `number` | -- | 轮询间隔 |
|
||||
| `remote.batch.timeoutMinutes` | `number` | -- | 批处理超时时间 |
|
||||
| Key | Type | Default | Description |
|
||||
| ----------------------------- | --------- | ------- | ---------------------- |
|
||||
| `remote.batch.enabled` | `boolean` | `false` | 启用批量嵌入 API |
|
||||
| `remote.batch.concurrency` | `number` | `2` | 并行批量任务数 |
|
||||
| `remote.batch.wait` | `boolean` | `true` | 等待批量完成 |
|
||||
| `remote.batch.pollIntervalMs` | `number` | -- | 轮询间隔 |
|
||||
| `remote.batch.timeoutMinutes` | `number` | -- | 批量超时时间 |
|
||||
|
||||
适用于 `openai`、`gemini` 和 `voyage`。对于大型回填任务，
|
||||
OpenAI 批处理通常最快且成本最低。
|
||||
适用于 `openai`、`gemini` 和 `voyage`。对于大规模回填，OpenAI 批量通常最快且最便宜。
|
||||
|
||||
---
|
||||
|
||||
## 会话内存搜索（实验性）
|
||||
|
||||
为会话转录建立索引，并通过 `memory_search` 提供结果：
|
||||
索引会话转录，并通过 `memory_search` 提供结果：
|
||||
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ----------------------------- | ---------- | ------------- | -------------------------------------- |
|
||||
| `experimental.sessionMemory` | `boolean` | `false` | 启用会话索引 |
|
||||
| `sources` | `string[]` | `["memory"]` | 添加 `"sessions"` 以包含转录内容 |
|
||||
| `sync.sessions.deltaBytes` | `number` | `100000` | 触发重建索引的字节阈值 |
|
||||
| `sync.sessions.deltaMessages` | `number` | `50` | 触发重建索引的消息阈值 |
|
||||
| Key | Type | Default | Description |
|
||||
| ----------------------------- | ---------- | ------------ | -------------------------------------- |
|
||||
| `experimental.sessionMemory` | `boolean` | `false` | 启用会话索引 |
|
||||
| `sources` | `string[]` | `["memory"]` | 添加 `"sessions"` 以包含转录 |
|
||||
| `sync.sessions.deltaBytes` | `number` | `100000` | 触发重新索引的字节阈值 |
|
||||
| `sync.sessions.deltaMessages` | `number` | `50` | 触发重新索引的消息阈值 |
|
||||
|
||||
会话索引采用选择加入方式，并异步运行。结果可能略有滞后。
|
||||
会话日志存储在磁盘上，因此请将文件系统访问视为信任边界。
|
||||
会话索引为可选启用，并以异步方式运行。结果可能会略有滞后。会话日志保存在磁盘上，因此应将文件系统访问视为信任边界。
|
||||
|
||||
---
|
||||
|
||||
## SQLite 向量加速（sqlite-vec）
|
||||
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ---------------------------- | --------- | ------- | --------------------------------- |
|
||||
| `store.vector.enabled` | `boolean` | `true` | 使用 sqlite-vec 进行向量查询 |
|
||||
| `store.vector.extensionPath` | `string` | 内置 | 覆盖 sqlite-vec 路径 |
|
||||
| Key | Type | Default | Description |
|
||||
| ---------------------------- | --------- | ------- | ------------------------------- |
|
||||
| `store.vector.enabled` | `boolean` | `true` | 对向量查询使用 sqlite-vec |
|
||||
| `store.vector.extensionPath` | `string` | bundled | 覆盖 sqlite-vec 路径 |
|
||||
|
||||
当 sqlite-vec 不可用时，OpenClaw 会自动回退到进程内余弦相似度。
|
||||
当 sqlite-vec 不可用时，OpenClaw 会自动回退到进程内余弦相似度计算。
|
||||
|
||||
---
|
||||
|
||||
## 索引存储
|
||||
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| --------------------- | -------- | ------------------------------------- | ----------------------------------------- |
|
||||
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | 索引位置（支持 `{agentId}` 令牌） |
|
||||
| `store.fts.tokenizer` | `string` | `unicode61` | FTS5 分词器（`unicode61` 或 `trigram`） |
|
||||
| Key | Type | Default | Description |
|
||||
| --------------------- | -------- | ------------------------------------- | ------------------------------------------ |
|
||||
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | 索引位置（支持 `{agentId}` 令牌） |
|
||||
| `store.fts.tokenizer` | `string` | `unicode61` | FTS5 分词器（`unicode61` 或 `trigram`） |
|
||||
|
||||
---
|
||||
|
||||
## QMD 后端配置
|
||||
|
||||
设置 `memory.backend = "qmd"` 以启用。所有 QMD 设置都位于
|
||||
`memory.qmd` 下：
|
||||
设置 `memory.backend = "qmd"` 以启用。所有 QMD 设置都位于 `memory.qmd` 下：
|
||||
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ------------------------ | --------- | -------- | -------------------------------------------- |
|
||||
| `command` | `string` | `qmd` | QMD 可执行文件路径 |
|
||||
| `searchMode` | `string` | `search` | 搜索命令：`search`、`vsearch`、`query` |
|
||||
| `includeDefaultMemory` | `boolean` | `true` | 自动索引 `MEMORY.md` + `memory/**/*.md` |
|
||||
| `paths[]` | `array` | -- | 额外路径：`{ name, path, pattern? }` |
|
||||
| `sessions.enabled` | `boolean` | `false` | 为会话转录建立索引 |
|
||||
| `sessions.retentionDays` | `number` | -- | 转录保留时间 |
|
||||
| `sessions.exportDir` | `string` | -- | 导出目录 |
|
||||
| Key | Type | Default | Description |
|
||||
| ------------------------ | --------- | -------- | ------------------------------------------- |
|
||||
| `command` | `string` | `qmd` | QMD 可执行文件路径 |
|
||||
| `searchMode` | `string` | `search` | 搜索命令：`search`、`vsearch`、`query` |
|
||||
| `includeDefaultMemory` | `boolean` | `true` | 自动索引 `MEMORY.md` + `memory/**/*.md` |
|
||||
| `paths[]` | `array` | -- | 额外路径：`{ name, path, pattern? }` |
|
||||
| `sessions.enabled` | `boolean` | `false` | 索引会话转录 |
|
||||
| `sessions.retentionDays` | `number` | -- | 转录保留期 |
|
||||
| `sessions.exportDir` | `string` | -- | 导出目录 |
|
||||
|
||||
OpenClaw 优先使用当前的 QMD 集合和 MCP 查询结构，但也会在需要时回退到旧版
|
||||
QMD 发布版本支持的旧 `--mask` 集合标志和旧 MCP 工具名称，以保持兼容。
|
||||
OpenClaw 优先使用当前的 QMD collection 和 MCP query 结构，但会在需要时回退到旧版 `--mask` collection 标志和旧版 MCP 工具名称，以保持与较早 QMD 版本的兼容性。
|
||||
|
||||
QMD 模型覆盖保留在 QMD 侧，而不是 OpenClaw 配置中。如果你需要全局覆盖
|
||||
QMD 的模型，请在 Gateway 网关运行时环境中设置环境变量，例如
|
||||
`QMD_EMBED_MODEL`、`QMD_RERANK_MODEL` 和 `QMD_GENERATE_MODEL`。
|
||||
QMD 模型覆盖配置保留在 QMD 侧，而不是 OpenClaw 配置中。如果你需要全局覆盖 QMD 的模型，请在 Gateway 网关运行时环境中设置诸如 `QMD_EMBED_MODEL`、`QMD_RERANK_MODEL` 和 `QMD_GENERATE_MODEL` 之类的环境变量。
|
||||
|
||||
### 更新计划
|
||||
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ------------------------- | --------- | -------- | ------------------------------------ |
|
||||
| `update.interval` | `string` | `5m` | 刷新间隔 |
|
||||
| `update.debounceMs` | `number` | `15000` | 文件变更防抖 |
|
||||
| `update.onBoot` | `boolean` | `true` | 启动时刷新 |
|
||||
| `update.waitForBootSync` | `boolean` | `false` | 阻止启动直到刷新完成 |
|
||||
| `update.embedInterval` | `string` | -- | 单独的嵌入执行周期 |
|
||||
| `update.commandTimeoutMs` | `number` | -- | QMD 命令超时时间 |
|
||||
| `update.updateTimeoutMs` | `number` | -- | QMD 更新操作超时时间 |
|
||||
| `update.embedTimeoutMs` | `number` | -- | QMD 嵌入操作超时时间 |
|
||||
| Key | Type | Default | Description |
|
||||
| ------------------------- | --------- | ------- | --------------------------------- |
|
||||
| `update.interval` | `string` | `5m` | 刷新间隔 |
|
||||
| `update.debounceMs` | `number` | `15000` | 文件变更去抖时间 |
|
||||
| `update.onBoot` | `boolean` | `true` | 启动时刷新 |
|
||||
| `update.waitForBootSync` | `boolean` | `false` | 在刷新完成前阻塞启动 |
|
||||
| `update.embedInterval` | `string` | -- | 单独的嵌入执行周期 |
|
||||
| `update.commandTimeoutMs` | `number` | -- | QMD 命令超时时间 |
|
||||
| `update.updateTimeoutMs` | `number` | -- | QMD 更新操作超时时间 |
|
||||
| `update.embedTimeoutMs` | `number` | -- | QMD 嵌入操作超时时间 |
|
||||
|
||||
### 限制
|
||||
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ------------------------- | -------- | ------- | ------------------------ |
|
||||
| `limits.maxResults` | `number` | `6` | 最大搜索结果数 |
|
||||
| `limits.maxSnippetChars` | `number` | -- | 限制摘要长度 |
|
||||
| `limits.maxInjectedChars` | `number` | -- | 限制注入的总字符数 |
|
||||
| `limits.timeoutMs` | `number` | `4000` | 搜索超时时间 |
|
||||
| Key | Type | Default | Description |
|
||||
| ------------------------- | -------- | ------- | ---------------------- |
|
||||
| `limits.maxResults` | `number` | `6` | 最大搜索结果数 |
|
||||
| `limits.maxSnippetChars` | `number` | -- | 限制片段长度 |
|
||||
| `limits.maxInjectedChars` | `number` | -- | 限制注入字符总数 |
|
||||
| `limits.timeoutMs` | `number` | `4000` | 搜索超时时间 |
|
||||
|
||||
### 范围
|
||||
|
||||
控制哪些会话可以接收 QMD 搜索结果。与
|
||||
[`session.sendPolicy`](/zh-CN/gateway/configuration-reference#session) 使用相同的 schema：
|
||||
控制哪些会话可以接收 QMD 搜索结果。使用与 [`session.sendPolicy`](/zh-CN/gateway/configuration-reference#session) 相同的 schema：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -425,18 +415,18 @@ QMD 的模型，请在 Gateway 网关运行时环境中设置环境变量，例
|
||||
}
|
||||
```
|
||||
|
||||
默认仅限私信。`match.keyPrefix` 匹配规范化后的会话键；
|
||||
`match.rawKeyPrefix` 匹配包含 `agent:<id>:` 的原始键。
|
||||
默认仅限私信。`match.keyPrefix` 匹配规范化后的会话 key；
|
||||
`match.rawKeyPrefix` 匹配包含 `agent:<id>:` 的原始 key。
|
||||
|
||||
### 引用
|
||||
|
||||
`memory.citations` 适用于所有后端：
|
||||
|
||||
| 值 | 行为 |
|
||||
| ---------------- | ---------------------------------------------------- |
|
||||
| `auto`（默认） | 在摘要中包含 `Source: <path#line>` 页脚 |
|
||||
| `on` | 始终包含页脚 |
|
||||
| `off` | 省略页脚（路径仍会在内部传递给智能体） |
|
||||
| Value | Behavior |
|
||||
| ---------------- | --------------------------------------------- |
|
||||
| `auto`（默认） | 在片段中包含 `Source: <path#line>` 页脚 |
|
||||
| `on` | 始终包含页脚 |
|
||||
| `off` | 省略页脚（路径仍会在内部传递给智能体） |
|
||||
|
||||
### 完整 QMD 示例
|
||||
|
||||
@ -466,17 +456,16 @@ QMD 的模型，请在 Gateway 网关运行时环境中设置环境变量，例
|
||||
Dreaming 配置位于 `plugins.entries.memory-core.config.dreaming` 下，
|
||||
而不在 `agents.defaults.memorySearch` 下。
|
||||
|
||||
Dreaming 作为一次计划任务扫描运行，并将内部的 light/deep/REM 阶段
|
||||
作为实现细节使用。
|
||||
Dreaming 作为一次计划内扫描运行，并将内部的 light/deep/REM 阶段作为实现细节来使用。
|
||||
|
||||
有关概念行为和斜杠命令，请参见 [Dreaming](/zh-CN/concepts/dreaming)。
|
||||
有关概念行为和斜杠命令，请参阅 [Dreaming](/zh-CN/concepts/dreaming)。
|
||||
|
||||
### 用户设置
|
||||
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ----------- | --------- | ----------- | ---------------------------------------------- |
|
||||
| `enabled` | `boolean` | `false` | 完全启用或禁用 Dreaming |
|
||||
| `frequency` | `string` | `0 3 * * *` | 整个 Dreaming 扫描的可选 cron 执行频率 |
|
||||
| Key | Type | Default | Description |
|
||||
| ----------- | --------- | ----------- | -------------------------------------------- |
|
||||
| `enabled` | `boolean` | `false` | 完全启用或禁用 Dreaming |
|
||||
| `frequency` | `string` | `0 3 * * *` | 完整 Dreaming 扫描的可选 cron 执行周期 |
|
||||
|
||||
### 示例
|
||||
|
||||
@ -497,8 +486,8 @@ Dreaming 作为一次计划任务扫描运行，并将内部的 light/deep/REM
|
||||
}
|
||||
```
|
||||
|
||||
注意：
|
||||
说明：
|
||||
|
||||
- Dreaming 会将机器状态写入 `memory/.dreams/`。
|
||||
- Dreaming 会将人类可读的叙事输出写入 `DREAMS.md`（或现有的 `dreams.md`）。
|
||||
- Dreaming 会将人类可读的叙述输出写入 `DREAMS.md`（或现有的 `dreams.md`）。
|
||||
- light/deep/REM 阶段策略和阈值属于内部行为，不是面向用户的配置。
|
||||
|
||||
Loading…
Reference in New Issue
Block a user