# The OpenClaw Memory System: Never Lose Context Again Canonical: https://clawdocx.com/docs/memory-system-guide Author: Sam Okafor Difficulty: BEGINNER Published: 2026-02-24 Updated: 2026-09-19 > Master OpenClaw's memory system: daily logs, long-term storage, semantic search, and memory maintenance best practices. OpenClaw's memory system lets your agent remember things across sessions. Without it, every conversation starts fresh. With it, your agent knows your preferences, recalls past decisions, and builds context over time. ## How Memory Works OpenClaw has three layers of memory: ### 1. Session Memory (Temporary) - Lives for one conversation - Lost when session ends - Fast, immediate context ### 2. Daily Memory Files (Short-term) - Stored in `memory/YYYY-MM-DD.md` - Raw logs of what happened each day - Automatically searched before answering questions ### 3. MEMORY.md (Long-term) - Curated, distilled knowledge - Manually maintained (or by Memory Gardener skill) - Survives forever if you maintain it ``` memory/ ├── 2026-02-24.md # Today's raw log ├── 2026-02-23.md # Yesterday's raw log ├── 2026-02-22.md # Day before ├── archive/ # Old daily files (optional) │ ├── 2026-01/ │ └── 2025-12/ └── MEMORY.md # Long-term curated memory ``` --- ## Daily Memory Files Every day, OpenClaw creates (or appends to) a memory file. These are raw, unfiltered logs. ### What's Automatically Logged - **Conversations:** Key points from your chats - **Decisions:** Things you decided or agreed to - **Tasks:** Actions taken or delegated - **Errors:** Mistakes and how they were fixed - **Learnings:** New information discovered ### Example Daily Memory File ```markdown # February 24, 2026 ## Morning Standup (9:00 AM) - Reviewed Q1 roadmap with team - Decided to prioritize mobile app over web dashboard - Action items: Update Jira, notify design team ## Agent Configuration Changes - Switched default model from Sonnet 4.5 to Sonnet 4.6 - Added new GitHub skill for PR reviews - Set up morning briefing cron job for 7:30 AM ## Learnings - Found that Haiku 4 is 40% cheaper than Sonnet for summarization - Discovered browser automation fails on sites with heavy Cloudflare protection ## Errors Encountered - Stripe webhook failed due to wrong URL in dev environment - Fixed by updating NEXTAUTH_URL in .env.local ``` ### How Daily Memory Gets Used Before answering a question, OpenClaw automatically searches recent memory files: **You:** "What did I decide about the mobile app?" **Agent:** *(searches memory files, finds standup entry)* "According to your memory from this morning's standup, you decided to prioritize the mobile app over the web dashboard for Q1." This happens automatically; you don't need to do anything. --- ## MEMORY.md (Long-Term Memory) Daily memory files accumulate forever. MEMORY.md is where you (or your agent) distill the important stuff. ### What Goes in MEMORY.md - **Preferences:** How you like things done - **Decisions:** Important choices and their rationale - **Patterns:** Things that keep coming up - **Lessons:** Mistakes to avoid repeating - **Contacts:** Key people and their roles - **Projects:** Ongoing work and status ### Example MEMORY.md Structure ```markdown # My Memory ## Preferences - I prefer concise answers over verbose explanations - Code examples should be in TypeScript - I wake up at 6:30 AM, work best 8 AM - 12 PM - prefer evening meetings over morning ones ## Active Projects ### ClawDocx (Primary) - Status: Scaling content library - Goals: 100 guides, 200 skills by Q2 - Stack: Next.js 16, Prisma, Stripe - Last deployed: Feb 24, 2026 ### DeepREM (On Hold) - Status: Paused to focus on ClawDocx - Resume: After ClawDocx reaches $10K MRR ## Key Decisions - **Feb 2026:** Switched from Supabase to Neon (better Vercel integration) - **Jan 2026:** Decided against mobile app for ClawDocx (focus on web first) - **Dec 2025:** Joined Propel accelerator (Vision cohort) ## People - **Alex** (me): Founder, makes final decisions - **David Rankin:** Business mentor, knows Atlantic Canada funding - **Chrystee Xing:** VC contact at Advantary ## Patterns - I often underestimate task complexity by 2x - I work in focused sprints followed by recovery days - I prefer async communication over meetings ## Lessons Learned - Always Playwright-test visual changes before pushing - Claude Code agents get killed—verify git status after - Never say "pick your brain" (Alex hates this phrase) ``` ### When to Update MEMORY.md **During sessions:** - When you make an important decision - When you learn something you want to remember - When you correct a mistake the agent made **Via the heartbeat monitor:** Older write-ups tell you to drop a memory-maintenance checklist into `HEARTBEAT.md`. Do not: OpenClaw "no longer creates `HEARTBEAT.md` in new workspaces or reads it at runtime." Heartbeat instructions now live in the system-owned monitor scratch in the shared state database. Heartbeat itself is "a system-owned automation that runs periodic agent turns in the main session so the model can surface anything that needs attention without spamming you", on a 30-minute default interval. The Gateway "maintains one system-owned automation job per heartbeat-enabled agent", which shows up as `Heartbeat (agent-id)`. Find its job id: ```bash openclaw automations list --all ``` Then read or replace that job's scratch, which is where the checklist goes: ```bash openclaw automations scratch # print current scratch openclaw automations scratch --json # scratch plus revision metadata openclaw automations scratch --set "..." # replace with exact text openclaw automations scratch --file notes.md # replace from a file ("-" for stdin) openclaw automations scratch --unset # remove the scratch row ``` So the memory-maintenance checklist above becomes a file you push into scratch: ```bash cat > /tmp/heartbeat.md <<'MD' ## Memory Maintenance - Review this week's daily files every Sunday - Extract 3-5 key insights - Update MEMORY.md with distilled learnings MD openclaw automations scratch --file /tmp/heartbeat.md ``` > **Note** > > Scratch "is stored in the shared state database, capped at 256 KiB, and never included in `automations list`/`automations get`/`automations runs` output." `--expected-revision ` gives you compare-and-swap protection against a concurrent write. During a heartbeat turn the agent can call `heartbeat_respond` with a `scratch` value to "fully replace the monitor scratch for future heartbeats", so the checklist can rewrite itself. If scratch exists but is effectively empty (blank lines, comments or headings only), OpenClaw skips the run to save API calls and reports `reason=empty-heartbeat-file`. **A weekly review is not a heartbeat job.** The docs draw the line clearly: "Create an automation for work with its own instructions or schedule; use heartbeat as the system-owned ambient monitor when periodic main-session awareness is useful." A Sunday memory review has its own schedule, so give it its own automation rather than stuffing it into scratch and hoping the ambient monitor notices the day of the week. Migrating from an old workspace? `openclaw doctor --fix` imports a legacy `HEARTBEAT.md`'s instructions into monitor scratch, converts valid legacy task entries into cron jobs, archives the original file, and removes it from the workspace. --- ## Memory Search OpenClaw can search across all your memory files semantically. ### How It Works The `memory_search` tool finds relevant snippets from your memory files: ``` memory_search:0 {"query": "What did I decide about the mobile app?"} ``` This searches: - All daily memory files - MEMORY.md - Recent session transcripts (if available) ### Search Results Results include: - **Path:** Which file the info came from - **Lines:** Where in the file - **Content:** The relevant text - **Score:** How relevant (0-1) ### Citation Best Practice When using memory in responses, cite the source: > "According to your memory from Feb 24 (Source: memory/2026-02-24.md#12-18), you decided to prioritize the mobile app over the web dashboard." This lets you verify the information is correct. --- ## Designing Your Memory Structure There's no one-size-fits-all. Design for your use case: ### For Personal Assistants ``` memory/ ├── daily/ # Raw daily logs ├── projects/ # Per-project notes ├── people/ # Contact info, preferences ├── decisions/ # Important choices └── lessons/ # Mistakes and insights ``` ### For Developers ``` memory/ ├── daily/ ├── codebase/ # Architecture decisions ├── bugs/ # Bug fixes and patterns ├── deployment/ # Deploy notes, rollbacks └── learning/ # New tech, tutorials ``` ### For Business Operations ``` memory/ ├── daily/ ├── clients/ # Per-client notes ├── processes/ # SOPs, workflows ├── metrics/ # KPI tracking └── strategy/ # Long-term planning ``` --- ## Memory Maintenance Best Practices ### 1. Review Weekly Every week, spend 10 minutes reviewing your memory: ```bash # List this week's memory files ls -la memory/2026-02-*.md # Read and distill # Update MEMORY.md with key insights ``` ### 2. Be Selective Not everything needs to be remembered: - **Remember:** Decisions, preferences, patterns, mistakes - **Forget:** Temporary tasks, one-off queries, testing ### 3. Use Clear Headings Structure makes memory searchable: ```markdown ## Decision: Switched Database Provider (Feb 24, 2026) **From:** Supabase **To:** Neon **Reason:** Better Vercel integration, no auth conflicts **Impact:** Positive—deploys are faster ``` ### 4. Link Related Memories ```markdown ## Project: ClawDocx **Status:** Active **Started:** Jan 15, 2026 **Related:** See memory/2026-01-15.md for launch decisions ``` ### 5. Archive Old Files Don't let daily files accumulate forever: ```bash # Monthly archive mkdir -p memory/archive/2026-01 mv memory/2026-01-*.md memory/archive/2026-01/ ``` --- ## Common Mistakes **Mistake 1: Not using memory at all** - Your agent starts fresh every session - You repeat yourself constantly **Mistake 2: Logging everything** - Daily files become unreadable - Important info gets buried **Mistake 3: Never updating MEMORY.md** - Long-term memory becomes stale - Agent references outdated information **Mistake 4: No structure** - Random notes scattered - Can't find things later **Mistake 5: Not reviewing** - Miss opportunities to learn - Repeat mistakes --- ## Automation with Memory Gardener Skill The **Memory Gardener** skill automates memory maintenance: ```bash openclaw skills install @/memory-gardener ``` **What it does:** - Reviews weekly memory files - Extracts key decisions and learnings - Updates MEMORY.md automatically - Archives old daily files - Runs as cron job every Sunday **Configuration:** ```json { "memory_gardener": { "review_day": "Sunday", "review_time": "10:00", "archive_after_days": 30, "extract_categories": ["decisions", "lessons", "preferences"] } } ``` --- ## Memory Templates ### Decision Template ```markdown ## Decision: [Title] ([Date]) **Context:** [Why this decision was needed] **Options Considered:** - Option A: [description] - Option B: [description] **Decision:** [What was chosen] **Rationale:** [Why this option] **Impact:** [Expected outcome] **Reversible:** Yes/No ``` ### Lesson Learned Template ```markdown ## Lesson: [Title] ([Date]) **Situation:** [What happened] **Mistake:** [What went wrong] **Root Cause:** [Why it happened] **Solution:** [How to fix/avoid] **Prevention:** [Process change to prevent recurrence] ``` ### Project Status Template ```markdown ## Project: [Name] **Status:** [Active/Paused/Completed] **Started:** [Date] **Goal:** [What we're trying to achieve] **Current Phase:** [Where we are] **Next Milestone:** [What's next] **Blockers:** [What's in the way] **Notes:** [Additional context] ``` --- ## What's Next? - **Heartbeat & Cron Job Configuration**: automate memory maintenance - **Building Custom Skills**: create a Memory Gardener variant for your needs - **Cost Optimization**: manage token usage when working with large memory files Start simple: create MEMORY.md with your top 10 preferences and decisions. Add daily files automatically. Review weekly. That's it. ## Sources - [OpenClaw: Skills CLI](https://docs.openclaw.ai/cli/skills) - [OpenClaw: Retired HEARTBEAT.md workspace file](https://docs.openclaw.ai/reference/templates/HEARTBEAT) - [OpenClaw: Heartbeat](https://docs.openclaw.ai/gateway/heartbeat) - [OpenClaw: Automations (cron)](https://docs.openclaw.ai/cli/cron) - [OpenClaw: Cron vs heartbeat](https://docs.openclaw.ai/automation/cron-vs-heartbeat) - [OpenClaw: Agent workspace](https://docs.openclaw.ai/concepts/agent-workspace)