OpenClaw MEMORY.md: The Complete Guide to Persistent AI Memory

“`html

OpenClaw MEMORY.md: The Complete Guide to Persistent AI Memory

If you’ve been running OpenClaw agents for more than a few sessions, you’ve probably hit the wall: context windows fill up, previous learnings vanish, and your AI restarts from scratch. I spent weeks watching my agents repeat mistakes they’d already solved. That’s when I got serious about MEMORY.md.

This file is the difference between a stateless chatbot and an agent that actually learns. Here’s how I’ve implemented it across production workflows.

How MEMORY.md Actually Works

MEMORY.md isn’t magical. It’s a persistent text file that lives in your agent’s working directory. When your agent initializes, it reads this file. When it learns something valuable, it updates this file. Between sessions, that knowledge persists.

The system works because of two core functions: memory_search and memory_get. Understanding the difference changed how I structure memories.

memory_get retrieves the entire MEMORY.md file. Use this sparingly—it’s a context dump. I call it only during agent initialization or when dealing with context overload recovery.

memory_search performs semantic search across your memory file. This is your workhorse. When your agent needs to recall something specific, search for it by concept, not by filename.

Here’s a real example from my API integration agent:

Agent: "I need to authenticate with the Stripe API"
memory_search("Stripe authentication key management")

Returns:
- Stripe API keys must be injected via environment variables, never hardcoded
- Test keys start with sk_test_, production with sk_live_
- Implement key rotation every 90 days
- Previous failure: hardcoded key in config.yaml caused security audit flag

That search took milliseconds and returned contextual guidance without bloating my token count. That’s the pattern.

Memory Search vs Memory Get: When to Use Each

I made mistakes here. Early on, I called memory_get constantly. Context exploded. Here’s my decision matrix:

Use memory_search when:

• Your agent is executing a specific task and needs related context
• You have more than 5KB of memories accumulated
• You want to avoid loading irrelevant historical data
• Latency matters (which it always does)

Use memory_get when:

• Initializing an agent for the first time in a session
• Your memory file is under 3KB
• You’re doing a complete context reset to prevent drift
• Debugging why the agent made a bad decision

In production, I structure this into the agent’s initialization prompt:

INITIALIZATION SEQUENCE:
1. memory_get() → load all memories
2. Parse into working knowledge
3. For each new task: memory_search(task_context)
4. Execute task
5. memory_update() → store learnings
6. Never call memory_get() during task execution

Preventing Context Bloat: The Real Problem

This is where most people fail. They dump everything into MEMORY.md and watch their context window choke.

I solve this with aggressive archival. Every 30 days, I review my MEMORY.md and run a cleanup:

• Remove duplicate learnings (keep the most specific version)
• Archive superseded information to a separate MEMORY_ARCHIVE.md
• Consolidate vague memories into actionable templates
• Delete anything not referenced in the past 60 days

Here’s what my cleanup script looks like:

#!/bin/bash
# Archive old memories

MEMORY_FILE="MEMORY.md"
ARCHIVE_FILE="MEMORY_ARCHIVE.md"
CUTOFF_DATE=$(date -d "60 days ago" +%s)

# Find entries with timestamps older than cutoff
grep -B2 "last_used:" $MEMORY_FILE | while read line; do
  entry_date=$(echo $line | grep -o '[0-9]\{10\}')
  if [ "$entry_date" -lt "$CUTOFF_DATE" ]; then
    echo "$line" >> $ARCHIVE_FILE
  fi
done

# Regenerate MEMORY.md with only active entries

I also cap my active MEMORY.md at 8KB. When it approaches that, the agent gets an instruction to compress before appending new memories.

Structuring Long-Term vs Daily Memories

Not all memories have equal weight. I separate them:

Long-term memories are principles, patterns, and lessons that rarely change. These include API specifications, architectural decisions, and hard-earned debugging insights. They live in the top section of MEMORY.md with minimal timestamps.

Daily memories are task-specific learnings, recent successes, and current project context. These are timestamped and rotated out frequently.

Here’s my actual MEMORY.md structure:

## LONG-TERM KNOWLEDGE
### Architecture Patterns
- Microservices deployment uses Docker Compose with shared .env
- Database migrations must include rollback steps
- All API responses validated against schema before processing

### Common Pitfalls
- PostgreSQL connection pooling: max 20 connections per instance
- Redis cache invalidation: must include version suffix to prevent stale reads
- File uploads: always validate MIME type server-side, never trust client headers

## DAILY CONTEXT
### Current Project (2024-01-15)
- Building user authentication module for dashboard
- Using Auth0 integration (client_id: [redacted])
- Last blocker: session timeout conflicts with refresh token rotation

### Recent Wins
- Fixed N+1 query on user profiles (implemented batch loading)
- Optimized Docker build from 4m to 1.2m via layer caching

### Active Blockers
- CORS headers not propagating to preflight requests
- Need to test against Safari (Edge case found in QA)

This structure means my agent can quickly distinguish between “this is how the world works” and “this is what I’m working on right now.”

Memory Templates That Actually Work

After dozens of iterations, I’ve settled on templates that compress information efficiently:

Problem-Solution Template:

## PROBLEM: [Clear Problem Statement]
- Symptom: [What you observed]
- Root Cause: [Why it happened]
- Solution: [What worked]
- Prevention: [How to avoid next time]
- Tags: [search-friendly keywords]

API Reference Template:

## API: [Service Name]
- Base URL: [endpoint]
- Auth: [method and required fields]
- Rate Limits: [requests/second]
- Common Errors: [error codes and fixes]
- Last Updated: [date]

Decision Log Template:

## DECISION: [What was decided]
- Context: [Why we needed to decide]
- Options Considered: [alternatives and why rejected]
- Chosen Solution: [what we picked and why]
- Reversible: [yes/no and implications]
- Date: [when decided]

I use these templates religiously. They’re searchable, scannable, and compact. When my agent runs memory_search("database connection timeout"), it finds exactly what it needs in seconds.

Practical Implementation: My Current Setup

Here’s what I actually do at the end of each agent session:

1. Agent completes task
2. Run memory_search() on key topics from the session
3. Identify gaps in existing memories
4. Add new learnings using templates above
5. Check MEMORY.md file size
6. If > 7KB: archive and compress
7. Commit changes with timestamp

I also maintain a checklist before deploying an agent to production:

• MEMORY.md exists and is valid markdown
• No hardcoded secrets or credentials
• Most recent memories are timestamped within 30 days
• Archive file exists with historical context
• memory_search is used at least 3x per major task
• No single memory entry exceeds 200 words

What Changed for Me

Before MEMORY.md discipline, my agents repeated mistakes weekly. With this system, they catch 80% of common errors automatically. More importantly, they compound knowledge—each session makes them marginally better than the last.

The key is treating MEMORY.md as a real database, not a dumping ground. Structure it. Search it. Maintain it. Your future self—and your agent—will thank you.

Frequently Asked Questions