--- 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 past.dev is a memory API for assistants you build. It runs as a managed service or, on an Enterprise agreement, in your own cloud. `POST /api/v1/ingest` accepts timestamped source text, stable source metadata, an audience slug, and an author identity. Once ingestion completes, `POST /api/v1/recall` requires a query and identity and returns ranked documents with dates and source excerpts. Start with the [Memory API quickstart](/docs/memory-api/quickstart) and the [benchmarks](/benchmarks). If your agent runs on OpenClaw, the [OpenClaw integration](/integrations/openclaw) covers the wiring.