Memory & Context Optimization

Why Your Agent Forgets Everything

Out of the box, OpenClaw's memory doesn't work the way most people expect. You tell your agent something on Monday. By Wednesday, it's gone. You explain a preference three times and it still doesn't stick. This isn't a bug — it's a misunderstanding of how the system works.

Three things are working against you:

• Context compaction. When the conversation gets too long, OpenClaw compresses older messages to make room for new ones. Important details get summarized away or dropped entirely.
• Auto-capture is off by default. A recent update changed the default so agents don't automatically save memories between sessions. If you didn't explicitly enable it, your agent starts every conversation fresh.
• No structure to what gets saved. Even with auto-capture on, everything goes into a flat daily log. Critical business decisions sit next to casual chit-chat. When the agent searches memory, it retrieves noise alongside signal.

The fix isn't a third-party plugin (though those help). The fix starts with understanding OpenClaw's native memory architecture and configuring it properly.

OpenClaw's Memory Architecture

OpenClaw uses a file-based memory system, not a vector database. There are four layers:

The agent has two tools for accessing memory: memory_search (semantic recall across all indexed files) and memory_get (targeted file reads for specific dates or documents).

The 2-File System

The single most effective memory optimization is separating curated knowledge from ephemeral logs. Nearly every power user in the community converges on this pattern:

MEMORY.md — Your Agent's Core Knowledge

This is the file your agent reads when it needs to recall important facts. It should be structured, concise, and manually maintained. Think of it as the agent's institutional knowledge.

# MEMORY.md

## Owner
- Name: Joshua Thacker
- Location: Sacramento, CA
- Primary business: SearcherOS (SaaS for SMB acquisition screening)
- Goal: $100K ARR by December 2026

## Preferences
- Communication style: direct, concise, no fluff
- Timezone: America/Los_Angeles
- Morning person — available before 2 PM, family time after
- Never send emails without explicit approval

## Current Priorities (updated weekly)
- SearcherOS: shipping notification system this sprint
- Content: publishing OpenClaw guide series
- Marketing: LinkedIn content cadence — 3x/week

## Key Decisions
- 2026-02-15: Chose Anthropic over OpenAI for prompt-injection resistance
- 2026-02-20: Moved from EC2 to Mac Mini M4 Pro — saved $150/month
- 2026-03-01: Added Bridget (CCO) to agent hierarchy

Keep MEMORY.md under 1,000 words. It loads into the context window, so every word costs tokens. Be ruthless about what earns a place here. If it's not referenced at least weekly, it doesn't belong.

Daily Logs — The Ephemeral Record

Daily logs go to memory/YYYY-MM-DD.md. With auto-capture enabled, OpenClaw writes a summary of each session to the day's log file. These are searchable via memory_search but aren't loaded into the context window by default.

The key insight: daily logs are for search, not for context. The agent doesn't read them unless it specifically searches for something. This means they can be verbose without wasting tokens.

# memory/2026-03-08.md

## Session 1 — SearcherOS bug fix
- Fixed notification delivery failure on webhook timeout
- Root cause: retry logic wasn't exponential
- Deployed v2.4.1 at 10:30 AM PT

## Session 2 — Content planning
- Drafted outline for Memory Optimization guide
- Decided to cover pre-compaction flush technique
- Riker to promote on LinkedIn Thursday

The Memory Pipeline: Daily → Weekly → Long-Term

The 2-file system is the foundation. But to really make memory work at scale, you need a pipeline that progressively distills information from raw session logs into durable knowledge. This is the system I use:

Layer 1: Daily Logs (Raw)

Every session, every agent writes to memory/YYYY-MM-DD.md. These logs capture everything: decisions made, tasks completed, bugs found, ideas discussed. They're verbose and unfiltered. That's the point — you want the raw record.

Layer 2: Weekly Summaries (Distilled)

Every Friday (or as part of a cron job), the agent summarizes the week's daily logs into a single memory/weekly/YYYY-WXX.md file. The weekly summary strips out the noise — the false starts, the debugging dead ends, the casual conversation — and keeps only what mattered:

# memory/weekly/2026-W10.md

## Key Decisions
- Switched notification system from polling to webhooks
- Approved Riker's LinkedIn content calendar through March
- Declined partnership offer from XYZ — unit economics didn't work

## Metrics
- SearcherOS: 47 new signups, 12 conversions, $2,400 MRR
- Content: 3 LinkedIn posts published, 8,200 impressions
- Agent costs: $34.50 in API tokens this week

## Blockers Resolved
- Webhook timeout bug (Bill, deployed v2.4.1)
- DNS propagation delay on joshuathacker.com (resolved)

## Carried Forward
- SearcherOS onboarding flow redesign (Bill, in progress)
- OpenClaw guide series (Bridget, 2 of 4 complete)

Weekly summaries are compact enough to be useful for search but structured enough to tell the story of what happened that week.

Layer 3: Long-Term Memory (Promoted)

When patterns emerge across weekly summaries — recurring decisions, stable preferences, proven strategies — promote them to MEMORY.md. This is the institutional knowledge layer. It's what the agent loads every session.

The promotion criteria is simple: if something has been true for three consecutive weeks, it belongs in MEMORY.md. If it was a one-time decision, it stays in the weekly summary. The daily log gets archived after 90 days.

Daily logs (raw, verbose)
  ↓ summarized every Friday
Weekly summaries (distilled, structured)
  ↓ patterns promoted after 3+ weeks
MEMORY.md (permanent, curated, <1000 words)

This pipeline means the agent always has the right level of detail available: MEMORY.md for instant context, weekly summaries for recent history, and daily logs for forensic recall when needed.

Enable Auto-Capture

This is step zero. If auto-capture is off, nothing else in this guide matters because the agent won't save anything between sessions.

// In openclaw.json, ensure:
"memory": {
  "autoCapture": true
}

Pre-Compaction Memory Flush

This is the technique that changed how I think about agent memory. Here's the problem: when a conversation gets long, OpenClaw compacts the context window. Older messages get summarized or dropped. If you had important context in those messages, it's gone.

The fix: before the conversation hits the compaction threshold, the agent saves critical context to its daily log. You can trigger this manually (“Save everything important from this conversation to your memory files”) but you should not rely on remembering to do it. Build it into every agent's SOUL.md as a standing instruction:

# In SOUL.md — add this to EVERY agent:

## Memory Protocol (CRITICAL — do not skip)
Before EVERY long session ends, and whenever the conversation
approaches 50% of the context window:
1. Summarize all key decisions, facts, and action items
2. Write them to today's daily log (memory/YYYY-MM-DD.md)
3. Promote anything that should be permanent to MEMORY.md
4. Confirm with me before compaction occurs
5. At end of week, summarize daily logs into weekly summary

NEVER let a session end without writing to the daily log.
Lost context cannot be recovered.

The difference is night and day. Before I added this protocol, I was constantly re-explaining context to agents. After, the daily logs capture everything, the weekly summaries distill it, and MEMORY.md holds the permanent knowledge. Nothing falls through the cracks.

Hybrid Search Configuration

When the agent searches memory, it uses a combination of vector (semantic) search and text (keyword) search. The default settings are fine for casual use, but for production setups with multiple agents and weeks of accumulated memory, you want to tune the search.

Optimal Configuration

// In openclaw.json:
"memorySearch": {
  "vectorWeight": 0.7,
  "textWeight": 0.3,
  "mmr": {
    "enabled": true,
    "lambda": 0.7
  },
  "temporalDecay": {
    "enabled": true,
    "halfLife": 30
  }
}

What each setting does:

• Vector weight 0.7, text weight 0.3: Semantic search finds conceptually related content even when the exact words don't match. Text search catches exact terms, names, and identifiers. The 70/30 split favors meaning over keywords.
• MMR (Maximal Marginal Relevance) with lambda 0.7: Reduces redundant results. Without MMR, a search for “SearcherOS pricing” might return five nearly identical daily log entries. MMR diversifies the results so you get the most informative hits.
• Temporal decay with 30-day half-life: Newer memories rank higher than older ones. A decision from last week is more relevant than one from two months ago. The 30-day half-life means a memory's weight drops by 50% every 30 days.

Shared Memory Across Agents

In a multi-agent setup, agents need to share knowledge without contaminating each other's individual context. This is covered in depth in the Agent Hierarchy guide, but the memory-specific configuration is here.

Symlinked Shared Directory

Create a _shared/ directory and symlink it into each agent's workspace. Shared files (STATUS.md, ROADMAP.md, METRICS.md) live here and are readable by all agents.

mkdir -p ~/.openclaw/agents/_shared
ln -s ~/.openclaw/agents/_shared ~/.openclaw/agents/bob/_shared
ln -s ~/.openclaw/agents/_shared ~/.openclaw/agents/bill/_shared

Index Shared Files for Search

Symlinked files are readable but not automatically indexed for semantic search. To include them in memory_search results, add the shared path to memorySearch.extraPaths:

"memorySearch": {
  "extraPaths": [
    "~/.openclaw/agents/_shared"
  ]
}

Only .md files are indexed. If you need to share structured data (JSON, CSV), convert the relevant parts to Markdown first.

Third-Party Memory Options

The native memory system is solid once configured. But if you need capabilities beyond what file-based memory provides, three options are gaining traction in the community:

Mem0

Adds persistent cross-session memory with a 30-second setup. Mem0 sits alongside OpenClaw's native memory and provides a separate knowledge store that persists across sessions without relying on MEMORY.md. It's the most recommended memory plugin in the community right now.

Best for: getting cross-session memory working quickly with minimal configuration.

MemU (MEMU)

Designed for always-on agents running 24/7 (like on a Mac Mini). MemU adds long-term memory with prediction capabilities — the agent can anticipate what you'll need based on patterns in past behavior. Free and open-source.

Best for: always-on setups where you want the agent to proactively surface relevant information without being asked.

Obsidian Vault

Pairing OpenClaw with Obsidian gives a “second brain” approach. The agent reads and writes to your Obsidian vault, giving it access to your entire personal knowledge base. Notes, bookmarks, research, and structured references all become searchable context.

Best for: users who already maintain an Obsidian vault and want to bridge their personal knowledge management with their agent's memory.

Memory Anti-Patterns

Things I've seen go wrong — and things I got wrong myself:

• Dumping everything into MEMORY.md. If your MEMORY.md is 3,000 words, it's a daily log pretending to be curated knowledge. MEMORY.md is for the 20% of information that drives 80% of decisions. Everything else goes in daily logs.
• Never pruning daily logs. After 90 days, your memory directory has hundreds of files. Temporal decay helps with search ranking, but the index still grows. Archive or delete logs older than 90 days unless they contain critical decisions.
• Relying on auto-capture alone. Auto-capture saves session summaries, but it doesn't know what's important. You still need to manually promote key decisions and facts to MEMORY.md. Auto-capture is the safety net, not the strategy.
• Skipping the pre-compaction flush. Long sessions without a flush are the #1 cause of “I told the agent this yesterday and it forgot.” Build the flush protocol into your SOUL.md and make it automatic.

Putting It All Together

A properly configured memory system has these components:

• autoCapture: true in your config
• A structured MEMORY.md under 1,000 words with owner info, preferences, priorities, and key decisions
• Daily logs in memory/YYYY-MM-DD.md capturing session summaries
• A pre-compaction flush protocol in SOUL.md
• Hybrid search tuned to 0.7 vector / 0.3 text with MMR and temporal decay
• A shared _shared/ directory symlinked across agents (if running multiple)
• extraPaths configured so shared files are indexed for search

Get this right and your agents remember what matters, forget what doesn't, and share knowledge cleanly across the team. Get it wrong and you'll spend more time re-explaining context than doing actual work.