This guide covers the technical internals of OpenClaw's memory system. If you have already read the guide on managing agent memory, this page goes deeper into engine behavior, search functionality, and configuration.
The memory engine architecture
OpenClaw's memory system is designed around a file-first philosophy. Unlike opaque database backends, memory lives as plain Markdown files in your workspace, giving you full visibility and control.
Core components
- File loader: Reads and parses the eight auto-loaded files at session start
- Context injector: Inserts memory content into the model context window
- Memory search: Provides semantic search across memory files
- QMD (Query Memory Doctor): Diagnostic tool for memory health checks
- Context compactor: Manages context window efficiency as conversations grow
Memory search strategies
The memory_search tool enables semantic queries across your memory corpus. Understanding when and how to use it improves both speed and accuracy.
When to use memory search
- Finding specific information across many memory files
- Locating related concepts without exact keyword matches
- Querying historical decisions or past interactions
- Answering questions that span multiple memory sources
Search syntax and tips
Effective memory searches require good query formulation:
- Use natural language questions, not keywords
- Be specific about what you are looking for
- Use the maxResults parameter to limit response volume
- Use minScore to filter low-confidence matches
Search corpus options
The memory_search tool supports different corpus scopes:
- memory: Search across MEMORY.md and daily notes only
- wiki: Search compiled wiki supplements if configured
- all: Search all available sources
The QMD memory doctor
QMD (Query Memory Doctor) is a diagnostic tool that analyzes your memory setup. It helps identify issues before they cause problems.
What QMD checks
- File structure validity
- Size and bloat detection
- Missing file references
- Inconsistent formatting
- Deprecated content detection
Running QMD
QMD is invoked through the memory_search tool with special queries. The tool automatically routes diagnostic requests to QMD functionality when detected.
Memory configuration reference
While memory files themselves are the primary configuration, there are engine-level settings that affect memory behavior.
Auto-loaded files reference
| File | Purpose | Typical size |
|---|---|---|
| SOUL.md | Agent identity and hard rules | 1-3 KB |
| AGENTS.md | Operational routing | 1-5 KB |
| USER.md | User context | 0.5-2 KB |
| TOOLS.md | Tool configurations | 1-3 KB |
| IDENTITY.md | Agent branding | 0.5 KB |
| HEARTBEAT.md | Automation rules | 1-4 KB |
| BOOTSTRAP.md | Initial instructions | 1-2 KB |
| MEMORY.md | Long-term knowledge | 2-10 KB |
Optimization recommendations
- Keep auto-loaded files under 10 KB total for fastest boot times
- Use daily notes for transient context, not MEMORY.md
- Review and prune MEMORY.md monthly
- Archive old daily notes to prevent search bloat
Context window considerations
Every byte in memory files consumes context tokens. Understanding this relationship helps optimize performance.
Token budget for memory
As a rough guideline:
- 1 KB of text equals approximately 300-400 tokens
- The eight auto-loaded files typically use 1500-3000 tokens
- Memory search results add additional context per query
Balancing persistence and performance
More memory content means:
- Slower session startup
- Higher per-message token costs
- More context space used before your conversation begins
Find the balance that works for your use case. Highly interactive sessions benefit from leaner memory. Complex tasks may justify more comprehensive memory loading.
Advanced: Custom search corpora
For advanced setups, you can configure additional search sources beyond the default memory files.
Wiki supplements
Compiled wiki content can be registered as additional search corpora. This is useful for:
- Product documentation
- Codebase references
- External knowledge bases
Troubleshooting memory issues
Common issues and solutions
- Agent not finding information: Use memory_search to locate content, then verify it is in the right file
- Slow startup: Reduce auto-loaded file sizes
- Inconsistent behavior: Check SOUL.md for conflicting rules
- Lost context: Ensure important info is saved to MEMORY.md, not just chat
Security considerations
Memory files contain potentially sensitive information. Consider these security practices:
- Do not store credentials or API keys in memory files
- Use environment variables and TOOLS.md for secrets
- Review what gets included in context before sharing
- Consider workspace access controls for shared setups
Need help from people who already use this stuff?
Need help optimizing memory?
Get personalized guidance on memory configuration and performance tuning in the community forum.
FAQ
How does OpenClaw's memory search differ from simple file matching?
OpenClaw uses semantic search via the memory_search tool, which understands meaning rather than just keyword matching. This allows finding related concepts even when exact words differ.
What is QMD in OpenClaw memory?
QMD (Query-Memory-Doctor) is an optional diagnostic tool that analyzes your memory files and configuration. It helps identify issues like bloat, inconsistencies, or missing mappings.
Can I disable automatic memory loading?
No. The eight auto-loaded files (SOUL.md, AGENTS.md, etc.) are core to OpenClaw's architecture. However, you can control what content they contain, which effectively controls what gets loaded.
How do memory files affect context window usage?
Auto-loaded files consume context tokens at the start of every session. Keeping these files concise improves response speed and reduces token costs.
What happens if a memory file is malformed?
OpenClaw will attempt to load what it can from malformed files. Check server logs for warnings if you suspect file parsing issues. The QMD tool can help validate file structure.