OpenClaw Memory System: The Secret to Agents That Remember

An agent that forgets everything between sessions isn't an agent — it's a stateless chatbot. The difference between a genuinely useful OpenClaw deployment and a frustrating one almost always comes down to memory configuration. Three layers exist. Each serves a different purpose. Here's what we've seen consistently: builders who configure all three correctly ship agents that feel genuinely intelligent. Those who skip two of the three layers ship agents that constantly need re-explaining.

The Three Memory Layers Explained

OpenClaw's memory architecture is intentionally layered. Each layer has a different scope, persistence duration, and performance characteristic. Understanding all three before configuring any of them is the prerequisite that 80% of setups skip — and that's exactly where confusion about memory behavior comes from.

We'll get to the long-term store configuration in a moment — but first you need to understand why session memory alone breaks 80% of agent deployments that rely on it.

Session Memory: What It Is and What It Isn't

Session memory is the agent's working context for the current conversation. Every message sent and received, every skill result, every intermediate reasoning step — all of it lives in session memory while the session is active. When the session ends, all of that is gone. Completely. The next session starts from scratch.

This is correct behavior for a stateless task — a one-off research query, a single document analysis, a temporary calculation. It's a fundamental problem for any agent that needs to remember a user's name, their preferences, what they worked on yesterday, or any decision made in a previous session.

Session memory size is bounded by the LLM's context window. As conversations grow longer, older messages get pushed out of context. This is the context overflow problem — and it's a separate issue from persistence. Even within a single long session, early context can be lost as the window fills. The solution is proactive memory writes during the session, not just at the end.

Persistent Memory: The memory.md Configuration

Persistent memory is the layer that makes an OpenClaw agent feel like it actually knows you. It's implemented as a Markdown file — memory.md — that the agent reads at startup before any user input is processed, and writes to during and after sessions when new information should be retained.

Enable persistent memory in your agent YAML:

memory:
  persist: true
  file: ./memory.md
  load_on_startup: true
  auto_write_triggers:
    - user_preference_stated
    - key_decision_made
    - task_completed
    - important_fact_established
  write_categories:
    - preferences
    - decisions
    - completed_tasks
    - user_context
  session_summary:
    enabled: true
    write_on_session_end: true
    summary_max_words: 150

The auto_write_triggers list defines which events cause the agent to write to memory.md mid-session. user_preference_stated fires when a user expresses a preference — "I prefer bullet points", "always use metric units", "don't include caveats". The agent extracts the preference and writes it to memory under the appropriate category.

The session_summary block enables automatic end-of-session summaries. When a session ends, the agent writes a concise summary of what was accomplished — what tasks were completed, what decisions were made, what the user will likely want to continue next time. This summary is what the agent reads at the start of the next session to restore context.

Long-Term Store: Beyond memory.md

memory.md works well for per-agent context up to a few hundred kilobytes. Beyond that, startup time increases, the file becomes harder to search effectively, and the flat structure stops scaling. The long-term store addresses all three problems.

As of early 2025, OpenClaw supports three long-term store backends: SQLite (simple, no infrastructure required, good for single-agent deployments), PostgreSQL (production-grade, good for teams), and Chroma (vector store, good for semantic search over large knowledge bases). The choice depends on your search requirements and scale.

memory:
  persist: true
  file: ./memory.md
  long_term_store:
    enabled: true
    backend: chroma
    connection: "http://localhost:8000"
    collection: "agent-knowledge"
    embed_model: "text-embedding-3-small"
    write_threshold_chars: 500
    search_top_k: 5

The write_threshold_chars setting controls when information goes to the long-term store versus memory.md. Short facts and preferences stay in memory.md. Long documents, research outputs, and detailed summaries above the threshold go to the long-term store where they can be searched semantically rather than recalled as full documents.

Memory Limits and Pruning Strategies

memory.md grows with every session unless you actively manage its size. A memory file that grows without bounds causes two problems: startup time increases as the agent reads a larger file, and the full file eventually exceeds what can be efficiently loaded into context.

Configure a hard size limit and a pruning strategy before production deployment. Three strategies are available:

• FIFO (First In, First Out) — removes the oldest entries when the size limit is reached. Simple and predictable. Loses older context regardless of how relevant it remains.
• Recency-weighted — scores entries by how recently they were accessed and removes low-score entries. Keeps frequently referenced facts even if they're old.
• Category-pinned — designated categories (e.g., preferences, user_context) are never pruned. Other categories are pruned by recency. Best for most production deployments.

memory:
  persist: true
  file: ./memory.md
  max_size_kb: 128
  pruning_strategy: category_pinned
  pinned_categories:
    - preferences
    - user_context
  prune_check_interval: session_start

Cross-Session Continuity: The Full Configuration

Cross-session continuity is the outcome all three memory layers work together to produce. The agent finishes a session, writes a summary to memory.md. The next session starts, the agent reads memory.md, and it knows what was accomplished last time without the user needing to explain it.

The mistake most builders make here is assuming continuity happens automatically. It doesn't. The session summary write has to be explicitly configured and enabled. The categories of information that should persist have to be explicitly defined. And the agent's startup prompt has to explicitly instruct it to read from memory.md and use that context to orient itself.

When all three layers are configured correctly and the startup prompt references memory correctly, here's what happens in practice: a user returns to an agent after a week away. The agent greets them by name, references the task they were working on last session, and asks if they want to continue from where they left off. No re-explaining required. That's what proper memory configuration produces — and it's the difference users notice immediately.

Common Memory Configuration Mistakes

• Relying only on session memory for multi-session workflows — any task that spans more than one session needs persistent memory configured. If users constantly re-explain context at the start of each session, this is the problem.
• No size limit on memory.md — without a size limit, memory.md grows indefinitely. On production agents running for months, uncapped memory files have been observed reaching several megabytes — causing slow startups and context loading issues.
• Not testing the startup read — configure persistent memory, then restart the agent and verify it actually references memory.md content in its first response. Many builders configure the memory write correctly but never verify the read is working.
• Writing everything to the long-term store — the long-term store is for substantial, searchable knowledge — not for every short fact. Use memory.md for preferences and short context; use the long-term store for documents and research outputs above your threshold.
• No pruning strategy defined — memory.md without pruning is a liability waiting to manifest. Set the size limit and pruning strategy before the first production deployment, not after you notice performance degrading.

Frequently Asked Questions

What are the three layers of the OpenClaw memory system?

Session memory holds the current conversation context and clears when the session ends. Persistent memory survives restarts via memory.md files, read at startup and written during sessions. Long-term store is a structured external database for large knowledge bases that exceed memory.md limits and need semantic search.

What is memory.md in OpenClaw?

A Markdown file the agent reads at startup and appends to during sessions. It acts as the agent's persistent notepad — preferences, decisions, summaries, and context that should survive between sessions are written here and read back the next time the agent starts.

How do I prevent my agent from forgetting between sessions?

Configure persistent memory with memory.persist: true and enable session summaries with session_summary.write_on_session_end: true. Define which event types trigger mid-session writes in auto_write_triggers. Verify the startup read is working by restarting and checking that the agent references memory.md content immediately.

What happens when memory.md gets too large?

Startup time increases and context loading degrades. Configure a hard size limit in kilobytes and a pruning strategy — category-pinned is the most practical for production. Set these before deployment, not after performance issues appear.

How does cross-session memory continuity work in OpenClaw?

At session end, the agent writes a summary to memory.md covering decisions made, tasks completed, and context that matters next time. At session start, the agent reads memory.md before any user input. This creates continuity without the user re-explaining context — but only if both the write and the read are explicitly configured.

When should I use the long-term store instead of memory.md?

Use the long-term store when your knowledge base exceeds a few hundred kilobytes, when you need semantic search rather than full-document recall, or when multiple agents need to share a common knowledge base. memory.md is for per-agent context; the long-term store is for shared, searchable knowledge.