OpenClaw memory search

The memory search tool finds relevant notes from an agent’s memory files even when the wording differs from the original text: it chunks memory into small pieces and searches them with embeddings, keywords, or both. OpenAI embeddings are the default and a dozen providers are supported, including a managed local one with no API key. Here is how a search runs, the ranking the docs spell out, the trigger recall that runs before a reply, the fallback rules, session memory, and the troubleshooting list.

Providers and the two paths

• The provider key names one of OpenAI, Gemini, Voyage, Mistral, Bedrock, DeepInfra, GitHub Copilot, Ollama, LM Studio, a generic OpenAI-compatible endpoint, or local, which installs a verified llama.cpp server and a small embedding model of about a third of a gigabyte; a custom provider entry works too when it uses a supported API kind.
• Two retrieval paths run in parallel and merge: vector search matches similar meaning, so a query about the Gateway host finds a note about the machine running OpenClaw, and BM25 keyword search matches exact terms such as ids, error strings and config keys. If only one path is available, the other runs alone.
• Filename search indexes paths separately from bodies, so an exact path, basename or stem ranks ahead of partial matches while snippets still come from note content.
• Some OpenAI-compatible endpoints need asymmetric input types for queries and documents, which two config keys set.

Old notes gradually lose ranking weight so recent information surfaces first.

The ranking

The builtin engine applies a deterministic formula, hybrid relevance times recency decay times an importance multiplier. Importance is scored once when an entry is written by a memory workflow that already has a model in the loop, and a missing score is neutral. Dated daily notes decay with a thirty-day half-life, so last month’s note scores at half its original weight, while the curated memory and user files and undated files stay evergreen. The docs credit the relevance, recency and importance result in the Generative Agents paper, without adding a query-time model call. A diversity pass then reorders the scored candidates to reduce near-identical snippets, with a fixed relevance-biased setting and a bounded candidate pool, without changing scores or calling a provider. Keyword matches are preserved when every ranked result falls below the configured minimum score, and hybrid search fills remaining slots with keyword-only hits.

Trigger recall and the fallback rules

• On eligible interactive turns the engine compares the inbound message with short trigger phrases stored on indexed entries and can add up to three compact entries to hidden context before the reply; only promoted, trusted entries from the root memory and user files qualify, and daily notes, imported and session transcripts are never injected automatically.
• Setting the provider to none disables embeddings on purpose for keyword-only search; leaving it unset or on auto falls back to keyword-only ranking when embedding setup or a request fails, as does the local provider, and indexing still records text for keyword search before the first search.
• Naming any other provider explicitly and having it fail at request time makes the tool report memory as unavailable instead of silently degrading, which keeps a broken configuration visible; the fix is the provider or auth configuration, or none for deliberate keyword-only recall.

OpenClaw memory explained explains the files being searched, and OpenClaw dreaming the nightly sweep that decides what gets promoted into them and therefore what trigger recall may inject.

Session memory and troubleshooting

Exact full-text recall from transcripts belongs to the sessions search tool; indexing transcripts into memory search is opt-in through an experimental flag and a sources list, with a corpus option to search notes only, visibility settings that default to all, and cross-agent access governed by the agent-to-agent setting. Images and audio can be indexed alongside Markdown with one Gemini embedding model, but only under extra paths, not the default memory roots. When there are no results, check the index status and rebuild it; when only keyword matches come back, the embedding provider is probably not configured, which the deep status shows; when local embeddings time out, inspect the managed server endpoints before rebuilding; and CJK text that cannot be found needs a forced index rebuild. OpenClaw local models covers the local models the local providers sit beside, and OpenClaw sessions the transcripts the opt-in indexes.

On Diali

On Diali memory search runs with whatever embedding provider your model key gives it and falls back to the keyword path the docs describe when there is none; either way the notes live in the assistant’s persistent workspace. Hosted OpenClaw on Diali is the assistant.

• Vector for meaning, BM25 for exact terms, merged.
• Relevance times recency times importance; daily notes halve every thirty days.
• A broken explicit provider is reported, never hidden.