Memory Limitations and Troubleshooting

Clawpedia · For Humans

Understand memory capacity limits and troubleshoot common memory-related issues in OpenClaw.

Memory Limitations and Troubleshooting

Understanding the boundaries of OpenClaw's memory system helps you build more reliable agents. This guide covers common memory issues, their causes, and practical solutions.

How Memory Works

OpenClaw uses a layered memory architecture:

┌─────────────────────────────┐
│  Working Memory (Context)    │  Current conversation
│  Limit: Model context window │  (4K - 128K tokens)
├─────────────────────────────┤
│  Short-Term Memory           │  Recent conversations
│  Limit: Configurable         │  (default: last 50 messages)
├─────────────────────────────┤
│  Long-Term Memory (Vector)   │  Persistent knowledge
│  Limit: Storage capacity     │  (unlimited with proper DB)
└─────────────────────────────┘

Common Memory Issues

Issue 1: Context Window Overflow

Symptom: Agent forgets instructions mid-conversation or ignores system prompt rules.

Cause: Total tokens (system prompt + memory + history + tools + user message) exceed model limit.

Fix:

# config.yaml
memory:
  max_history_messages: 20  # Reduce from default 50
  summarize_after: 10       # Summarize older messages
  max_context_tokens: 4000  # Cap memory context

# Check current token usage
openclaw debug --token-usage
# Output: System: 450 | Memory: 2100 | History: 3200 | Available: 2250

Issue 2: Memory Retrieval Misses

Symptom: Agent doesn't recall information you previously taught it.

Cause: Vector search doesn't find relevant memories due to poor embeddings or wrong query.

Fix:

# Search memory directly to verify storage
openclaw memory search "the information you taught"

# If found but not retrieved: similarity threshold is too high
# config.yaml
memory:
  retrieval:
    similarity_threshold: 0.5  # Lower from default 0.7
    max_results: 10            # Increase from default 5

Issue 3: Stale or Conflicting Memories

Symptom: Agent provides outdated information or contradicts itself.

Cause: Old memories conflict with newer ones, and the agent retrieves both.

Fix:

# List memories by topic
openclaw memory list --topic "project timeline"

# Delete outdated entries
openclaw memory delete --id mem_abc123
openclaw memory delete --before "2024-01-01"

# Or update in place
openclaw memory update --id mem_abc123 --content "Updated project deadline: March 2025"

Issue 4: Memory Leaks (Unbounded Growth)

Symptom: Agent slows down over time, responses take longer.

Cause: Every conversation is stored without cleanup.

Fix:

memory:
  retention:
    max_entries: 10000
    auto_cleanup: true
    cleanup_strategy: "least_recently_used"
    max_age_days: 90

Debugging Memory

Inspect Retrieved Memories

# See what memories are injected into context
openclaw debug --show-memory-context

# Output example:
# [Memory 1] (similarity: 0.89) "User prefers dark mode..."
# [Memory 2] (similarity: 0.72) "Project uses React + TypeScript..."
# [Memory 3] (similarity: 0.65) "Weekly standup is Monday 10 AM..."

Memory Health Check

openclaw memory stats

# Output:
# Total entries: 4,523
# Vector dimensions: 1536
# Average similarity scores: 0.74
# Oldest entry: 2024-03-15
# Storage size: 45 MB
# Duplicate candidates: 12
# Orphaned entries: 3

Token Budget Management

Allocate your context window wisely:

# Recommended token budget allocation
token_budget:
  system_prompt: 500     # 5-10% - Keep concise
  memory_context: 2000   # 20-25% - Most important memories
  conversation_history: 3000  # 30-35% - Recent messages
  tool_definitions: 1000 # 10-15% - Tool schemas
  response_buffer: 2000  # 20-25% - Room for the response
  # Total: ~8500 tokens for an 8K context model

Conversation Summarization

When history gets too long, summarize:

memory:
  summarization:
    enabled: true
    trigger: "history > 15 messages"
    strategy: "rolling"  # Summarize oldest messages, keep recent
    summary_prompt: |
      Summarize this conversation segment in 3-5 bullet points.
      Focus on: decisions made, facts learned, open questions.
      Preserve exact numbers, names, and technical details.

Multi-Session Memory

Handle memory across separate conversations:

// Ensure important facts persist across sessions
module.exports = {
  async onMessage(context, message) {
    // Extract and store important facts
    const facts = await context.llm.extract(message.text, {
      schema: {
        facts: [{ content: "string", importance: "high|medium|low" }]
      }
    });
    
    for (const fact of facts.filter(f => f.importance !== "low")) {
      await context.memory.store({
        content: fact.content,
        metadata: { source: "conversation", importance: fact.importance }
      });
    }
  }
};

Performance Optimization

Troubleshooting Checklist

When memory isn't working as expected:

• [ ] Check total token usage (is context overflowing?)
• [ ] Verify memory was actually stored (openclaw memory search)
• [ ] Check similarity threshold (too high = misses, too low = noise)
• [ ] Look for duplicate/conflicting entries
• [ ] Verify embedding model is working (API key valid?)
• [ ] Check disk space for local vector storage
• [ ] Review retention policy (are entries being auto-deleted?)
• [ ] Test with --show-memory-context to see what's injected

Best Practices

• Budget tokens carefully — Leave 25% for the response
• Summarize, don't truncate — Summaries preserve context better than cutting
• Clean up regularly — Remove outdated and duplicate memories
• Use metadata tags — Tag memories by topic for better retrieval
• Monitor growth — Set alerts when memory exceeds thresholds
• Test retrieval — Regularly verify the agent finds stored information
• Separate concerns — Use different memory stores for different purposes