OpenClaw Memory Search: Setup, Indexing, and Troubleshooting

A dirty memory index is not automatically a broken memory index. Treat OpenClaw memory search as four linked contracts: source scope, index identity, retrieval behavior, and source fidelity. Inspect all four before forcing a rebuild. On the installation measured for this review, the index was marked dirty while its identity remained valid, both FTS and vector search were available, and exact plus semantic probes returned verifiable source passages.

The tempting diagnosis is “stale vectors.” That label is convenient and often wrong. A changed Markdown file can make an otherwise valid index dirty for a short interval. The same status can also accompany a growing transcript source. Neither condition proves that embeddings are incompatible or that recall is unusable.

The useful question is narrower: which contract failed? If no files are in scope, rebuilding produces another empty index. If provider identity changed, waiting for a file watcher will not validate the migration. If a semantic query works but an exact identifier does not, the problem sits in retrieval, not ingestion. If the result cannot be opened at its cited lines, a high relevance score is beside the point.

The dirty index that still answered correctly

A read-only probe on OpenClaw 2026.7.1-2 found the builtin memory engine using OpenAI text-embedding-3-large. The index held 1,754 files and 12,069 chunks. Its dirty flag was true, yet the index identity was valid, the embedding probe passed, sqlite-vec was available at 3,072 dimensions, FTS was available, and semantic search was available. A separate scan reported no source issues.

The source mix mattered. Workspace memory contributed 461 files and 3,847 chunks. Opt-in session transcripts contributed another 1,293 files and 8,222 chunks. A status total without that split would hide the fact that transcripts—not curated Markdown—made up most of the retrieval corpus.

The correct response was observation, not repair. No forced index, config edit, provider switch, or file mutation was needed to establish the current behavior.

Validation before repair

Three queries tested different properties while retaining only hashes, scores, result counts, and source-verification booleans. The exact operational phrase returned one result at 0.635070. A paraphrase of the same decision returned one result at 0.549854. Both results included line ranges and matched an accessible source file. An opaque fabricated token, queried with a 0.85 threshold, returned nothing.

Those numbers are not portable quality grades. Scores depend on provider, model, fusion weights, corpus composition, and query. Their value here is comparative: exact and semantic formulations both found grounded evidence, while a deliberately absent identifier did not cross the negative gate.

A score without a readable source is not evidence.

Retrieval is a four-contract system

This model prevents category errors. “No results” can mean an empty source scope, invalid identity, unavailable provider, an overly strict threshold, or a genuinely absent fact. “Wrong result” can mean noisy notes, redundant transcripts, weak headings, poor chunk boundaries, or a query that depends on an identifier the notes never retained. The same symptom does not justify the same repair.

Markdown deserves an editorial policy

MEMORY.md is the compact, curated layer: stable preferences, standing decisions, durable project facts, and short lessons worth loading at session start. Dated files under memory/ carry the working layer: evidence, blockers, links, commit IDs, unresolved questions, and handoffs. The split protects prompt budget without sacrificing recall.

A good operational note records a condition, not merely a claim:

## Release handoff
- Owner: backend release session
- State: migration reviewed; implementation not merged
- Safe now: inspect the plan and run read-only checks
- Do not: edit production migrations from this thread
- Unlock: approved PR reaches main

That note is longer than “migration approved,” but far safer. It preserves authority, timing, and the action to avoid. It also gives keyword search stable nouns while semantic search can match a paraphrase such as “what blocks the database rollout?”

Repeated status dumps work against both humans and ranking. Keep raw logs in their operational system. Summarize the decision-changing facts once, use specific headings, retain uncommon identifiers intact, and remove stale instructions when their unlock condition has passed.

Testing both halves of hybrid search

OpenClaw’s builtin engine runs vector and keyword paths, then merges the candidates. Test them separately in spirit even when one CLI call performs the fusion.

A negative query should be genuinely opaque. Hyphenated phrases that contain common words or dates can activate keyword fallback and return low-scoring but lexically related candidates. That is not hallucinated memory; it is a poor negative fixture. Use an uncommon single token, record the threshold, and inspect the source before declaring a leak.

Troubleshooting when the symptom lies

Dirty but searchable

Check index identity, provider readiness, source counts, and a known query. If those pass, allow the normal watcher to settle before reaching for --force. A rebuild is expensive evidence destruction during an incident: it removes the ability to distinguish a delayed watcher from a bad vector space.

Valid identity, irrelevant ranking

Rebuilding the same corpus with the same settings usually reproduces the same ranking. Inspect duplicate notes, vague headings, oversized daily files, transcript volume, hybrid weights, MMR, temporal decay, and whether the query depends on missing exact terms.

Keyword works, paraphrase fails

The FTS path may be healthy while embeddings are unavailable or stale. Run deep status, inspect the provider probe, and confirm semantic availability. An explicitly configured remote provider fails visibly when unavailable; deliberate keyword-only operation uses provider: "none".

Paraphrase works, identifier fails

Preserve the identifier as plain contiguous text, then confirm FTS availability. Markdown decoration or line breaks can make an exact token harder to match. Do not weaken semantic thresholds to solve a keyword-ingestion problem.

The source cannot be opened

First distinguish workspace-memory paths from session transcript hits. The active memory plugin owns both tools, but the underlying sources and visibility rules differ. A result with no readable evidence should not become a production claim.

Verify the migration boundary

A provider, model, dimension, chunking, source, or scope change is an index migration. The builtin engine tracks an identity for that configuration and can reindex automatically when it changes. Operationally, still treat the change as a planned migration: capture the before state, change one contract, rebuild or wait for the documented reindex, then rerun the exact/semantic/source/negative matrix.

openclaw memory status --agent main --deep --json
openclaw memory index --agent main --force
openclaw memory search --agent main --json "known exact token"

--force is appropriate after a deliberate identity change or when a watcher has demonstrably stalled. It is not a diagnostic reflex. Do not edit SQLite metadata to silence an identity mismatch; that preserves incompatible vectors under a reassuring label.

Session transcripts change the privacy model

Workspace memory and session recall are different sources. Session transcripts are opt-in through experimental.sessionMemory plus the sessions source. Their results also obey tools.sessions.visibility. The default tree visibility exposes the current session and its descendants; broader same-agent recall requires an explicit visibility change.

The measured corpus illustrates the tradeoff: session chunks outnumbered curated memory chunks by more than two to one. That can improve continuity, but it also increases embedding cost, storage, ranking competition, and the amount of conversational data eligible for retrieval. Enable it because the workflow needs cross-session recall—not because a larger corpus looks healthier.

For shared or multi-user agents, keep personal durable facts out of a broadly shared workspace. Narrow the session visibility to the smallest useful scope. A search feature should never become an accidental audience expansion.

Operator handoff: the evidence worth keeping

• The active agent and workspace path are named.
• The configured sources are recorded separately for memory and sessions.
• Provider, model, vector dimensions, FTS availability, and index identity are captured.
• Dirty state is interpreted alongside source counts and a known retrieval probe.
• One exact query and one semantic paraphrase lead to verifiable source passages.
• An opaque negative token returns no result above the chosen threshold.
• Important notes retain owners, safe actions, forbidden actions, and unlock conditions.
• Secrets, raw authorization headers, customer payloads, and unnecessary transcript excerpts are absent.
• A forced rebuild is tied to an identity migration or a demonstrated watcher failure.

The decision for the inspected installation was deliberately boring: do not rebuild merely because dirty is true. The identity was valid, every retrieval subsystem was available, exact and semantic evidence resolved to readable sources, and the negative fixture stayed empty. The pending state should be observed and rechecked; repair begins only if one of those contracts degrades.

For a managed agent runtime, deploy an AI agent on GolemWorkers. For adjacent operating boundaries, see OpenClaw session isolation and OpenClaw configuration validation.

The primary record behind this retrieval contract

• OpenClaw memory overview — durable files, search tools, action-sensitive notes, and memory backends.
• Builtin memory engine — FTS5, vector search, hybrid retrieval, index identity, file watching, and rebuild behavior.
• Memory search — provider selection, hybrid fusion, temporal decay, MMR, session sources, and failure semantics.
• Memory CLI — status, deep provider probes, indexing, search thresholds, source counts, and promotion commands.