OpenClaw Memory Search Explained — How Agents Find What They Know

Memory in OpenClaw works differently from what most people expect. There's no magical database being queried — it's a well-designed file system that gets loaded into the LLM's context window. Once you understand how it actually works, you'll manage it much more effectively.

The File-Based Memory Model

Every OpenClaw session starts fresh. The agent has no memory of previous sessions unless that memory was written to files. Those files are:

• MEMORY.md — Long-term curated memories. Key decisions, important preferences, project context.
• memory/YYYY-MM-DD.md — Daily notes. Session-specific context relevant for days to weeks.
• SOUL.md, TOOLS.md, AGENTS.md, USER.md — Structural context loaded every session.

# AGENTS.md instructs what to load:
## Every Session
1. Read SOUL.md
2. Read USER.md
3. Read COMPANY.md
4. If in MAIN SESSION: also read MEMORY.md

How Memory Gets Into Context

When the agent receives a message, it reads the files specified in AGENTS.md. These become part of the LLM prompt's context window. The LLM then has access to everything in those files when forming its response. Memory retrieval is just reading files — no separate search step.

The Context Window Constraint

LLMs have a context window limit (typically 100K-200K tokens for modern models). Everything loaded needs to fit within this window along with the current conversation. Large workspace files consume context budget.

# Practical size guidelines:
# SOUL.md: 300-500 words
# TOOLS.md: 500-1,000 words of active content
# MEMORY.md: 1,000-2,000 words (curated, not a diary)
# AGENTS.md: 300-500 words
# Daily notes: 200-500 words per day, auto-archive after 30 days

Writing Effective Memory Entries

The LLM needs to recognize when a memory is relevant. Vague entries get ignored. Specific, contextual entries get used.

# WEAK:
## Decisions
- Chose React framework

# STRONG:
## 2026-03-15: Architecture Decision
Chose Astro (not Next.js) for ClawKit website because:
- Static generation fits content-heavy site
- Faster build times than Next.js
- Vercel deployment is simpler
DON'T revisit this — Rahul confirmed final choice.

On-Demand Memory Reads

You can point your agent at specific memory files in conversation:

# In Slack:
"check my notes from last month about the payment integration"

# Agent will read relevant memory/ files and extract context

When to Archive vs Keep

The golden rule: if you wouldn't tell a new employee this fact on their first day, archive it. MEMORY.md is the essential briefing, not a complete history.

# Archived content goes to:
~/memory/archive/2026-Q1.md
# Still searchable on demand, but not loaded every session

Adding Vector Search (Advanced)

For large knowledge bases, add a vector search MCP server:

{
  "mcp": {
    "servers": [
      {
        "name": "memory-search",
        "command": "npx @modelcontextprotocol/server-memory",
        "args": ["--dir", "~/.openclaw/workspace/memory"]
      }
    ]
  }
}

For the full memory architecture guide including long-term knowledge management patterns, The OpenClaw Playbook covers it in depth for $9.99.