Memory Systems

Memory Types Overview

OpenClaw provides four memory types, each suited to different retention needs:

Working Memory

Working memory holds the current conversation in the agent's active context window. Every message in the session is available to the LLM without retrieval. This is the simplest memory model and the default for interactive use.

memory:
  type: working
  max_tokens: 8000    # truncate oldest messages when context exceeds limit
  strategy: sliding   # alternatives: summarize, trim_oldest

When the conversation exceeds max_tokens, OpenClaw applies the configured truncation strategy. sliding drops the oldest messages first. summarize uses an LLM call to compress older context into a summary before dropping it — more expensive but preserves semantic continuity. trim_oldest is equivalent to sliding.

Episodic Memory

Episodic memory persists interaction history across sessions. When you start a new conversation, the agent can recall relevant past interactions — what was discussed, what decisions were made, what the user previously asked.

memory:
  type: episodic
  storage: sqlite            # sqlite (default), postgres, redis
  max_episodes: 100          # keep last 100 interaction episodes
  recall_top_k: 5            # retrieve 5 most relevant past episodes per query
  db_path: ~/.openclaw/memory.db

# Inspect what's in memory
openclaw memory list --agent my-agent
openclaw memory search "previous task summary" --agent my-agent
openclaw memory clear --agent my-agent  # start fresh

Semantic Memory

Semantic memory stores factual knowledge as vector embeddings, enabling semantic similarity search. This is the foundation of RAG (Retrieval-Augmented Generation) — the agent can search its knowledge base for facts relevant to the current query and include them in context automatically.

memory:
  type: semantic
  vector_store: chroma        # chroma (default), qdrant, pinecone, weaviate
  embedding_model: text-embedding-3-small  # OpenAI embedding model
  collection: my_knowledge_base
  top_k: 6                    # number of relevant chunks to retrieve

# Index documents into semantic memory:
# openclaw memory index --files ./docs/**/*.md --agent my-agent

Semantic memory is the right choice when your agent needs to answer questions about a specific document corpus — product documentation, codebase knowledge, organizational policies, or domain-specific reference material. Rather than stuffing all documents into every prompt (expensive and slow), semantic retrieval fetches only the relevant chunks.

Combining Memory Types

Production agents often need multiple memory types simultaneously. A customer support agent might use working memory for the current conversation, episodic memory to recall this customer's previous tickets, and semantic memory to search the product knowledge base.

memory:
  working:
    max_tokens: 4000
    strategy: summarize
  episodic:
    storage: postgres
    max_episodes: 50
    connection: ${DATABASE_URL}
  semantic:
    vector_store: qdrant
    collection: product_docs
    top_k: 4

When multiple memory types are configured, OpenClaw retrieves from all sources and presents them to the agent as distinct context blocks: [CURRENT SESSION], [PAST INTERACTIONS], and [RELEVANT KNOWLEDGE]. The agent can draw from all sources simultaneously without the user needing to manage memory retrieval explicitly.

Best Practices

• Start with working memory. It requires zero configuration and handles most use cases well. Only add persistent memory when you have a specific need for cross-session retention.
• Use semantic memory for reference content. If your agent needs to answer questions about large document sets, semantic memory is far more scalable than working memory.
• Set reasonable max_episodes. Retrieving from 1,000 episodes is slower and often less relevant than the 50 most recent. More history is not always better.
• Periodically curate semantic memory. Outdated or contradictory facts in semantic memory produce confusing agent behavior. Regular audits keep knowledge bases clean.

Memory Indexing and Maintenance

Semantic memory degrades in usefulness if the underlying documents change and the index isn't updated. OpenClaw's memory system supports incremental indexing — only changed documents are re-embedded when you run the index command again, making regular re-indexing fast even for large collections.

# Re-index changed documents only (incremental)
openclaw memory index --source ./docs --incremental

# Schedule automatic re-indexing
# In config.yaml:
# memory:
#   semantic:
#     auto_reindex: true
#     reindex_cron: "0 2 * * *"   # 2am daily

For episodic memory, consider establishing a periodic review policy. Long-running agents that store every interaction indefinitely accumulate noise — interactions that are no longer relevant. The openclaw memory prune command supports date-based and relevance-based pruning strategies to keep memory focused on useful history.

Memory Privacy Considerations

Memory systems store information that may be sensitive — previous conversations, personal data, organizational knowledge. Before deploying persistent memory, consider your data retention and privacy requirements:

• Episodic memory persists conversation content — ensure it complies with your data retention policies and any applicable regulations (GDPR, CCPA)
• Semantic memory may store confidential documents — ensure the vector database is deployed in your security boundary with appropriate access controls
• Memory databases should be encrypted at rest and in transit
• Document a memory deletion process for data subject requests

For maximum privacy, deploy Qdrant or pgvector in your own infrastructure. Avoid cloud-hosted vector stores for sensitive data unless you have a data processing agreement with the provider.

Memory Diagnostics in Production

Unexpected agent behavior is frequently caused by stale or incorrect information in persistent memory. When an agent starts giving surprising responses, check memory state first: openclaw memory list --agent <name> shows recent episodic entries, and openclaw rag query "<topic>" shows what semantic memory would retrieve for a given query. A quick memory inspection often reveals the root cause faster than adding logging or rerunning the agent in verbose mode.