Understanding OpenClaw's Memory System

Clawpedia · For Humans

A deep dive into how OpenClaw stores, retrieves, and manages conversational and long-term memory.

Overview

OpenClaw's memory system is what transforms a stateless chatbot into a personalized assistant that remembers you. It stores facts, preferences, conversation context, and learned behavior across sessions. This article explains how memory works, the different memory types, storage architecture, and how to configure it for your needs.

Why Memory Matters

Without memory, every conversation starts from zero. The agent wouldn't know your name, your preferences, your timezone, or what you discussed yesterday. Memory provides:

• Continuity — conversations span across sessions and platforms.
• Personalization — responses adapt to your preferences and habits.
• Context — the agent understands references to past interactions.
• Learning — the agent improves its responses over time.

Memory Architecture

OpenClaw uses a three-tier memory system:

┌─────────────────────────────────────────────────┐
│                Working Memory                    │
│         (Current conversation context)           │
│                  ~10-50 messages                 │
├─────────────────────────────────────────────────┤
│               Short-Term Memory                  │
│      (Recent interactions, last 7 days)          │
│              ~500-1000 entries                   │
├─────────────────────────────────────────────────┤
│               Long-Term Memory                   │
│  (Facts, preferences, learned patterns)          │
│             Unlimited entries                    │
└─────────────────────────────────────────────────┘

Working Memory

The conversation buffer that holds the current chat context:

memory:
  working:
    max_messages: 50           # How many messages to keep in context
    max_tokens: 8000           # Token limit for the context window
    summarize_at: 40           # Summarize when reaching this count

When working memory fills up, OpenClaw automatically summarizes older messages and moves key facts to short-term memory.

Short-Term Memory

Recent interactions and temporary context:

memory:
  short_term:
    max_entries: 1000
    ttl_days: 7
    auto_prune: true

Long-Term Memory

Persistent knowledge about you:

memory:
  long_term:
    storage: sqlite             # sqlite | postgres | file
    path: ~/.openclaw/memory/long-term.db
    embedding_model: all-MiniLM-L6-v2
    search_top_k: 5             # Return top 5 relevant memories

How Memory Is Used

When you send a message, OpenClaw:

• Retrieves relevant memories using semantic search.
• Injects them into the model's context alongside your message.
• Processes the message with full context.
• Stores new facts and important information.

User: "Schedule a meeting with Sarah next Tuesday"

Memory Retrieval:
  - "Sarah is the user's project manager" (long-term)
  - "User prefers morning meetings" (long-term)
  - "Sarah mentioned Thursday is better" (short-term, 2 days ago)

Agent Response:
  "I'll schedule a meeting with Sarah for next Tuesday morning.
   Note: Sarah recently mentioned Thursday works better for her —
   would you like me to check with her first?"

Memory Storage Backends

SQLite (Default)

memory:
  long_term:
    storage: sqlite
    path: ~/.openclaw/memory/long-term.db

PostgreSQL (Production)

memory:
  long_term:
    storage: postgres
    connection: postgresql://user:pass@localhost:5432/openclaw
    table_prefix: memory_

Semantic Search

Memory retrieval uses vector embeddings for semantic similarity:

Query: "What's Sarah's email?"

Results (ranked by relevance):
1. "Sarah's email is sarah@company.com" (similarity: 0.94)
2. "Sarah prefers video calls over email" (similarity: 0.67)
3. "User's email is user@example.com" (similarity: 0.52)

The embedding model converts text into numerical vectors. Similar concepts have similar vectors, enabling intelligent retrieval even when exact words don't match.

Embedding Models

memory:
  long_term:
    embedding_model: all-MiniLM-L6-v2    # Local, no API needed
    # or: text-embedding-3-small          # OpenAI API

Memory Operations

Viewing Memory

# Statistics
openclaw memory stats

# Output:
# Working Memory:   23 messages (current session)
# Short-Term:       342 entries (7-day window)
# Long-Term:        1,247 entries (all time)
# Storage Used:     48 MB
# Embedding Model:  all-MiniLM-L6-v2

# Search memory
openclaw memory search "Sarah email"

# View recent entries
openclaw memory recent --last 20

Exporting and Importing

# Export all memory to JSON
openclaw memory export --output memory-backup.json

# Export only long-term memory
openclaw memory export --type long-term --output lt-backup.json

# Import from backup
openclaw memory import memory-backup.json

Manual Memory Management

# Add a fact manually
openclaw memory add "My favorite programming language is Rust"

# Delete a specific memory entry
openclaw memory delete --id mem_abc123

# Clear all short-term memory
openclaw memory clear --type short-term

# Clear everything (requires confirmation)
openclaw memory clear --all --confirm

Memory Scoping

Control how memory is shared across platforms:

memory:
  scope: global                # global | per-platform | per-user

For personal use, global is usually best. For shared bots, per-user prevents context leaking.

Automatic Memory Extraction

OpenClaw automatically identifies and stores important facts:

memory:
  auto_extract: true
  extract_types:
    - preferences              # "I prefer dark mode"
    - facts                    # "My birthday is March 15"
    - contacts                 # "Sarah is my project manager"
    - locations                # "I live in Berlin"
    - schedules                # "I usually wake up at 7 AM"

The agent uses the LLM to identify significant information and stores it as structured entries:

{
  "id": "mem_abc123",
  "type": "preference",
  "content": "User prefers metric units for temperature",
  "confidence": 0.95,
  "source": "telegram:2024-01-15",
  "created_at": "2024-01-15T10:30:00Z"
}

Troubleshooting

Agent Doesn't Remember Previous Conversations

• Check memory is enabled: openclaw config get memory.
• Verify storage backend: openclaw memory stats.
• Check if memory was cleared: openclaw memory recent.
• Ensure the storage path is writable.

Memory Search Returns Irrelevant Results

• Try different search terms.
• Upgrade the embedding model for better quality.
• Adjust search_top_k to return more or fewer results.

Memory Uses Too Much Disk Space

• Enable auto-pruning: openclaw config set memory.short_term.auto_prune true.
• Reduce short-term TTL: openclaw config set memory.short_term.ttl_days 3.
• Export and clear old data: openclaw memory export && openclaw memory clear --all.

Next Steps

• Manage long-term memory: Managing Long-Term Memory in Your OpenClaw Assistant.
• Clear memory safely: Clearing or Resetting OpenClaw's Memory.
• Learn about personalization: How OpenClaw Personalizes Its Responses.