--- title: "How OpenClaw's memory works" description: "OpenClaw memory, from the official docs: the Markdown files that persist, what loads at session start, the documented caps, and the dreaming sweep." canonical: https://past.dev/blog/openclaw-memory date: 2026-09-03 category: Research authors: The past.dev team --- # How OpenClaw's memory works OpenClaw stores memory as plain Markdown files in the agent's workspace: a curated `MEMORY.md` for durable facts, dated notes under `memory/`, and an optional `USER.md` profile ([memory overview](https://docs.openclaw.ai/concepts/memory)). The curated file loads at session start, recent daily notes load on reset, and everything older is retrieved on demand through a search tool. A background process the docs call dreaming promotes material from the daily notes into `MEMORY.md`. The OpenClaw memory model has one governing rule, stated in the docs: the model only remembers what gets saved to disk, and there is no hidden state. This post documents that model as of September 2026, from the official documentation and repository ([openclaw/openclaw](https://github.com/openclaw/openclaw)). ## Does OpenClaw have memory? Yes. OpenClaw is an open-source personal AI agent, and file-based persistence is part of its core design rather than a plugin afterthought ([repo](https://github.com/openclaw/openclaw)). Memory lives as human-readable Markdown in the agent workspace, which defaults to `~/.openclaw/workspace` ([memory overview](https://docs.openclaw.ai/concepts/memory)). There is no server-side memory service to configure or clear: what the agent knows across sessions is whatever sits in those files. That makes OpenClaw's [long-term memory](/glossary/long-term-memory) inspectable and editable with any text editor. ## The files that persist The memory overview defines a small set of files, each with a distinct job ([memory overview](https://docs.openclaw.ai/concepts/memory)): - `MEMORY.md`: the curated layer. Durable non-profile facts, standing decisions, and short summaries. The docs say to keep it short. - `memory/YYYY-MM-DD.md`: the working layer. Detailed daily notes, observations, session summaries, and raw context. Slugged variants such as `memory/YYYY-MM-DD-.md` sit alongside the date-only files. - `USER.md` (optional): stable preferences, communication style, relationships, and project context, written as directives. - `DREAMS.md` (optional): the diary the dreaming sweep writes for human review. - `memory/imports/codex/`, `memory/imports/claude-code/`, `memory/imports/hermes/`: memory imported from other tools. It stays segregated, gets indexed for search, and is never merged into `MEMORY.md`. Conversation history persists separately from memory. Session rows and transcripts live in a per-agent SQLite database at `~/.openclaw/agents//agent/openclaw-agent.sqlite` ([session management](https://docs.openclaw.ai/concepts/session)). ## What loads at session start, and the caps Loading is selective, and it is capped ([memory overview](https://docs.openclaw.ai/concepts/memory)): - `MEMORY.md` loads at the start of a session. `USER.md` loads with a separate small budget. - Today's and yesterday's dated notes load automatically on a bare `/new` or `/reset`. - Older daily notes are indexed for the retrieval tools and are excluded from the bootstrap prompt. - Injection has hard limits. `agents.defaults.bootstrapMaxChars` truncates each injected file at 20,000 characters by default, and `agents.defaults.bootstrapTotalMaxChars` caps combined bootstrap injection at 60,000 characters ([context docs](https://docs.openclaw.ai/concepts/context)). - On truncation the file on disk stays intact. The injected copy is cut, the runtime adds a notice under Project Context, and `/context list`, `/context detail`, or `openclaw doctor` show raw versus injected sizes ([context docs](https://docs.openclaw.ai/concepts/context)). The cap has bitten people. A closed issue on the official repo reported a 14,296 character `MEMORY.md` losing everything past 12,000 characters at session start, with no warning to the user or the agent at the time ([issue #71782](https://github.com/openclaw/openclaw/issues/71782), a user report). The current docs describe the in-prompt truncation notice that addresses this ([context docs](https://docs.openclaw.ai/concepts/context)). ## Retrieval: search rather than full injection Anything outside the bootstrap set is reached through tools ([memory overview](https://docs.openclaw.ai/concepts/memory)): - `memory_search` runs hybrid retrieval over all memory files: vector similarity for meaning, combined with keyword matching for exact terms like IDs and code symbols. - `memory_get` reads a specific memory file or line range. - Embeddings default to OpenAI and can be switched via `memory.search.provider` to Gemini, Voyage, Mistral, Bedrock, DeepInfra, local GGUF, Ollama, LM Studio, GitHub Copilot, or any OpenAI-compatible endpoint. - The same index is reachable from the shell: `openclaw memory status`, `openclaw memory search "query"`, and `openclaw memory index --force`. - Setting `memory.search.rememberAcrossConversations: true` extends retrieval across the agent's other conversations without merging their transcripts ([session management](https://docs.openclaw.ai/concepts/session)). ## The dreaming sweep: consolidation by default OpenClaw ships automated [memory consolidation](/glossary/memory-consolidation) under the name dreaming, enabled by default ([memory overview](https://docs.openclaw.ai/concepts/memory)): - The `memory-core` plugin manages a recurring job that reviews daily notes and promotes material into `MEMORY.md`. - Promotion is gated. Candidates must pass score, recall-frequency, and query-diversity thresholds, and a bounded subagent merges duplicates and supersedes stale entries. - Untrusted and system-derived candidates are kept out of the consolidation prompt and the durable promotion path. - Phase summaries and diary entries land in `DREAMS.md`. - Disable it with `plugins.entries.memory-core.config.dreaming.enabled: false`. - `openclaw memory rem-backfill --path ./memory --stage-short-term` replays historical daily notes through the pipeline, and `--rollback` undoes a backfill. A related safeguard runs at the other end of the loop: before compaction summarizes a long conversation, OpenClaw runs a silent turn that reminds the agent to write important context to its memory files. It is on by default, disabled with `agents.defaults.compaction.memoryFlush.enabled: false`, and skipped when the session has no writable workspace ([memory overview](https://docs.openclaw.ai/concepts/memory)). ## Sessions reset; files do not `/new` and `/reset` start a fresh session, and `session.reset.mode` can force resets daily at a set hour or after idle time ([session management](https://docs.openclaw.ai/concepts/session)). Transcripts also age out: `session.maintenance` defaults to `pruneAfter: '30d'` with a 500 session cap, and only archived or pinned sessions are exempt ([session management](https://docs.openclaw.ai/concepts/session)). The durable path is the Markdown layer. Anything worth keeping past that window has to be written to the memory files by the agent, the pre-compaction flush, or the dreaming sweep. ## What OpenClaw memory does not do The documentation is unusually direct about the boundaries ([memory overview](https://docs.openclaw.ai/concepts/memory)): - No hidden state. If it was never written to disk, the agent will start the next session without it. - `MEMORY.md` is a curated layer rather than a raw transcript, daily log, or exhaustive archive. - Imported memory from Codex, Claude Code, or Hermes is indexed but never merged, and their sessions, settings, and credentials are not imported at all. - Memory can preserve approval context, but it does not enforce policy. The file-first pattern is spreading among coding and personal agents; [Claude Code's memory](/blog/claude-code-memory) applies the same shape with `CLAUDE.md` files and an auto-memory directory. ## For builders: past a single workspace OpenClaw's files answer one workspace on one machine. If you are building an agent product whose memory must span many users, many sources, and years of history, that layer is what past.dev provides: a memory API where `POST /api/v1/ingest` accepts raw text with its original timestamp, entity resolution links mentions of the same person across sources, and facts carry event time, validity windows, and supersession links. `POST /api/v1/recall` returns ranked, dated evidence with sources and one of four status values (Supported, Conflicted, NoKnownSupport, UnknownBecauseDegraded), deployed managed or self-hosted in your own Postgres. Start with the [quickstart](/docs/memory-api/quickstart) and the [benchmarks](/benchmarks), and if your agent runs on OpenClaw itself, the [OpenClaw integration](/integrations/openclaw) covers the wiring.