Last updated: March 2026 Β· Source: ~/.openclaw/workspace/memory-system/
Persistent Memory System
OpenClaw agents accumulate knowledge across sessions through a layered memory system: a compact index loaded at session start, per-topic Markdown files read on demand, and an organizer pipeline that extracts facts from raw session files, deduplicates them, and indexes them for semantic search.
Three Design Inspirations
The memory-system organizer (~/.openclaw/workspace/memory-system/) draws on three research paradigms:
Mem0 β Fact Extraction
After sessions, the organizer uses an LLM (Claude Haiku via OpenClaw OAuth) to extract discrete facts from raw memory files β preferences, project state, lessons learned, active tasks. Extracted facts are structured, categorized, and stored in SQLite with FTS5.
Zep β Temporal Decay
Each fact carries a TTL. Personal facts and system state are permanent; task-related facts expire after 7 days, agent-related facts after 30. A decay engine periodically checks expired entries, uses an LLM to summarize them into lessons, and archives them β never deletes them.
MemGPT β Agent Self-Management
Agents write new memories directly via python -m src.tools write. A separate lessons extractor scans session JSONL files for "failure β retry β success" patterns, runs LLM extraction, and appends structured lessons to memory/lessons.md.
Memory Layers
Layer 1 β MEMORY.md (Session-Start Context)
Loaded into every agent's context window at the start of each session. Intentionally kept short (under ~200 lines) to avoid consuming the context budget on sessions with large task descriptions. Contains only the most current, high-priority facts: recent activity, active projects, key contacts, infrastructure notes.
# MEMORY.md β long-term memory index
# (agent loads this at session start)
## Recent Activity
- [2026-03-05] claw-stack website: major refactor, 71 pages
- [2026-03-04] AI Town: WS + interpolation + tile atlas fixes
## Active Projects
| Project | Path | Status | Memory file |
|----------|-------------------|---------|---------------------|
| claw-stack | ~/projects/claw-stack/ | active | memory/website-claw-stack.md |
## Key Facts
- Owner timezone: EST
- Host: macOS, Apple Silicon, local network
Layer 2 β memory/*.md (On-Demand Knowledge)
The memory/ directory holds per-topic Markdown files that agents read when they need deep context on a specific subject. MEMORY.md stores references (links) to these files; agents fetch the full file when needed.
| Directory / File | Contents |
|---|---|
| memory/entities/ | Projects, contacts, servers β one file per entity |
| memory/patterns/ | Reusable patterns and workflows discovered over time |
| memory/lessons.md | Extracted lessons from past failures and retries |
| memory/summaries/ | Session summaries (written at end of sessions) |
| memory/events/ | Time-stamped event records |
| memory/structured/ | Facts exported per category by the organizer pipeline (used by QMD for vector indexing) |
Layer 3 β QMD Semantic Search (Deep Retrieval)
OpenClaw's built-in memory_search tool (QMD) runs a 768-dimensional embedding model (embeddinggemma) over the memory/structured/ files. The index auto-updates every 10 minutes. Queries go through qwen3-reranker for semantic re-ranking and query expansion. This handles questions like "what did we decide about X three months ago" without the agent scanning every file manually.
The Organizer Pipeline
The memory-system organizer runs on a schedule (cron) and processes raw memory files through a pipeline:
[Organizer β runs on cron schedule]
β scan memory/*.md (MD5 hash check, skip unchanged)
β LLM fact extraction (Haiku via OpenClaw OAuth)
β deduplication (word overlap > 60% β merge)
β classification: personal / tasks / agents / system
β TTL assignment: personal=β, tasks=7d, agents=30d, system=β
β store in SQLite + FTS5 (memories.db, WAL mode)
β export structured/*.md for QMD vector indexing
β update INDEX.md (compact index ~2KB)
[Decay Engine β runs separately]
β scan SQLite for expired TTLs
β LLM summarize expired entries into lessons
β archive (removed from index, still searchable)
[Lessons Extractor β runs separately]
β scan session JSONL for error β retry β success patterns
β LLM extraction: scenario / wrong approach / correct approach / reason
β dedup (word overlap > 70%, then LLM DUPLICATE/NOVEL check)
β append to memory/lessons.md
Memory Search Script
A standalone memory-search.py script provides intent-aware search across agent memory:
# Search coding agent's memory for tmux content
uv run python memory-search.py --query "tmux claude code" --agent coding
# Search all agents, return top 3
uv run python memory-search.py --query "deployment patterns" --all-agents --top 3
# Smart mode: use Claude API for intent analysis
uv run python memory-search.py --query "how to deploy" --smart --verbose
# Search only lessons
uv run python memory-search.py --query "mistakes" --category lessons --agent main
Frequently Asked Questions
Can memory files be edited manually?
Yes. All memory files are plain Markdown on disk. You can edit, delete, or reorganize them directly. The organizer uses MD5 hashing to detect changed files and will re-process them on the next run. Changes to MEMORY.md take effect in the next session immediately β no pipeline run needed.
Is memory shared between agents?
Each agent has its own workspace and memory directory. There is also a ~/.openclaw/shared/memory/ directory that all agents can read. Agents write to their own memory; the orchestrator (main agent) coordinates shared memory updates.
What is the token cost of loading MEMORY.md at session start?
MEMORY.md is kept under ~200 lines by design. The actual token cost varies with content density but keeping it to an index-only file (with links to the detailed entity files) minimizes context overhead while still giving the agent immediate access to current state.
Authors: Qiushi Wu & Orange π