Your AI agent wakes up every session with total amnesia. It doesn't remember yesterday's deployment disaster, the database credentials you gave it an hour ago, or the fact that you prefer tabs over spaces. Every conversation starts from zero. This is the default state of every LLM-based agent. The context window is a goldfish bowl — when the session ends, everything evaporates. If you're running OpenClaw (or any agent framework) without a memory strategy, you're essentially hiring a contractor who forgets your name every morning. Here's how to fix it. Not with theory — with the actual architecture we run in production. ## The Four Layers of OpenClaw Memory OpenClaw's memory system isn't a single database. It's four layers, each serving a different purpose, each with different performance characteristics. ### Layer 1: Workspace Files The simplest layer. Your agent's working directory contains files it can read and write: configs, scripts, downloaded assets, notes. These persist across sessions because they're just files on disk. ``` /root/.openclaw/workspace/ ├── AGENTS.md # Agent behavior rules ├── SOUL.md # Personality and tone ├── USER.md # Info about your human ├── TOOLS.md # Local tool configuration ├── MEMORY.md # Long-term curated memory ├── HEARTBEAT.md # Periodic task checklist └── memory/ ├── 2026-02-28.md # Daily log ├── 2026-03-01.md # Daily log └── heartbeat-state.json ``` This is the foundation. No database, no embeddings, no API calls. Just markdown files that your agent reads at session start. ### Layer 2: Daily Logs (Raw Context) Every session, your agent should append to `memory/YYYY-MM-DD.md` — a chronological record of what happened. Think of it as a work journal. ```markdown # 2026-03-01 — Session Notes ## Deploy Gate Article Published - Slug: how-to-build-a-deploy-gate-pre-push-smoke-test-for-web-apps - DALL-E 3 hero image saved locally - Category: Automation ## Critical SSR Bug Fixed - Articles with template literals in code examples broke SSR injection - Fixed by escaping all < in SSR-injected content - This was a latent bug affecting ANY article with HTML in code blocks ``` Daily logs are append-only. They capture everything — decisions, bugs found, commands run, lessons learned. The agent reads today's and yesterday's logs at session start for recent context. The key rule: **if you didn't write it down, it didn't happen.** Your agent cannot make "mental notes." There is no mental. There are only files. ### Layer 3: MEMORY.md (Curated Long-Term Memory) `MEMORY.md` is the distilled version. While daily logs are raw and chronological, `MEMORY.md` is organized by topic and curated for relevance. ```markdown # Sebastian - Operational Memory ## Core Systems - **Identity:** Sebastian (Efficient, direct, professional) - **User:** Boris - **Timezone:** PST (San Francisco) ## Integration Status - **Google Calendar:** Active. Can read/write/delete events. - **Google Drive:** Active. Can upload files. - **Twitter/X:** Active. V2 API via x_post_v2_final.py. ## Active Initiatives - **stormap.ai:** Blog engine + automation scripts. Vercel auto-deploys. - **Deploy Gate:** Pre-push smoke test. Puppeteer + headless Chromium. ``` This file is the agent's "personality" and institutional knowledge. It knows what projects are active, what APIs are configured, what decisions were made and why. It loads this at session start in the main (private) session. **Critical security rule:** `MEMORY.md` only loads in your main session — direct chats between you and your agent. In group chats, Discord servers, or shared contexts, the agent should NOT load `MEMORY.md`. It contains personal context, API configurations, and operational details that shouldn't leak to strangers. ### Layer 4: Semantic Search (memory_search + memory_get) The first three layers are read-at-startup. They work, but they don't scale. When you have months of daily logs and a sprawling `MEMORY.md`, you can't load everything into context. This is where `memory_search` comes in. It's a semantic search tool that indexes your memory files and returns relevant snippets: ``` memory_search({ query: "what database does stormap.ai use" }) → Returns: "MongoDB Atlas (brainstormapp.bc96xa0.mongodb.net)" Source: MEMORY.md#line42 ``` Under the hood, OpenClaw uses a hybrid search system: - **BM25 text matching** for exact keyword hits - **Vector similarity** for semantic/conceptual matches - Results are fused and ranked by relevance The embeddings are generated by local models when available, falling back to OpenAI's embedding API. Chunks are hash-stabilized to avoid re-embedding unchanged content. After `memory_search` finds relevant snippets, `memory_get` does targeted retrieval — pulling specific lines from a specific file: ``` memory_get({ path: "MEMORY.md", from: 42, lines: 10 }) ``` This two-step pattern (search → get) keeps context small. You don't dump your entire memory into the prompt. You pull exactly what you need. ## Heartbeats: Automated Memory Maintenance Memory rots if nobody maintains it. Daily logs pile up. `MEMORY.md` gets stale. Old decisions stay documented long after they're reversed. OpenClaw solves this with heartbeats — periodic polls where the agent can do background work. You configure a `HEARTBEAT.md` checklist: ```markdown # HEARTBEAT.md - Check email inbox for urgent messages - Review calendar for upcoming events - If it's been 3+ days, curate daily logs into MEMORY.md ``` Every 30 minutes (configurable), the agent wakes up, reads `HEARTBEAT.md`, and decides whether to act or go back to sleep (`HEARTBEAT_OK`). The memory maintenance pattern works like this: 1. **Every few days**, the agent reviews recent `memory/YYYY-MM-DD.md` files 2. **Identifies patterns** — recurring issues, completed projects, lessons learned 3. **Promotes important info** to `MEMORY.md` 4. **Removes outdated entries** from `MEMORY.md` (dead projects, resolved bugs) This is the equivalent of a human reviewing their journal and updating their mental model. The daily files are raw notes; `MEMORY.md` is curated wisdom. ## Anti-Patterns: How to Sabotage Your Agent's Memory ### The "Mental Notes" Trap The single most common mistake: the agent "decides" to remember something without writing it to a file. LLMs are convincing — they'll say "I'll keep that in mind" or "noted for future reference." But there is no future reference. The session ends. The context evaporates. The note is gone. **Fix:** Your `AGENTS.md` should explicitly state: "Memory is limited. If you want to remember something, WRITE IT TO A FILE. Mental notes don't survive session restarts. Files do." ### Bloated MEMORY.md The opposite problem: dumping everything into `MEMORY.md` until it's 50KB of historical trivia. At that point, it's consuming thousands of tokens every session just to load, and most of it is irrelevant noise. **Fix:** Curate aggressively. If a project is done, archive the details to a daily log and keep only a one-liner in `MEMORY.md`. If a decision was reversed, remove the old entry. Keep `MEMORY.md` under 5KB. ### Unmaintained Daily Logs Writing daily logs but never reviewing them. They accumulate for months. Nobody (human or agent) reads them. They exist purely to consume disk space. **Fix:** Heartbeat-driven maintenance. Every few days, the agent should review recent logs, promote valuable info to `MEMORY.md`, and archive the rest. You can also set up a cron job to gzip logs older than 30 days. ### Loading Memory in Group Chats Your agent loads `MEMORY.md` in a Discord server. Now everyone in the server can see your API keys, personal preferences, and operational details. **Fix:** `MEMORY.md` loads only in the main session (direct chat). In group contexts, the agent should rely on workspace files and semantic search for non-sensitive information. ## Comparison: Markdown vs SQLite vs Vector DB | Approach | Pros | Cons | Best For | |----------|------|------|----------| | **Flat Markdown** | Human-readable, zero setup, version-controllable, grep-friendly | Doesn't scale past ~100KB, no structured queries | Small-medium agents, personal use | | **SQLite** | Structured queries, handles millions of rows, single file | Not human-readable, requires schema design, harder to manually edit | Agents with structured data needs | | **Vector DB** | Semantic search, handles massive corpora, scales horizontally | Complex setup, embedding costs, overkill for small agents | Large-scale enterprise agents | | **Hybrid (OpenClaw)** | Human-readable files + semantic search, best of both worlds | Requires embedding generation, more moving parts | Production agents that need both readability and recall | OpenClaw's approach is pragmatically hybrid: store everything in markdown (human-readable, git-friendly, editable), but index it with embeddings for semantic retrieval. You get the simplicity of flat files with the recall power of a vector database. ## Performance: Keeping Context Small Memory is only useful if your agent can access it without burning its entire context window. Here's how to keep it lean: **Load hierarchy at session start:** 1. `SOUL.md` (personality — small, ~500 tokens) 2. `USER.md` (user info — small, ~200 tokens) 3. Today + yesterday's daily logs (~500-2000 tokens) 4. `MEMORY.md` (main session only — target under 2000 tokens) **Total startup context: ~3000-5000 tokens.** That leaves 95%+ of your context window for actual work. **For everything else, use `memory_search`:** - Don't load last month's daily logs at startup - Don't put your entire project history in `MEMORY.md` - Search on demand, retrieve specific lines with `memory_get` **Archive aggressively:** - Daily logs older than 30 days? Compress or archive them - Completed project details? Move to a `memory/archive/` folder - `MEMORY.md` over 5KB? Time to curate ## The Real Lesson AI agent memory isn't a technology problem. It's a discipline problem. The tools exist — markdown files, semantic search, heartbeat maintenance, curated long-term memory. The hard part is actually using them consistently. Write everything down. Curate regularly. Keep it small. Search instead of loading. And never, ever trust a "mental note." Your agent is only as good as its memory. Make it remember.