openclaw怎么调用记忆的

作者：CSDN博客
https://deepwiki.com/search/_102ce0dc-bde6-4596-b145-a914d607d3ec?mode=fast
简要总结

OpenClaw 的记忆以工作区中的 Markdown 文件为唯一事实来源，配合可选的向量/混合索引实现语义搜索；系统会在会话接近压缩时自动触发“记忆刷新”提醒模型持久化重要信息，并提供 CLI 工具用于手动索引与搜索 12 。

---

1. 记忆文件结构（Markdown）

memory/YYYY-MM-DD.md：每日日志（仅追加），会话开始时读取当天与昨天的内容 3 。MEMORY.md：长期记忆，仅在主/私人会话加载，群组上下文不加载 4 。这些文件位于工作区（agents.defaults.workspace，默认 ~/.openclaw/workspace） 5 。

2. 何时写入记忆

决策、偏好、持久事实写入 MEMORY.md；日常笔记写入当日 memory/YYYY-MM-DD.md6 。若有人说“记住这个”，应立即写入文件而非仅存内存 7 。

3. 自动记忆刷新（压缩前触发）

当会话接近自动压缩时，系统触发一次静默的智能体回合，提醒模型写入持久记忆 8 。由 agents.defaults.compaction.memoryFlush 控制，支持软阈值、双提示与每周期一次刷新；沙箱只读工作区会跳过 9 。

4. 向量/混合搜索与索引

默认启用对 MEMORY.md 与 memory/**/*.md 的向量索引，支持 OpenAI/Gemini/Voyage/本地嵌入；自动选择可用提供商 10 。混合搜索结合向量相似度与 BM25 关键词，权重可配（默认 0.7/0.3） 11 。索引存储为每智能体的 SQLite（~/.openclaw/memory/<agentId>.sqlite），监视文件变更并异步同步；嵌入/模型/分块参数变化会触发全量重建 12 。工具：memory_search 返回带来源的片段；memory_get 按路径读取文件 13 。

5. CLI 管理

openclaw memory status：查看状态；--deep 探测向量与嵌入可用性；--index 在脏时重建索引 14 。openclaw memory index：手动重建索引；--verbose 输出详细日志 15 。openclaw memory search "查询词"：执行语义搜索 16 。支持 --agent <id> 限定单智能体操作 17 。

6. 配置要点

记忆搜索配置位于 agents.defaults.memorySearch，可设 provider、model、fallback、extraPaths、混合权重、缓存等 18 。实验性功能：会话记忆搜索（需开启 experimental.sessionMemory 与 sources: ["memory","sessions"]） 19 。可选后端：QMD（需单独安装）或内置 SQLite 向量加速（sqlite-vec） 2021 。

7. 常见问题

记忆持久化在磁盘，直到手动删除；会话上下文仍受模型窗口限制，因此需要记忆搜索 22 。若模型“忘记”，请明确要求其写入 MEMORY.md 或当日文件，并确认 Gateway 使用同一工作区 23 。

---

Notes

记忆文件是唯一可信源，模型仅“记住”写入磁盘的内容 24 。可通过 plugins.slots.memory = "none" 禁用记忆插件 25 。中文用户可参考 docs/zh-CN/concepts/memory.md 与 docs/zh-CN/cli/memory.md 获取本地化说明 2627 。

Wiki pages you might want to explore:

Overview (openclaw/openclaw)

Citations

File: docs/concepts/memory.md (L11-27)

1. OpenClaw memory is **plain Markdown in the agent workspace**. The files are the
2. source of truth; the model only "remembers" what gets written to disk.
4. Memory search tools are provided by the active memory plugin (default:
5. `memory-core`). Disable memory plugins with `plugins.slots.memory = "none"`.
7. ## Memory files (Markdown)
9. The default workspace layout uses two memory layers:
11. - `memory/YYYY-MM-DD.md`
12.   - Daily log (append-only).
13.   - Read today + yesterday at session start.
14. - `MEMORY.md` (optional)
15.   - Curated long-term memory.
16.   - **Only load in the main, private session** (never in group contexts).

复制代码

File: docs/concepts/memory.md (L28-29)

1. These files live under the workspace (`agents.defaults.workspace`, default
2. `~/.openclaw/workspace`). See [Agent workspace](/concepts/agent-workspace) for the full layout.

复制代码

File: docs/concepts/memory.md (L33-34)

1. - Decisions, preferences, and durable facts go to `MEMORY.md`.
2. - Day-to-day notes and running context go to `memory/YYYY-MM-DD.md`.

复制代码

File: docs/concepts/memory.md (L35-37)

1. - If someone says "remember this," write it down (do not keep it in RAM).
2. - This area is still evolving. It helps to remind the model to store memories; it will know what to do.
3. - If you want something to stick, **ask the bot to write it** into memory.

复制代码

File: docs/concepts/memory.md (L39-45)

1. ## Automatic memory flush (pre-compaction ping)
3. When a session is **close to auto-compaction**, OpenClaw triggers a **silent,
4. agentic turn** that reminds the model to write durable memory **before** the
5. context is compacted. The default prompts explicitly say the model _may reply_,
6. but usually `NO_REPLY` is the correct response so the user never sees this turn.

复制代码

File: docs/concepts/memory.md (L46-75)

1. This is controlled by `agents.defaults.compaction.memoryFlush`:
3. ```json5
4. {
5.   agents: {
6.     defaults: {
7.       compaction: {
8.         reserveTokensFloor: 20000,
9.         memoryFlush: {
10.           enabled: true,
11.           softThresholdTokens: 4000,
12.           systemPrompt: "Session nearing compaction. Store durable memories now.",
13.           prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store.",
14.         },
15.       },
16.     },
17.   },
18. }

复制代码

Details:

Soft threshold: flush triggers when the session token estimate crosses
contextWindow - reserveTokensFloor - softThresholdTokens.Silent by default: prompts include NO_REPLY so nothing is delivered.Two prompts: a user prompt plus a system prompt append the reminder.One flush per compaction cycle (tracked in sessions.json).Workspace must be writable: if the session runs sandboxed with
workspaceAccess: "ro" or "none", the flush is skipped.

1. **File:** docs/concepts/memory.md (L79-96)
2. ```markdown
3. ## Vector memory search
5. OpenClaw can build a small vector index over `MEMORY.md` and `memory/*.md` so
6. semantic queries can find related notes even when wording differs.
8. Defaults:
10. - Enabled by default.
11. - Watches memory files for changes (debounced).
12. - Configure memory search under `agents.defaults.memorySearch` (not top-level
13.   `memorySearch`).
14. - Uses remote embeddings by default. If `memorySearch.provider` is not set, OpenClaw auto-selects:
15.   1. `local` if a `memorySearch.local.modelPath` is configured and the file exists.
16.   2. `openai` if an OpenAI key can be resolved.
17.   3. `gemini` if a Gemini key can be resolved.
18.   4. `voyage` if a Voyage key can be resolved.
19.   5. Otherwise memory search stays disabled until configured.
20. - Local mode uses node-llama-cpp and may require `pnpm approve-builds`.

复制代码

File: docs/concepts/memory.md (L107-120)

1. ### QMD backend (experimental)
3. Set `memory.backend = "qmd"` to swap the built-in SQLite indexer for
4. [QMD](https://github.com/tobi/qmd): a local-first search sidecar that combines
5. BM25 + vectors + reranking. Markdown stays the source of truth; OpenClaw shells
6. out to QMD for retrieval. Key points:
8. **Prereqs**
10. - Disabled by default. Opt in per-config (`memory.backend = "qmd"`).
11. - Install the QMD CLI separately (`bun install -g https://github.com/tobi/qmd` or grab
12.   a release) and make sure the `qmd` binary is on the gateway’s `PATH`.
13. - QMD needs an SQLite build that allows extensions (`brew install sqlite` on
14.   macOS).

复制代码

File: docs/concepts/memory.md (L181-197)

1. - `searchMode` (default `search`): pick which QMD command backs
2.   `memory_search` (`search`, `vsearch`, `query`).
3. - `includeDefaultMemory` (default `true`): auto-index `MEMORY.md` + `memory/**/*.md`.
4. - `paths[]`: add extra directories/files (`path`, optional `pattern`, optional
5.   stable `name`).
6. - `sessions`: opt into session JSONL indexing (`enabled`, `retentionDays`,
7.   `exportDir`).
8. - `update`: controls refresh cadence and maintenance execution:
9.   (`interval`, `debounceMs`, `onBoot`, `waitForBootSync`, `embedInterval`,
10.   `commandTimeoutMs`, `updateTimeoutMs`, `embedTimeoutMs`).
11. - `limits`: clamp recall payload (`maxResults`, `maxSnippetChars`,
12.   `maxInjectedChars`, `timeoutMs`).
13. - `scope`: same schema as [`session.sendPolicy`](/gateway/configuration#session).
14.   Default is DM-only (`deny` all, `allow` direct chats); loosen it to surface QMD
15.   hits in groups/channels.
16. - When `scope` denies a search, OpenClaw logs a warning with the derived
17.   `channel`/`chatType` so empty results are easier to debug.

复制代码

File: docs/concepts/memory.md (L312-326)

1. Batch indexing (OpenAI + Gemini + Voyage):
3. - Disabled by default. Set `agents.defaults.memorySearch.remote.batch.enabled = true` to enable for large-corpus indexing (OpenAI, Gemini, and Voyage).
4. - Default behavior waits for batch completion; tune `remote.batch.wait`, `remote.batch.pollIntervalMs`, and `remote.batch.timeoutMinutes` if needed.
5. - Set `remote.batch.concurrency` to control how many batch jobs we submit in parallel (default: 2).
6. - Batch mode applies when `memorySearch.provider = "openai"` or `"gemini"` and uses the corresponding API key.
7. - Gemini batch jobs use the async embeddings batch endpoint and require Gemini Batch API availability.
9. Why OpenAI batch is fast + cheap:
11. - For large backfills, OpenAI is typically the fastest option we support because we can submit many embedding requests in a single batch job and let OpenAI process them asynchronously.
12. - OpenAI offers discounted pricing for Batch API workloads, so large indexing runs are usually cheaper than sending the same requests synchronously.
13. - See the OpenAI Batch API docs and pricing for details:
14.   - [https://platform.openai.com/docs/api-reference/batch](https://platform.openai.com/docs/api-reference/batch)

复制代码

File: docs/concepts/memory.md (L347-351)

1. Tools:
3. - `memory_search` — returns snippets with file + line ranges.
4. - `memory_get` — read memory file content by path.

复制代码

File: docs/concepts/memory.md (L354-360)

1. - Set `agents.defaults.memorySearch.provider = "local"`.
2. - Provide `agents.defaults.memorySearch.local.modelPath` (GGUF or `hf:` URI).
3. - Optional: set `agents.defaults.memorySearch.fallback = "none"` to avoid remote fallback.
5. ### How the memory tools work
7. - `memory_search` semantically searches Markdown chunks (~400 token target, 80-token overlap) from `MEMORY.md` + `memory/**/*.md`. It returns snippet text (capped ~700 chars), file path, line range, score, provider/model, and whether we fell back from local → remote embeddings. No full file payload is returned.

复制代码

File: docs/concepts/memory.md (L364-370)

1. ### What gets indexed (and when)
3. - File type: Markdown only (`MEMORY.md`, `memory/**/*.md`).
4. - Index storage: per-agent SQLite at `~/.openclaw/memory/<agentId>.sqlite` (configurable via `agents.defaults.memorySearch.store.path`, supports `{agentId}` token).
5. - Freshness: watcher on `MEMORY.md` + `memory/` marks the index dirty (debounce 1.5s). Sync is scheduled on session start, on search, or on an interval and runs asynchronously. Session transcripts use delta thresholds to trigger background sync.
6. - Reindex triggers: the index stores the embedding **provider/model + endpoint fingerprint + chunking params**. If any of those change, OpenClaw automatically resets and reindexes the entire store.

复制代码

File: docs/concepts/memory.md (L371-396)

1. ### Hybrid search (BM25 + vector)
3. When enabled, OpenClaw combines:
5. - **Vector similarity** (semantic match, wording can differ)
6. - **BM25 keyword relevance** (exact tokens like IDs, env vars, code symbols)
8. If full-text search is unavailable on your platform, OpenClaw falls back to vector-only search.
10. #### Why hybrid?
12. Vector search is great at “this means the same thing”:
14. - “Mac Studio gateway host” vs “the machine running the gateway”
15. - “debounce file updates” vs “avoid indexing on every write”
17. But it can be weak at exact, high-signal tokens:
19. - IDs (`a828e60`, `b3b9895a…`)
20. - code symbols (`memorySearch.query.hybrid`)
21. - error strings (“sqlite-vec unavailable”)
23. BM25 (full-text) is the opposite: strong at exact tokens, weaker at paraphrases.
24. Hybrid search is the pragmatic middle ground: **use both retrieval signals** so you get
25. good results for both “natural language” queries and “needle in a haystack” queries.

复制代码

File: docs/cli/memory.md (L21-28)

1. ```bash
2. openclaw memory status
3. openclaw memory status --deep
4. openclaw memory status --deep --index
5. openclaw memory status --deep --index --verbose
6. openclaw memory index
7. openclaw memory index --verbose
8. openclaw memory search "release checklist"

复制代码

File: docs/cli/memory.md (L37-38)

1. - `--agent <id>`: scope to a single agent (default: all configured agents).
2. - `--verbose`: emit detailed logs during probes and indexing.

复制代码

File: docs/help/faq.md (L1208-1217)

1. ### Memory keeps forgetting things How do I make it stick
3. Ask the bot to **write the fact to memory**. Long-term notes belong in `MEMORY.md`,
4. short-term context goes into `memory/YYYY-MM-DD.md`.
6. This is still an area we are improving. It helps to remind the model to store memories;
7. it will know what to do. If it keeps forgetting, verify the Gateway is using the same
8. workspace on every run.
10. Docs: [Memory](/concepts/memory), [Agent workspace](/concepts/agent-workspace).

复制代码

File: docs/help/faq.md (L1239-1246)

1. ### Does memory persist forever What are the limits
3. Memory files live on disk and persist until you delete them. The limit is your
4. storage, not the model. The **session context** is still limited by the model
5. context window, so long conversations can compact or truncate. That is why
6. memory search exists - it pulls only the relevant parts back into context.
8. Docs: [Memory](/concepts/memory), [Context](/concepts/context).

复制代码

File: docs/zh-CN/concepts/memory.md (L16-33)

1. # 记忆
3. OpenClaw 记忆是**智能体工作空间中的纯 Markdown 文件**。这些文件是唯一的事实来源；模型只"记住"写入磁盘的内容。
5. 记忆搜索工具由活动的记忆插件提供（默认：`memory-core`）。使用 `plugins.slots.memory = "none"` 禁用记忆插件。
7. ## 记忆文件（Markdown）
9. 默认工作空间布局使用两个记忆层：
11. - `memory/YYYY-MM-DD.md`
12.   - 每日日志（仅追加）。
13.   - 在会话开始时读取今天和昨天的内容。
14. - `MEMORY.md`（可选）
15.   - 精心整理的长期记忆。
16.   - **仅在主要的私人会话中加载**（绝不在群组上下文中加载）。
18. 这些文件位于工作空间下（`agents.defaults.workspace`，默认 `~/.openclaw/workspace`）。完整布局参见[智能体工作空间](/concepts/agent-workspace)。

复制代码

File: docs/zh-CN/cli/memory.md (L16-38)

1. # `openclaw memory`
3. 管理语义记忆的索引和搜索。
4. 由活跃的记忆插件提供（默认：`memory-core`；设置 `plugins.slots.memory = "none"` 可禁用）。
6. 相关内容：
8. - 记忆概念：[记忆](/concepts/memory)
9. - 插件：[插件](/tools/plugin)
11. ## 示例
13. ```bash
14. openclaw memory status
15. openclaw memory status --deep
16. openclaw memory status --deep --index
17. openclaw memory status --deep --index --verbose
18. openclaw memory index
19. openclaw memory index --verbose
20. openclaw memory search "release checklist"
21. openclaw memory status --agent main
22. openclaw memory index --agent main --verbose

复制代码

原文地址：https://blog.csdn.net/njsgcs/article/details/158128527