OpenClaw Memory System
AI agents forget everything between sessions — unless you give them memory. OpenClaw's layered memory system lets agents remember decisions, learn from mistakes, and build knowledge over weeks and months.
Memory Architecture
Three Layers of Memory
📝 Daily Logs — Short-Term Memory
memory/YYYY-MM-DD.md files capture raw events as they happen.
Like a journal. Every important decision, conversation, task completion, and error gets logged here. The agent reads today's and yesterday's files on startup for immediate context.
🧠 MEMORY.md — Long-Term Memory
Curated knowledge the agent should always have access to.
Like a human's crystallized knowledge. User preferences, project context, important decisions, lessons learned. The agent periodically distills daily logs into MEMORY.md.
🔍 QMD Vector Search — Recall Engine
Semantic search across all memory files, research, and workspace documents.
Like a search engine for your agent's brain. Runs locally with zero API cost using Metal-accelerated embeddings. The agent can query "what happened with the client project last week?" and get instant results.
Daily Memory Files
Example: memory/2026-03-11.md
# 2026-03-11
## Tasks Completed
- Built OpenClaw content cluster (10 pages) for AI Agent Tools
- Fixed TypeScript build errors in newsletter component
- Deployed v2.3 of the marketing site
## Decisions Made
- Chose Tailwind v4 over styled-components for new pages
- Set up Opus for main sessions, Sonnet for subagents
## Issues & Lessons
- Build failed due to missing heroicons import — always verify imports
- Subagent lost context after compaction — use write-on-complete rule
## Notes
- Client meeting moved to Thursday
- Need to review PR #247 tomorrowThe agent writes to this file throughout the day. On the next session start, it reads today's and yesterday's files automatically for continuity.
💡 Write-on-Complete Rule
When a major task completes, the agent immediately writes to the daily log. Don't wait for heartbeats or nightly extraction — session crashes and context compaction can erase unwritten memory forever.
Long-Term Memory (MEMORY.md)
MEMORY.md is the agent's curated knowledge base. Unlike daily logs that capture everything, this file contains only what matters long-term — user preferences, project history, important decisions, and lessons the agent has learned over time.
Example MEMORY.md Structure
# MEMORY.md
## About My Human
- Prefers direct communication, no fluff
- Works in Central Time, usually active 8am-11pm
- Building AI Agent Tools website and OpenClaw ecosystem
## Active Projects
- AI Agent Tools (Next.js site) — main revenue project
- OpenClaw content marketing — SEO-driven content cluster
- Client automation system — launching Q2 2026
## Systems Built
- 3,000+ page content site with AI-generated pages
- 22-cron-job automation system for nightly operations
- Multi-agent orchestration with Opus/Sonnet/Haiku splitting
## Lessons Learned
- Always write-on-complete — lost an entire night of work once
- Cheaper models for subagents, premium for orchestration
- Keep HEARTBEAT.md under 200 words to manage token costsMemory Maintenance
Every few days, the agent reviews recent daily files and distills important information into MEMORY.md. Old, irrelevant entries get archived. Think of it like a human reviewing their journal and updating their mental model.
Security Note
MEMORY.md contains personal context. OpenClaw only loads it in the main session with your human — never in shared contexts like group chats or public Discord channels. Your private context stays private.
Vector Search with QMD
Semantic Memory Recall
QMD (Query Memory Database) provides instant semantic search across all your agent's files. Instead of reading every memory file, the agent searches by meaning:
qmd query "what happened with the client project last week?"Zero API cost — runs locally on Metal
Sub-second results with reranking
Auto-updates index hourly
Memory Best Practices
✅ Do
- • Write to daily logs immediately on task completion
- • Keep MEMORY.md curated and concise
- • Use QMD for recall instead of reading all files
- • Review and prune MEMORY.md every few days
- • Log decisions and their reasoning
- • Track lessons learned from mistakes
❌ Don't
- • Rely on "mental notes" — they don't survive restarts
- • Store secrets in memory files
- • Let MEMORY.md grow beyond ~2,000 words
- • Skip the write-on-complete rule
- • Load MEMORY.md in shared/group contexts
- • Forget to log important errors
Build Smarter AI Agents
Learn memory architecture patterns, optimization strategies, and real examples from builders running production agents.
Related OpenClaw Topics
Memory FAQ
How does OpenClaw agent memory work?
Three layers: daily log files for raw events, MEMORY.md for curated long-term knowledge, and QMD vector search for semantic recall across all files. The agent reads recent logs on startup and searches older memories as needed.
Does the agent remember previous conversations?
Within a session, yes — full context. Across sessions, the agent reads daily memory files and MEMORY.md to recall important context. With QMD, it can also search for specific topics across all historical files.
What is MEMORY.md?
The agent's curated long-term memory. Contains distilled knowledge — user preferences, project context, decisions, and lessons. Loaded only in private sessions for security.
How does QMD vector search work?
QMD indexes all memory files into vector embeddings that run locally on Apple Metal (or CPU). The agent queries by meaning, not keywords, getting relevant results in milliseconds with zero API cost.
Give Your Agent a Memory
Persistent memory is what separates a chatbot from a true AI agent. Set it up today.