OpenClaw Memory: What Top Builders Always Configure First

An agent without memory is a very expensive calculator. It answers questions, but it doesn't learn. It helps once, but forgets the next session. The builders running the most capable OpenClaw deployments spend their first two hours configuring memory — before they write a single agent skill. Here's exactly what they do and why.

The Three Memory Tiers in OpenClaw

OpenClaw separates memory into three independent layers, each serving a different purpose and operating on a different persistence model. Understanding what each tier does — and what it cannot do — prevents the most expensive debugging sessions builders encounter.

Tier 1: In-context memory is the active conversation window. Everything the agent has seen in the current session lives here. It's fast, zero-configuration, and completely ephemeral. When the session ends, it's gone. This tier is managed entirely by the LLM's context window — OpenClaw passes the conversation history as part of each prompt.

Tier 2: Shared memory is a key-value store accessible to all agents connected to the same gateway. One agent writes a value; any other agent can read it. This is how pipeline agents hand off state — a research agent writes findings, a writing agent reads them, a review agent checks both. Without shared memory, multi-agent pipelines require manual message passing for every data handoff.

Tier 3: Long-term memory is vector-backed or file-backed retrieval. This is what allows agents to recall specific facts from past sessions, retrieve relevant past conversations, or search a knowledge base. It requires an embedding model and a vector store, making it the most complex tier to configure — but also the one that creates the most visible quality difference in agent output.

Setting Up Shared Memory

Shared memory is configured in gateway.yaml under the memory block. By default it runs in-process (lost on restart). For production, configure a Redis or SQLite backend.

# gateway.yaml
memory:
  backend: redis          # options: memory (in-process), redis, sqlite
  redis:
    host: localhost
    port: 6379
    db: 0
    key_prefix: "openclaw:"
  defaults:
    ttl: 86400            # 24 hours default TTL for all keys
    max_key_size: 10240   # 10KB max value size

Once configured, any agent can read and write shared memory using the built-in memory skills:

# Write to shared memory from an agent skill
memory.set("user:123:preferences", JSON.stringify({
  tone: "concise",
  format: "bullet_points",
  timezone: "America/New_York"
}))

# Read from shared memory in another agent
const prefs = JSON.parse(memory.get("user:123:preferences") || "{}")

The key naming convention matters. Use a hierarchical structure — entity:id:field — so you can scan and expire related keys together. A flat namespace becomes impossible to manage past 50 keys.

Managing In-Context Memory

In-context memory is the conversation history passed to the LLM on each turn. OpenClaw manages this automatically, but two configuration parameters control how aggressively it trims older messages when the context window approaches its limit.

# agent config (agents/my-agent.yaml)
context:
  max_tokens: 16000       # reserve this much for history
  trim_strategy: sliding  # options: sliding, summarize, drop_oldest
  summary_threshold: 0.8  # summarize when context hits 80% capacity

The summarize trim strategy is the best balance for most use cases. When context fills up, OpenClaw calls the LLM to summarize the oldest portion of the conversation and replaces those messages with the summary. The agent retains the gist without losing the full token budget to old messages.

Here's where most people stop. They set up shared memory but never configure trim strategy, then wonder why long-running agent sessions degrade in quality after 30 turns. The conversation window fills, old messages drop without summarization, and the agent loses critical early-session context.

Configuring Long-Term Memory

Long-term memory requires three components: an embedding model, a vector store, and a retrieval skill wired into your agent. As of early 2025, OpenClaw supports OpenAI embeddings, Ollama-hosted embedding models (for local/private deployments), and Chroma or Qdrant as vector stores.

The local Chroma + Ollama embedding stack costs nothing and works well for single-server deployments under 100k stored memories. Switch to Qdrant Cloud when you need horizontal scaling or cross-server retrieval.

Common Memory Configuration Mistakes

• Running shared memory without a backend — the default in-process mode loses all shared state on every restart. Any agent that depends on shared memory will start cold after a server reboot. Configure Redis or SQLite before going to production.
• Not setting key TTLs — without TTLs, shared memory accumulates stale keys indefinitely. A deployment running for three months without TTLs can have thousands of orphaned keys that slow every read operation.
• Using the same context window for all agents — a simple FAQ agent needs 4k tokens of context; a research agent needs 32k. Don't use a single global context limit. Set per-agent context budgets that match the actual task complexity.
• Skipping long-term memory entirely — agents without long-term memory reset to zero knowledge every session. For user-facing agents that should improve over time, this is a critical gap. Even a basic file-backed memory store adds meaningful continuity.
• Writing entire conversation transcripts to shared memory — shared memory is a key-value store, not a conversation database. Store summaries and extracted facts, not raw message logs. Raw logs bloat memory and make retrieval noisy.

Frequently Asked Questions

What is OpenClaw memory and how does it work?

OpenClaw memory is the persistence layer that lets agents retain information across conversations and sessions. It operates in three tiers: in-context (active window), shared memory (key-value store), and long-term storage (vector or file-backed). Configuring all three prevents agents from losing context and repeating themselves.

What should I configure in OpenClaw memory first?

Start with shared memory initialization in gateway.yaml. Define the keys your agents will read and write — user profiles, task state, learned preferences. Without this baseline, every agent starts cold and agents in the same pipeline cannot share state. Shared memory is the foundation everything else builds on.

Does OpenClaw memory persist between restarts?

Shared memory persists if you configure a backend storage adapter — Redis, SQLite, or a file-backed store. Without a backend, shared memory is in-process and lost on restart. In-context memory is always session-scoped. Long-term memory persists by definition, as it writes to an external vector or file store.

How do agents in OpenClaw share memory with each other?

All agents connected to the same gateway can read and write the shared memory store. Write a value from one agent with memory.set, and any other agent reads it with memory.get. This is how pipeline agents hand off context without direct message passing between them.

What happens if OpenClaw memory gets too large?

Shared memory doesn't have a built-in size limit, but large key-value stores slow read latency. Set TTLs on transient keys to prevent accumulation. For long-term memory with vector search, prune embeddings older than your useful recall window — most use cases need 30–90 days of history, not an unlimited archive.

Can OpenClaw memory store structured data like JSON?

Yes. Shared memory values are stored as strings, so serialize JSON before writing and parse after retrieval. For complex structured data requiring querying, use the file-backed or database memory adapter instead of the key-value store, which isn't optimized for structured queries.