Working with Memory and Context Management in OpenClaw

OpenClaw’s memory system is designed for reliability, security, and longevity. Unlike models that rely on "in-context" memory, OpenClaw treats files as the source of truth. Your agent’s memory lives on disk, not in RAM, ensuring nothing is lost between sessions.

This guide covers the core concepts, file structure, and best practices for managing memory and context.

The Two-Layer Memory Model

OpenClaw uses a two-tiered approach to memory, balancing immediate context with durable knowledge.

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

Every day, your agent creates a new log file in the memory/ directory. This file acts as a running journal.

Purpose: Record day-to-day events, decisions, and running context.

Best Practices:

• Always read today’s and yesterday’s logs at session start.
• Make entries throughout the day as things happen.
• Treat it as an append-only log—avoid editing past entries.
• Keep it detailed: include decisions, actions taken, and context for future you.

These files are the raw material of your agent’s experience.

2. Long-Term Memory (MEMORY.md)

MEMORY.md is your agent’s curated knowledge base—its long-term memory.

Purpose: Store durable facts, preferences, system context, and distilled insights from daily logs.

Best Practices:

• Only load MEMORY.md in main, private sessions. Never in group or public chats.
• Regularly review daily logs and update MEMORY.md with what’s worth keeping.
• Treat it like a personal wiki: update it with preferences, important decisions, and project summaries.
• Keep it concise—distill, don’t dump.

MEMORY.md is the filtered essence of your agent’s life.

Semantic Search with memory_search

OpenClaw includes powerful memory recall tools. The memory_search tool enables semantic search across all memory files.

When you ask a question about prior work, OpenClaw first runs:

memory_search(query: "What are the known bugs in Assistable.ai?")

This returns relevant snippets from MEMORY.md, memory/*.md, and even session transcripts (if enabled). It uses vector embeddings to match meaning, not just keywords.

Supported Backends

• SQLite-vec: On-device vector search (default when available)
• QMD: Experimental hybrid search (BM25 + vectors + reranking)
• OpenAI / Gemini / Voyage: Remote embeddings for scalability
• Local embeddings: via node-llama-cpp and GGUF models

Search is automatic and secure—results are never sent externally unless you configure a remote provider.

How Context is Preserved Across Sessions

The agent’s workspace (~/.openclaw/workspace) is treated as private memory. At session start, the agent reads key files:

• AGENTS.md
• SOUL.md
• USER.md
• IDENTITY.md
• memory/YYYY-MM-DD.md (today + yesterday)
• MEMORY.md (only in main session)

This bootstrapping ensures the agent wakes up informed and consistent.

Pre-Compaction Memory Flush

To prevent critical memory from being lost during compaction, OpenClaw runs a silent "memory flush" when context use approaches the model’s limit.

A silent turn is triggered with the instruction:

"Session nearing compaction. Store durable memories now."

The agent responds with NO_REPLY if nothing to store, or writes key context to disk. This happens automatically—no action needed.

Manual Memory Management

While the system handles most recall automatically, you can interact directly:

Search Memory

memory_search(query: "cron scheduling")

Read Specific Snippets

memory_get(path: "MEMORY.md", from: 150, lines: 10)

Best Practice: Write Early, Write Often

"Mental notes don’t survive session restarts. Files do."

If you want to remember something—write it down. Update the daily log or MEMORY.md immediately.

Security Notes

• Never expose MEMORY.md in group chats or public channels.
• The workspace is private. Do not commit credentials or secrets.
• Use placeholders in code examples (e.g., YOUR_API_KEY).

The workspace is your agent’s home—treat it with care.

Conclusion

Memory in OpenClaw is persistent, file-based, and secure. By leveraging daily logs, curated long-term memory, and semantic search, your agent builds a reliable, growing knowledge base.

The key is consistency: write things down, review regularly, and let the system do the rest.

Your future self will thank you.