memory-system

# 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_REPLY` so 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`: ```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.maxResults` and `memory.search.query.minScore`. MMR re-ranking and temporal decay (a 30-day half-life on dated daily notes; `MEMORY.md` does 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: ```markdown # 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: 1. Read last 3-5 daily logs 2. Identify durable facts, decisions, preferences 3. Check if they're already in MEMORY.md 4. Add new items, update changed items, remove outdated ones 5. 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: ```markdown ## 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: ```markdown ## 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 1. Keep MEMORY.md under 5,000 characters — it's loaded every main session 2. Use categories (Preferences, Decisions, Projects, Patterns) 3. Include dates for time-sensitive items 4. Remove outdated entries regularly 5. Let the agent suggest memory updates during curation 6. Don't duplicate what's in AGENTS.md or SOUL.md