OpenClaw Memory: Files, Search and Embedding Models

11 min read

How OpenClaw memory works: MEMORY.md and daily notes, hybrid memory_search, embedding models, dreaming, and 8 memory plugins compared (OpenViking, Hindsight).

OpenClaw memory is a folder of Markdown files the agent writes and reads. MEMORY.md holds durable facts and decisions, USER.md holds your preferences, and dated daily notes hold running context. The first two load at session start. Everything is indexed in SQLite, and the agent finds older notes with memory_search, a hybrid of vector and keyword search.

OpenClaw is an open-source (MIT) personal AI assistant built by Peter Steinberger and contributors and now stewarded by the OpenClaw Foundation. It runs on your own machine and talks to you through WhatsApp, Telegram, Slack, Discord, iMessage and 20+ other channels. Facts on this page come from the official memory docs and memory search docs, checked October 2026. New to OpenClaw? Start with the OpenClaw guide for install, onboarding and the Gateway.

What is OpenClaw memory?

OpenClaw memory is file-based. The model remembers only what is written to disk as Markdown in the agent workspace. A memory plugin (memory-core by default) indexes those files and gives the agent tools to search and read them, so knowledge survives restarts, compaction and new sessions.

Because memory is plain text, you can open, edit, diff and back it up like any other file. That’s the main difference from memory layers that keep facts inside a database. For the general pattern, see AI agent memory explained.

The memory files

FileWhat goes in itWhen it loads
MEMORY.mdCurated long-term facts and decisionsAt session start
USER.md (optional)Stable preferences, style, relationships, active projectsAt session start, with a smaller budget
memory/YYYY-MM-DD.mdDaily notes and running contextToday’s and yesterday’s on a bare /new or /reset; otherwise via search
memory/YYYY-MM-DD-<slug>.mdSlugged daily notes, such as from the session-memory hookSame as daily notes
DREAMS.md (optional)Dreaming summaries for human reviewNot injected

The workspace defaults to ~/.openclaw/workspace. If MEMORY.md grows past the bootstrap budget, the file on disk stays whole but the injected copy is truncated. /context list, /context detail and openclaw doctor show sizes and truncation.

The docs add a useful rule for notes that affect actions: record when it’s safe to act (approval needed, expiry, who said so), not just the fact. They also say plainly that memory “guides behavior but does not enforce policy.” Hard limits belong in approval settings and sandboxing.

Importing memory from other agents

The Control UI has Settings → Import Memory. It copies Markdown memory from Codex (~/.codex/memories), Claude Code (~/.claude/projects/*/memory) and Hermes (MEMORY.md and USER.md) into memory/imports/. Imports are searchable but aren’t merged into MEMORY.md, and a backup is made first.

How memory_search works

The default memory-core plugin gives the agent three tools:

  • memory_search: semantic search over notes, optionally also session transcripts.
  • memory_get: read a specific file or line range.
  • intent: create, list or cancel event-triggered standing intents.

With an embedding provider configured, search is hybrid. A vector search (meaning) and a BM25 keyword search (exact tokens like IDs, env vars and code symbols) run in parallel, plus a filename search. If one path fails, the other runs alone.

The final score multiplies three things: hybrid relevance, a recency decay and an importance score set at write time. Decay has a 30-day half-life, so a note from last month counts half as much. MEMORY.md, USER.md and undated files never decay. A fixed MMR step (lambda 0.7) then removes near-duplicate snippets so results aren’t five copies of one note.

Transcripts are opt-in: add "sessions" to sources and set experimental.sessionMemory: true. For more on how ranking by time works in memory systems, see temporal reasoning in AI memory.

Which embedding model OpenClaw uses

OpenAI is the default embedding provider. You change it with memory.search.provider:

ProviderConfig IDAPI keyDefault model or note
OpenAIopenaiDependsAPI key or eligible Codex OAuth
GeminigeminiYesgemini-embedding-2 for multimodal (image and audio)
VoyagevoyageYesvoyage-4-large
MistralmistralYesmistral-embed
DeepInfradeepinfraYesBAAI/bge-m3
BedrockbedrockNoAWS credential chain
GitHub Copilotgithub-copilotNoCopilot subscription
LocallocalNoManaged llama.cpp GGUF, about 0.3 GB
Ollama / LM Studioollama / lmstudioNoYour local model
OpenAI-compatibleopenai-compatibleUsuallyAny /v1/embeddings endpoint

Set none for keyword-only search, or auto to let OpenClaw pick and fall back to keywords if embeddings fail. For local embeddings, install @openclaw/llama-cpp-provider; OpenClaw then installs llama-server and downloads the GGUF for you.

How to pick: stay on the default if you already use OpenAI. Use local or Ollama if notes must never leave the machine. Use Gemini if you want images and audio indexed. Changing provider or model means rebuilding the index with openclaw memory index --force, because vectors from different models aren’t comparable. Background on choosing models is in embedding models for RAG.

Flush, dreaming and compaction

Two background processes keep memory current:

  1. Memory flush. Before compaction shrinks the conversation, OpenClaw runs a silent turn asking the agent to save anything important. It’s on by default. You can turn it off with agents.defaults.compaction.memoryFlush.enabled: false or point it at a cheaper model such as ollama/qwen3:8b. Read-only sandbox sessions skip it.
  2. Dreaming. A recurring job scores short-term recall signals and promotes items into MEMORY.md only if they pass score, frequency and query-diversity thresholds. Untrusted and system-derived candidates are excluded. Summaries go to DREAMS.md for you to review. Disable it with plugins.entries.memory-core.config.dreaming.enabled: false.

Dreaming is OpenClaw’s version of memory consolidation: turning a pile of daily notes into a small set of durable facts.

Memory engines and plugins

The memory slot is pluggable, and since some plugins also take over context assembly, there are three places a memory option can sit: the memory slot, the contextEngine slot, or beside both.

OptionSlotWhere memory livesWhat it adds
Builtin memory-core (default)MemorySQLite in the workspaceKeyword, vector and hybrid search over Markdown notes; no extra dependencies
memory-core on PostgreSQLMemoryYour PostgreSQL agent databaseSame search; needs unaccent, pg_trgm and, for vectors, pgvector
HonchoMemory (plugin)Honcho serverCross-session user modeling, semantic search, multi-agent awareness
LanceDBMemory (plugin)LanceDBOpenAI-compatible or local Ollama embeddings, auto-recall, auto-capture
Memory Wiki (bundled)Beside memoryWiki vaultClaims with evidence, contradiction and freshness tracking; doesn’t replace the memory plugin
OpenVikingContext engineOpenViking server (viking:// tree)Session archiving and summaries, recall before every reply, owns compaction
Mem0Memory (plugin)Mem0 Platform or self-hostedExtracted facts instead of file search
HindsightMemory (plugin)Hindsight Cloud, your server, or a local embedded daemonExtracted facts, consolidated observations, reflect

Sources: the OpenClaw memory docs for the first five rows (checked 24 October 2026), OpenViking’s OpenClaw integration guide, and each vendor’s plugin listing.

The PostgreSQL option is the newest built-in choice. SQLite stays the default, but memory-core can index and search a PostgreSQL agent database instead. Keyword-only search works with memory.search.provider: "none" and then doesn’t need the vector extension.

OpenViking works differently from the rest. Its plugin (openclaw plugins install clawhub:@openviking/openclaw-plugin, OpenClaw 2026.5.27 or later, Node.js 22+) occupies OpenClaw’s contextEngine slot. Before each turn it builds the model’s context from a server-side session summary, recent messages, the user profile and recalled memories. After each turn it captures the conversation and commits it to the OpenViking server once pending tokens pass half the token budget. It also sets ownsCompaction: true, so OpenViking, not OpenClaw, does compaction. A peer_role setting decides whether memory is shared per user or split per assistant or per sender. The OpenViking page covers the server itself.

OpenViking’s own May 2026 benchmark post reports OpenClaw going from 24.20% on LoCoMo with native memory to 82.08% with the plugin, using 91.0% fewer input tokens. Those are the project’s own numbers: the judge and answer models aren’t stated, and the baseline is OpenClaw’s file memory, not another memory system.

Mem0 (@mem0/openclaw-mem0 on ClawHub) and Hindsight (@vectorize-io/hindsight-openclaw) replace file search with an extraction-based store. Like OpenViking, they add LLM calls per turn, so they’re worth it mainly when the agent has months of history that daily notes and MEMORY.md no longer cover.

For that months-of-history case, Hindsight has the strongest published numbers: on the long-history BEAM benchmark it leads Mem0 73.9 to 64.1 at 1M tokens and 64.1 to 48.6 at 10M, per Mem0’s own comparison (vendor-run). It also does what dreaming does, in the background: related facts merge into evidence-backed observations that get refined rather than overwritten. Its plugin’s setup wizard (openclaw plugins install @vectorize-io/hindsight-openclaw) offers Hindsight Cloud, your own server, or an embedded local daemon, which can run on Ollama to keep everything on the machine. The cost is more LLM calls on every write and more context per recall than Mem0. Memory also moves out of Markdown files you can read and edit into a database.

What changed in the OpenClaw plugin (Hindsight v1.2.0, 3 November 2026). The plugin now gives OpenClaw the same three tools as the Hermes plugin, hindsight_retain, hindsight_recall and hindsight_reflect, with the same names and parameters (#5965). A memoryMode setting picks hybrid (the default: automatic recall plus tools), context (automatic recall only) or tools (tools only). Seven knowledge-base tools were added, and deleting needs allowKnowledgeDelete: true (#6004). Cron, heartbeat and sub-agent sessions stay out of memory unless you set skipOperationalSessions: false (#5963). Source: the Hindsight v1.2.0 release notes, read 2026-11-05. The same release’s retry change (failed saves re-sent up to 5 times, held in memory only) is in the Hermes plugin’s notes; the OpenClaw plugin’s retry behavior is not in them, so check it before you rely on it.

What changed in OpenClaw 2026.10.10 (November 2026)

OpenClaw 2026.10.10 shipped on 3 November 2026. Its changelog has a long “Memory and search” section. Two changes can make memory behave differently after you upgrade: search ranking moved, and new conversation text takes longer to become searchable.

ChangeWhat you noticeWhat to doSource
Hybrid search gives weak keyword overlap less weight than a closer match in meaningResults reorder; rare IDs or filename matches can move downIf you set a minimum search score, lower it when useful results disappear#177450, #167004
Natural-language fallback when strict body and filename searches find nothing; keyword matches outside the first vector window can scoreQuestions that used to return nothing can now find notesNothing#161165
Relevant older dated notes stay eligible despite recency decayOld daily notes show up again, though newer ones may still rank firstNothing#168692
Session transcripts are indexed after a quiet period, not during active turns; searches use the published indexSomething said a moment ago may not be in memory_search yetWait for the agent to go idle, or check openclaw memory status#170404
Growing transcripts only embed and write changed chunks; mostly unchanged sources reuse vectorsLess re-embedding work on long sessionsNothing#103201, #171402
A failed rebuild keeps the previous usable index; failed full reindexes retry with backoffSearch keeps working during a broken rebuild instead of going emptyFix the embedding error; openclaw doctor explains it#168263, #138786
Invalid, empty or all-zero query embeddings now show an error or Gateway warningBefore, vector matches were silently droppedCheck the embedding service and retry#168263, #183475
A query embedding with the wrong vector size errors with an agent-specific force-rebuild commandClear error after a model change instead of bad resultsRun the rebuild command it prints#168465
Memory embeddings follow the provider’s private-network rules, including redirectsA self-hosted embedding server on a private address can be refusedAllow that route explicitly on the embedding provider’s ID#169847, #170173
Private memory reads enforce role and admin checks; owner sessions and cross-agent subagents get access backAutomations linked to older chats can read memory againNothing#181359
Memory Wiki keeps handwritten text inside the marked Notes section when regenerating concept pagesHand edits outside that section on older generated pages are not protectedMove hand edits into the Notes section#175707

The changelog is careful to say the ranking change is “not a guarantee that every exact match comes first”. The report on exact recall is still open. If your agent looks up exact tokens such as ticket numbers or env var names, test those queries after upgrading.

OpenClaw 2026.11.1 (5 November 2026)

The next stable release, 2026.11.1, has no new memory features. It fixes how long conversations survive compaction and how big transcripts are read, which is what memory search and the memory flush work from.

ChangeWhat you noticeSource
Compaction keeps the human request that is still being worked on, across repeated summaries. Before, a later internal update (a tool result, a background run) could replace it, or finished work could come backAfter several compactions in one long task, the agent still knows what you asked for#180214
Memory indexing waits until an archived transcript is fully written before indexing itOld sessions are indexed from the complete text, not a half-written copyrelease notes
Very long transcripts are read in pages instead of all at once (earlier failures at 8 MiB, worker out-of-memory on “Resume in new session”)Big sessions resume and load instead of crashing#188450, #182091, #190690

None of these change ranking or what gets saved, so there is nothing to re-test after upgrading. The search changes in 2026.10.10 above still apply.

Useful commands and fixes

1openclaw memory status          # index status and active provider
2openclaw memory search "query"  # search from the command line
3openclaw memory index --force   # rebuild the index

If search returns nothing, check that the files aren’t empty, that the provider is set, then force a reindex. The docs also suggest a reindex when CJK text isn’t found. If the agent ignores something you know is in MEMORY.md, check for truncation with /context detail. To compare OpenClaw with Nous Research’s agent, see OpenClaw vs Hermes Agent memory.