🧠 Memory System

📁 How memory works

OpenClaw's memory is deliberately simple: Markdown files are the source of truth. The vector database is just a derived index — like a search index that can be dropped and rebuilt anytime.

~/.openclaw/workspace/
├── MEMORY.md              # Long-term curated facts
└── memory/
    ├── 2026-02-26.md      # Today's daily log
    ├── 2026-02-25.md      # Yesterday's log
    └── ...                # Older logs

Key principles:

• Files on disk = truth. The agent only remembers what gets written down.
• Human-editable. Open any file in a text editor, change it, done.
• Git-friendly. Track changes with version control. Diff, blame, revert.
• No vendor lock-in. Switch machines? rsync the folder. Switch embedding models? Re-index.

📅 Daily logs

Daily logs (memory/YYYY-MM-DD.md) are append-only files that capture day-to-day activities, decisions, and running context.

• Today + yesterday are loaded at every session start
• Older logs are searchable via semantic search but not loaded by default
• The agent appends to today's log during conversations

What goes in daily logs

# 2026-02-26

## Tasks Completed
- Deployed v2.3 of the cheatsheet site
- Fixed broken nav links in guide-channels.html

## Decisions Made
- Using Telegram as primary channel, WhatsApp as backup
- Chose PostgreSQL over MySQL for the new project

## Notes
- Adrian mentioned 1-2 hours/day constraint — keep suggestions actionable
- Next priority: build playbooks section

📌 MEMORY.md — long-term curated memory

MEMORY.md holds durable facts, preferences, and decisions that should persist for weeks or months. It's loaded in main/private sessions only — never in group chats (to protect sensitive information).

What goes in MEMORY.md vs daily logs

🔍 Hybrid search — vector + BM25

When the agent needs to recall something, OpenClaw searches memory using two complementary methods:

The final score combines both: vectorWeight × vectorScore + textWeight × textScore

OpenClaw uses union, not intersection — results from either method contribute to ranking. A chunk scoring high on vectors but zero on keywords is still included.

Advanced: MMR & temporal decay

• MMR (Maximal Marginal Relevance) — reduces redundant results. If five daily logs mention the same router config, MMR ensures you get diverse results instead of five near-duplicates.
• Temporal decay — exponentially reduces scores of old memories so recent notes rank higher. A half-life of 30 days works well for daily-note-heavy workflows.

🔌 Embedding providers

OpenClaw auto-selects an embedding provider in priority order:

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "provider": "openai",
        "model": "text-embedding-3-small"
      }
    }
  }
}

♻️ Memory flush before compaction

Long conversations eventually hit the context window limit. When this happens, OpenClaw "compacts" (summarizes) older messages. But before compacting, it runs a memory flush — giving the agent a chance to save important facts to disk before they're compressed away.

{
  "agents": {
    "defaults": {
      "compaction": {
        "reserveTokensFloor": 20000,
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 4000,
          "systemPrompt": "Session nearing compaction. Store durable memories now.",
          "prompt": "Write any lasting notes to memory/YYYY-MM-DD.md; reply NO_REPLY if nothing to store."
        }
      }
    }
  }
}

This is one of OpenClaw's most innovative features — it prevents the "goldfish brain" problem where important context evaporates during long sessions.

⚙️ Configuration reference

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "provider": "openai",
        "model": "text-embedding-3-small",
        "extraPaths": ["../team-docs"],
        "query": {
          "hybrid": {
            "enabled": true,
            "vectorWeight": 0.7,
            "textWeight": 0.3,
            "candidateMultiplier": 4,
            "mmr": { "enabled": true, "lambda": 0.7 },
            "temporalDecay": { "enabled": true, "halfLifeDays": 30 }
          }
        }
      }
    }
  }
}

• extraPaths — add external Markdown directories to the search index
• candidateMultiplier — fetch extra candidates before fusion (higher = better recall, slower)
• lambda — MMR trade-off: 1.0 = pure relevance, 0.0 = max diversity
• halfLifeDays — temporal decay: 30 = daily-heavy workflows, 90 = reference-heavy

🧹 Maintenance

• Review MEMORY.md monthly. Remove stale facts, fix inaccuracies, merge duplicates.
• Archive old daily logs. After 3-6 months, move old logs to an archive folder. They'll still be searchable if in extraPaths.
• Edit directly. If the agent remembered something wrong — open the file, fix it. That's the whole point of plaintext.
• Git-track your memory:

openclaw memory status   # Check index stats
openclaw memory index    # Reindex if needed
cd ~/.openclaw/workspace
git init && git add MEMORY.md memory/
git commit -m "memory snapshot"

🔧 Troubleshooting