Memory System

Memory System Guide

OpenClaw's memory is built on plain Markdown files in the workspace. The agent doesn't retain information in RAM between sessions — all persistent data must be written to disk.

Two-Layer Architecture

Layer 1: Daily Logs (memory/YYYY-MM-DD.md)

• Append-only journal for the day
• Today's and yesterday's entries loaded at session start
• Captures running notes, decisions, observations
• Format: freeform markdown, chronological entries
• Auto-created by the agent during sessions

Layer 2: Long-Term Memory (MEMORY.md)

• Curated, durable information
• Loaded ONLY in main private sessions (never in groups — security)
• Contains: key facts, user preferences, project decisions, recurring patterns
• Maintained by the agent during heartbeats or explicitly

Memory Tools

Two agent-facing tools for memory operations:

Memory Flush Mechanism

Before context compaction (when session tokens approach the limit), OpenClaw triggers a silent agentic turn:

• Agent is reminded to preserve durable memories to disk
• Activates when: contextWindow - reserveTokensFloor - softThresholdTokens is reached
• Uses NO_REPLY so users aren't interrupted
• Runs once per compaction cycle
• Requires writable workspace access (skipped in read-only sandbox)

Configure in openclaw.json:

{
  "agents": {
    "defaults": {
      "compaction": {
        "memoryFlush": true,
        "reserveTokensFloor": 8000
      }
    }
  }
}

Vector Search (Optional)

OpenClaw supports semantic memory search via vector indexing:

• Indexes both MEMORY.md and daily logs
• Supports multiple embedding providers: OpenAI, Gemini, Voyage, Mistral, Ollama, local GGUF
• Features: hybrid BM25+vector search, MMR re-ranking, temporal decay
• Useful for agents with large memory histories

MEMORY.md Structure

Recommended format for curated long-term memory:

# MEMORY.md

## User Preferences
- User prefers brief responses unless complexity requires detail
- Concise answers for simple questions, thorough for complex ones
- Prefers code examples over long explanations

## Key Decisions
- 2025-03-15: Chose PostgreSQL over MongoDB for the main project
- 2025-03-10: Agreed on 2-week sprints with Monday planning

## Active Projects
- OpenClaw workspace optimization — in progress
- API migration from v2 to v3 — blocked on auth design

## Recurring Patterns
- User asks about legal compliance every Monday
- Weekly report needed by Friday 17:00
- Deploy window: Tuesday-Thursday only

## Important Context
- Company uses Jira for project management
- CI/CD via GitHub Actions
- Production on AWS eu-central-1

Memory Curation Process

The agent should periodically (every few days) review daily logs and distill:

1. Read last 3-5 daily logs
2. Identify durable facts, decisions, preferences
3. Check if they're already in MEMORY.md
4. Add new items, update changed items, remove outdated ones
5. Keep MEMORY.md focused — remove ephemeral details

Security: MEMORY.md in Groups

MEMORY.md is never loaded in group chats. This is a security feature — prevents leaking private user information to shared contexts. The agent should follow this rule in AGENTS.md:

## Memory
- MEMORY.md loads ONLY in main session
- Never reference MEMORY.md content in group chats
- Daily logs are session-private as well

Configuring Memory in AGENTS.md

Add memory management instructions:

## Memory Management
1. On session start: read memory/YYYY-MM-DD.md (today + yesterday)
2. During work: append notes to today's memory file
3. Every 3 days: review daily files, distill into MEMORY.md
4. Before answering questions about past decisions: check MEMORY.md first
5. Never share MEMORY.md content in group chats

Best Practices

1. Keep MEMORY.md under 5,000 characters — it's loaded every main session
2. Use categories (Preferences, Decisions, Projects, Patterns)
3. Include dates for time-sensitive items
4. Remove outdated entries regularly
5. Let the agent suggest memory updates during curation
6. Don't duplicate what's in AGENTS.md or SOUL.md