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 scheduled automations or explicitly
Memory Tools
Two agent-facing tools for memory operations:
| Tool | Purpose |
|---|---|
memory_search |
Semantic retrieval across indexed Markdown snippets |
memory_get |
Targeted file/line-range reading (returns empty gracefully if file doesn't exist) |
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 once usage crosses a soft threshold below the compaction threshold (
softThresholdTokens), or when the active transcript reaches a byte size (forceFlushTranscriptBytes) - Uses
NO_REPLYso users aren't interrupted - Runs once per compaction cycle, on a private copy of the conversation
- Requires writable workspace access (skipped in read-only sandbox)
- Skipped for CLI backends and heartbeat turns
On by default. memoryFlush is an object, not a boolean; configure it in openclaw.json:
{
"agents": {
"defaults": {
"compaction": {
"memoryFlush": {
"enabled": true,
"model": "<provider>/<model-id>",
"softThresholdTokens": 4000
}
}
}
}
}
model is optional and applies to the flush turn only (it does not inherit the session's fallback
chain) — take the value from the instance's own model catalogue. Leave every key out to keep the
defaults. A key the schema does not know refuses the gateway at the next restart, so change this block
through the config-surgery procedure and check the key list with openclaw config schema first.
Vector Search
OpenClaw supports semantic memory search via vector indexing:
- Indexes both MEMORY.md and daily logs
- Supports multiple embedding providers (OpenAI by default; Gemini, Voyage, Mistral, Ollama and local GGUF among others) — the list changes between releases, so read it from the instance
- Configured under
memory.search.*:memory.search.provider,memory.search.model,memory.search.fallback; the older keys of the former embedding section are migrated away by the runtime.provider: "none"is a deliberate full-text-only mode - Hybrid BM25+vector retrieval is always on; the only tuning keys are
memory.search.query.maxResultsandmemory.search.query.minScore. MMR re-ranking and temporal decay (a 30-day half-life on dated daily notes;MEMORY.mddoes not decay) are fixed, not configurable - The index lives in the per-agent state database, not in a standalone memory file
- Changing the embedding provider, model or chunking pauses vector search until an explicit reindex
Operating this subsystem — failing embeddings, a paused index, reindexing, database growth — belongs
to the memory-ops skill; this skill covers what the agent writes, not how the index is repaired.
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:
- Read last 3-5 daily logs
- Identify durable facts, decisions, preferences
- Check if they're already in MEMORY.md
- Add new items, update changed items, remove outdated ones
- 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
- Keep MEMORY.md under 5,000 characters — it's loaded every main session
- Use categories (Preferences, Decisions, Projects, Patterns)
- Include dates for time-sensitive items
- Remove outdated entries regularly
- Let the agent suggest memory updates during curation
- Don't duplicate what's in AGENTS.md or SOUL.md