OpenClaw Memory: How It Works, Where It Breaks, and How to Make It Persistent

Does OpenClaw have memory? Yes, and more of it than most agent frameworks: OpenClaw ships with a layered memory model built on plain markdown files, a consolidation pass it calls dreaming, and a pre-compaction flush so that nothing important is lost when a long conversation is summarised. The design is deliberately simple to read and edit. The cost of that simplicity shows up once an agent runs for weeks, serves more than one person, or needs to answer "why did we decide this?" rather than "what did we do today?". This guide explains the built-in OpenClaw memory system, its limits, and how to extend it with a memory engine that keeps the files but adds retrieval, structure and sharing.

How does OpenClaw memory work?

OpenClaw keeps everything it remembers in a workspace directory (by default ~/.openclaw/) as markdown. The agent loads a fixed subset of those files into its system prompt at session start and appends to others as it works. There are four files that matter:

A session therefore starts with the user profile, the curated memory, and the last two days of logs. Everything else is on disk but not in context unless the agent searches for it. That search is the second half of the model.

Memory search in OpenClaw

OpenClaw indexes the memory directory into a local SQLite database and exposes a hybrid search over it: full-text match plus an embedding similarity score, merged into one ranked list. The agent calls it as a tool when a question is not answered by what is already in the prompt. Pluggable memory engines sit behind the same interface; the default is the local SQLite index, and LanceDB and Honcho are available as alternatives for larger stores or hosted user modelling. A memory-wiki mode turns the directory into a browsable set of linked pages for people rather than for the agent.

Dreaming: how OpenClaw consolidates memory

Daily logs grow without bound, so OpenClaw runs a periodic consolidation pass. Dreaming reads recent memory/*.md files, decides what is worth keeping, rewrites MEMORY.md with the promoted facts, and records what it did in DREAMS.md. It is the mechanism that stops MEMORY.md from becoming a dump of every log line, and the reason OpenClaw agents feel like they improve over time even though every session still starts from files.

The pre-compaction memory flush

Long conversations get compacted: older turns are summarised to free context. Before OpenClaw compacts, it triggers a memory flush, prompting the agent to write anything in the soon-to-be-summarised turns that should survive into today's log. This closes the gap that most agents have, where a decision made in turn 40 is silently lost when turns 1 to 60 are collapsed into a paragraph.

Importing memory from other agents

OpenClaw can import memory exported from Codex, Claude Code and Hermes Agent, mapping their notes into MEMORY.md and the daily logs. That makes it a reasonable place to consolidate if you are moving between tools, and it is also a hint about the model's limits: the import is a copy, not a shared store, so the two agents drift apart from the moment it runs.

Where is OpenClaw memory stored?

Everything is local by default:

• ~/.openclaw/openclaw.json holds configuration, including which memory engine is active and plugin settings.
• ~/.openclaw/USER.md, MEMORY.md, DREAMS.md and memory/ hold the content described above; workspaces can override the location per agent.
• The SQLite index (or the LanceDB directory) sits alongside the memory files and can be deleted and rebuilt at any time; the markdown is the source of truth.

Because memory is files, it is trivially inspectable, diffable and backed up with the rest of the workspace. That is a genuine advantage over agents that keep memory in an opaque hosted store.

What are the limits of OpenClaw's built-in memory?

The limits follow from the design rather than from bugs.

• Prompt-bound by default. USER.md, MEMORY.md and two days of logs are loaded on every turn. As they grow, they compete with the actual task for context, and the only lever is to let dreaming prune harder, which means losing detail.
• One agent, one memory. Memory is a directory owned by one agent on one machine. Two OpenClaw agents, or OpenClaw and Claude Code, do not share a store unless you sync files by hand or run an import, which copies rather than shares.
• Flat facts. MEMORY.md is prose. "We moved billing to Stripe" and "billing uses Paddle" can both be true in the file at once, and search returns whichever matches the query better. There is no notion of one fact superseding another, or of when each was true.
• Search over text, not over structure. Hybrid search finds passages that look like the question. It cannot answer "what depends on the auth service" or "which decisions involved this customer" because the files do not record relationships, only sentences.
• Lossy consolidation. Dreaming is an LLM rewriting a file. It is good at promoting the obvious and quietly bad at keeping the long tail: the one-off incident, the rejected approach, the reason behind a constraint.
• No code memory. OpenClaw agents write and run code constantly, but nothing in the memory model understands a repository. Codebase knowledge is re-derived by reading files each session.

For a personal assistant with a small memory, none of this matters. For an agent that runs a company workflow, a support queue or a codebase, each item becomes a weekly annoyance.

How to give OpenClaw persistent graph memory with cognee

cognee is an open-source (Apache 2.0) memory engine that turns what an agent stores into a knowledge graph plus a vector index and returns the relevant part on request. The @cognee/cognee-openclaw plugin wires it into OpenClaw as an additional memory layer: the markdown files stay, and cognee becomes the place where memory is structured, searched and shared.

1. Install the plugin and run setup

openclaw plugins install @cognee/cognee-openclaw
openclaw cognee setup

openclaw cognee setup starts a local cognee server, writes the plugin configuration into ~/.openclaw/openclaw.json, and registers the memory tools. The default baseUrl is http://localhost:8011, and the plugin manages that server itself, so there is nothing to run by hand. Point baseUrl at a self-hosted instance or at Cognee Cloud instead if memory should live somewhere other than the laptop. Full options, including the API key and dataset settings, are in the OpenClaw integration docs.

2. Choose how it interacts with OpenClaw's own memory

The plugin has two modes. In the default mode it replaces the memory search path: recall comes from cognee, and the markdown files remain as OpenClaw's working notes. openclaw cognee setup --hybrid keeps OpenClaw's native engine active alongside cognee, so both are searched and merged. Hybrid is the safer first step for an agent with months of existing logs; the default mode is cleaner once cognee has indexed them.

Two hooks control the automatic behaviour, both set in openclaw.json:

{
  "plugins": {
    "cognee": {
      "baseUrl": "http://localhost:8011",
      "allowPromptInjection": true,
      "allowConversationAccess": true
    }
  }
}

allowPromptInjection lets the plugin run a recall before each prompt and insert the results into the context inside a <cognee_memories> block, so the agent sees relevant memory without calling a tool. allowConversationAccess lets the plugin capture the conversation after each turn and store what is new, with redaction applied to secrets and configurable patterns before anything is written. With both on, memory becomes automatic in the same way OpenClaw's logs are, but with retrieval rather than a fixed preamble.

3. Use the tools, or let the agent use them

The plugin registers six tools:

In practice the agent calls memory_search when the injected context is not enough, and memory_recap when asked "what do you know about X". memory_forget matters for compliance: a deletion removes the document and the graph nodes built from it, not just the text match.

4. Scope memory: company, user, agent

This is the part the file model cannot do. The plugin organises memory into datasets with three scopes:

• Company datasets hold shared knowledge: product facts, policies, customer context. Every agent in the organisation can read them; writes are controlled by permissions.
• User datasets hold what one person has told their agents: preferences, projects, history. They follow the user across agents.
• Agent datasets hold an individual agent's own working memory: what it tried, what worked, lessons it distilled.

A recall searches the scopes the current agent is allowed to see and merges the results. One OpenClaw agent handling support and another handling engineering share the company dataset and keep their own agent datasets; a new agent starts with everything the organisation knows on day one. memory_switch_dataset moves the write target when an agent works on a different project.

5. Index the repositories the agent works on

openclaw cognee index-repo /path/to/repo

This builds a code graph of the repository: files, functions, classes, calls and imports, extracted deterministically without LLM calls or embeddings, so it is fast, cheap and reproducible. After indexing, memory_code_search answers structural questions exactly: who calls a function, what a module depends on, what changes if a symbol is removed. For an OpenClaw agent that ships code, this replaces the re-reading it would otherwise do every session. The codebase memory guide covers what to index and how to keep it current.

What changes compared with files alone

Self-hosting is free; Cognee Cloud has a free tier (1M tokens, 1 workspace) and a Standard plan at $1.00 per 1M tokens processed plus $5 per additional workspace, as of October 2026. The managed setup for OpenClaw is on the Cognee Cloud OpenClaw page, and the local UI lets you browse what the agent has stored.

OpenClaw memory best practices

• Keep USER.md short and true. It loads on every turn. Preferences and constraints belong there; history does not.
• Let dreaming run, and read DREAMS.md occasionally. It is the only record of what was dropped. If something important keeps disappearing, that is the signal to move it into a store that does not prune.
• Treat MEMORY.md as the agent's README, not its database. Standing instructions and a dozen key facts. Everything with a date, a reason or a relationship goes into graph memory where it can be retrieved by meaning and linked to its context.
• Scope before you scale. Decide which facts are company, user and agent before the second agent exists. Retrofitting scopes onto a year of mixed memory is slow.
• Index repositories the agent edits. Decision memory without code memory still makes the agent re-learn the codebase every day.
• Review redaction rules before enabling conversation capture. The plugin redacts secrets by default; add patterns for anything domain-specific (account numbers, internal hostnames) before turning allowConversationAccess on for a shared dataset.
• Keep memory where the data is allowed to be. The auto-managed local server keeps everything on the machine. Use a self-hosted or VPC deployment for shared company datasets; the self-hosted vs VPC vs managed guide walks through the choice.

Hermes Agent memory describes a very similar file-based model and the same extension path; Claude Code memory, Codex memory and Cursor memory cover the coding agents OpenClaw often works next to, and all of them can share one cognee instance. MCP memory explains the protocol-level version of the same pattern. For earlier, more narrative looks at OpenClaw, see what OpenClaw is and how we gave it memory and three OpenClaw agents worth building with cognee. For the concepts behind all of this, see agent memory.

FAQ

Does OpenClaw have persistent memory?+

Yes. OpenClaw stores memory as markdown files in its workspace: USER.md, MEMORY.md, daily memory/YYYY-MM-DD.md logs and DREAMS.md. The user profile, curated memory and recent logs are loaded into every session, and a hybrid search over the rest is available as a tool. It is persistent across sessions on the same machine; it is not shared between agents or machines without syncing files.

Where does OpenClaw store memory?+

In the workspace directory, ~/.openclaw/ by default, next to openclaw.json. The memory files are plain markdown; the search index is a local SQLite database (or a LanceDB directory if that engine is selected) built from them and rebuildable at any time. The cognee plugin stores graph memory in the cognee server it points at, http://localhost:8011 by default.

What is dreaming in OpenClaw?+

Dreaming is OpenClaw's memory consolidation pass. It reads recent daily logs, promotes facts worth keeping into MEMORY.md, merges duplicates, drops noise, and writes a record of what it did to DREAMS.md. It keeps the curated memory small enough to load on every turn, at the cost of discarding detail that an LLM judged unimportant.

How do I clear or reset OpenClaw memory?+

Edit or delete the markdown files in the workspace and rebuild the index; the files are the source of truth. To remove a single fact from cognee memory, call memory_forget, which deletes the document and the graph knowledge derived from it. To start a fresh scope without deleting anything, use memory_switch_dataset.

Can OpenClaw share memory with Claude Code or Codex?+

Not natively. OpenClaw can import memory exported from Claude Code, Codex and Hermes Agent, but that is a one-time copy. If OpenClaw and the other agents all connect to the same cognee instance, they read and write one memory, with company, user and agent scopes controlling who sees what.

What is the difference between the default and hybrid mode of the cognee plugin?+

In the default mode cognee handles memory search and OpenClaw's markdown files remain as working notes. openclaw cognee setup --hybrid keeps OpenClaw's native engine active alongside cognee and merges results from both. Hybrid is a safe first step with a large existing memory; the default is simpler once cognee has indexed it.

Can OpenClaw remember my codebase?+

Not with the built-in files; it re-reads code each session. With the cognee plugin, openclaw cognee index-repo builds a code graph of the repository and memory_code_search answers structural questions such as callers, dependencies and the impact of a change. See the codebase memory guide.