How OpenClaw memory actually works.

OpenClaw doesn't use a hidden vector store, mysterious embeddings, or any "magic." It writes Markdown files. Once you internalize this, the rest of memory becomes obvious.

Memory is a folder. The folder lives at ~/.openclaw/agents/{agentId}/workspace/. You can cd into it. You can grep. You can git init if you want version-controlled memory.

workspace/
├── MEMORY.md              # Long-term, durable facts
├── memory/
│   ├── 2026-05-01.md     # Daily notes
│   ├── 2026-05-02.md
│   ├── 2026-05-03.md
│   └── 2026-05-04.md
├── recipients.md          # Custom files agents reference
├── projects/
│   └── q2-launch.md
└── .openclaw/
    └── memory.sqlite      # Vector index (regenerable)

Two files do most of the work. The rest is project-specific context the agent decides to keep.

Example MEMORY.md from a real personal-assistant agent:

# About Sam

Sam is a product manager at a 50-person SaaS company. They prefer short,
direct messages and don't like preamble. Default to brief unless they
ask for detail.

## Standing rules

- Don't draft Slack messages with emoji unless asked
- For meeting requests, default to 30 min in their morning slot
- They check Telegram more reliably than email; route urgent stuff there

## Active projects

- Q2 launch: see projects/q2-launch.md
- Hiring: 2 PM roles open, full pipeline in projects/hiring.md

## Recurring tasks

- Daily digest at 09:00 weekdays only
- Weekly review every Friday 16:00 → posted to Slack #sam-personal

Three triggers load memory automatically. Anything beyond these the agent has to look up explicitly.

• Session start. MEMORY.md, today's daily note, yesterday's daily note, and the system prompt all flow into the agent's context as the first messages.
• memory_search call. Agent decides "I don't remember the Q1 results, let me look" → vector search returns ranked snippets from older daily notes.
• Memory flush before compaction. Before history gets summarized, a silent turn prompts the agent to save anything new and important.

The agent has two memory-accessing tools. They're both called like any other tool — the agent decides when based on its system prompt and the conversation.

Under the hood, memory_search uses a hybrid score: 70% vector similarity (over OpenAI text-embedding-3-small embeddings), 30% BM25 keyword match. The hybrid catches both "concept" and "exact phrase" queries.

Without it, conversations evaporate when context fills up. With it, durable facts survive arbitrary numbers of compactions. The flush is one of OpenClaw's best ideas.

The flow:

• Agent's context approaches limit (default 80%)
• OpenClaw triggers a silent turn: "You're about to compact. Save anything important."
• Agent reviews recent history and writes to MEMORY.md or today's daily note
• Compaction summarizes the conversation history
• Next turn starts with summary + freshly-saved memory still intact

You almost never want to disable this. The cost is one extra turn per compaction (cheap); the benefit is the agent doesn't forget what you told it 30 messages ago.

From running OpenClaw agents in production:

• Edit MEMORY.md by hand. The agent's decisions about what to save aren't always great. Open the file weekly, prune what's stale, sharpen what's vague.
• Use headings aggressively. Each section becomes a memory_search anchor. "## Active projects" beats a wall of paragraphs.
• Move project-specific stuff to its own file. Don't bloat MEMORY.md with project details. Create projects/q2-launch.md and let memory_search find it.
• Keep a "rules" section. Standing preferences (no emoji, prefer Telegram, default meeting length) belong at the top of MEMORY.md so they're always-loaded.
• Version it. git init in the workspace. Every change becomes auditable. Disasters become recoverable.

The "my agent keeps forgetting" complaint usually has one of three causes.