OpenClaw Memory Explained: Architecture, Setup, and Why Your Agent Keeps Forgetting

The Complete OpenClaw Memory Architecture (3 Layers Explained)

OpenClaw memory operates across three distinct layers, each with different persistence characteristics and failure modes.

Full memory lifecycle:

Write → Embed/Index → Search → Compact → Recover
  ↓          ↓           ↓         ↓         ↓
.md file   sqlite-vec  semantic  summary   MEMORY.md
created    indexes it  query     replaces  re-read at
           on save     returns   context   session start
                       chunks    window

Every stage in this chain can fail independently. Most forgetting issues trace to exactly one broken stage.

Layer 1 — The Active Context Window

This is the model's working memory: everything currently loaded into the context window for the active conversation. It includes your system prompt, the conversation history, and any memory chunks retrieved by the search tool.

What fills it:

• System prompt (often large)
• Retrieved memory excerpts
• Tool call history
• Conversation turns

Practical limit: assume you have roughly 60–70% of the model's advertised context window available for actual conversation after system prompt and memory overhead.

Layer 2 — Daily Notes (The Rolling Two-Day Window)

Daily notes are append-only Markdown files named in YYYY-MM-DD format stored inside your memory/ directory. OpenClaw loads today's and yesterday's files automatically at the start of each session.

• Facts about today's work, decisions made, and active tasks get appended here
• They're not meant to be edited — treat them as a log
• After two days, they fall outside the auto-load window and become searchable only via semantic search

Layer 3 — Durable Memory (MEMORY.md and memory-wiki)

Long-term facts that should survive across sessions — your name, project context, coding preferences, architectural decisions — belong in MEMORY.md or the structured memory-wiki plugin vault.

The Compaction Problem — Why Your Instructions Vanish Mid-Task

Compaction is the most under-documented failure mode in OpenClaw. Most articles cover post-session forgetting. Almost none address mid-task compaction in long-running autonomous workflows — where the agent is executing a multi-step task, compaction fires silently at step 7 of 12, and the behavioral instructions from step 1 are gone.

What compaction does:

1. Detects the context window approaching capacity
2. Summarizes the current conversation into a condensed block
3. Replaces the original context with the summary
4. Continues execution

When it triggers: There's no configurable threshold in the default memory-core plugin. It fires based on token count, not task stage. In a 2-hour autonomous run, you can expect 3–5 compaction cycles.

How to Build a Compaction-Resistant File Architecture

Pin behavioral instructions in MEMORY.md, not in the conversation. Anything that must survive multiple compaction cycles needs to be in a durable file that gets re-read after each compaction.

Recommended pinning pattern:

## Agent Behavioral Rules (always active)
- Never overwrite files without showing a diff first
- Write tests before implementation (TDD mode: on)
- Use TypeScript strict mode in all new files

## Project Context
- Stack: Node.js 22, Fastify, PostgreSQL 16
- Repo root: /home/user/project
- Active sprint goal: migrate auth to Clerk

Naming conventions that survive compaction:

• Prefix critical sections with ## [PINNED] — the summarizer treats uppercase headers as high-priority
• Keep each pinned fact to one line where possible — dense paragraphs get summarized, single-line facts tend to survive verbatim
• Repeat the 3–5 most critical behavioral rules in both MEMORY.md and today's daily note — redundancy is your compaction hedge

Zero-to-Memory Setup in 10 Minutes (Complete File Scaffold)

This is the setup guide that doesn't exist anywhere else. Copy this structure, fill in your context, and you're running.

Directory tree:

memory/
├── MEMORY.md
├── 2026-04-27.md          ← today's daily note (create manually)
└── wiki/                  ← only if using memory-wiki plugin
    ├── index.md
    ├── project-context.md
    └── decisions.md

Starter MEMORY.md:

# Persistent Memory

## Identity & Preferences
- Name: [your name]
- Role: [your role]
- Preferred response style: concise, no preamble

## Project: [Project Name]
- Stack: [your stack]
- Key constraints: [e.g., no external APIs, TypeScript only]
- Current focus: [active task or sprint goal]

## Behavioral Rules
- [Rule 1]
- [Rule 2]

## Decisions Made
- [YYYY-MM-DD] Decided to use X because Y

Starter daily note (2026-04-27.md):

# 2026-04-27

## Session Goals
- [ ] Task 1
- [ ] Task 2

## Notes

Plugin slot configuration (2026 syntax):

{
  "plugins": {
    "slots": {
      "memory": "memory-core"
    }
  }
}

To disable memory entirely:

{
  "plugins": {
    "slots": {
      "memory": false
    }
  }
}

Verification steps:

1. Run a session and ask the agent to recall something you told it in a previous session
2. Check that memory/YYYY-MM-DD.md was written (it should have new content)
3. Ask the agent directly: "What do you know about me?" — it should pull from MEMORY.md

Configuring memory-wiki for a Production Knowledge Base

Enable it by swapping the plugin slot:

{
  "plugins": {
    "slots": {
      "memory": "memory-wiki"
    }
  }
}

memory-wiki generates a structured vault under memory/wiki/. Each topic gets its own page. The plugin compiles a digest.md that aggregates high-confidence, non-contradicted facts for the agent to load at session start.

Practical vault structure for a production agent:

memory/wiki/
├── index.md              ← vault table of contents
├── digest.md             ← auto-generated; agent reads this
├── project-context.md    ← stack, goals, constraints
├── decisions.md          ← architectural decisions log
├── team.md               ← stakeholders, contacts
└── domain-knowledge.md   ← business rules, glossary

Semantic Search and Embeddings — SQLite, sqlite-vec, and the JS Fallback

OpenClaw indexes your memory files using SQLite with the sqlite-vec extension for vector similarity search. When you or the agent issues a memory search, it embeds the query and retrieves the most semantically relevant chunks.

Verify your vector store is healthy:

# Check that the memory index exists
ls memory/.index/

# Reset a corrupted index (safe to run — it rebuilds from .md files)
rm -rf memory/.index/ && openclaw reindex

If sqlite-vec is unavailable (common on ARM Linux and some Windows configurations), OpenClaw falls back to a pure-JS vector extension. Force the fallback explicitly:

{
  "memory": {
    "vectorBackend": "js"
  }
}

Segment-Specific Memory Strategies

Solo Developer — Minimal Overhead, Maximum Recall

Recommended setup: memory-core plugin, MEMORY.md + daily notes only, no wiki vault.

• Keep MEMORY.md under 200 lines — longer files slow session start
• Append to daily notes aggressively; don't try to keep them clean
• Review and prune MEMORY.md weekly — stale facts degrade search quality

Multi-Agent Pipeline — Shared Memory Across Agents

When multiple agents read and write to the same memory/ directory, you need explicit ownership rules.

• One agent owns writes to each file — concurrent writes to the same .md file will produce conflicts
• Use subdirectories per agent: memory/agent-a/, memory/agent-b/, with a shared memory/shared/MEMORY.md
• Use memory-wiki for the shared vault — its digest compilation handles freshness across multiple writers better than raw files

Long-Running Autonomous Tasks — Surviving Hours of Execution

For agents running tasks measured in hours:

• Force memory writes at checkpoints — after each major task stage, instruct the agent to append its current state to today's daily note
• Pre-load compaction-resistant context — put the full task specification in MEMORY.md before the run starts, not just in the initial message
• Set explicit continuation markers in daily notes: <!-- RESUME POINT: completed steps 1-4, next: step 5 --> so the agent can self-orient after a compaction cycle

Troubleshooting OpenClaw Memory — Diagnose Any Forgetting Issue in 2 Minutes

Work through these steps in order:

Frequently Asked Questions

Final Verdict — The Memory Setup That Actually Sticks

Recommended baseline for most users: memory-core plugin, memory/ directory created before first session, MEMORY.md with behavioral rules in a clearly labeled pinned section, daily notes appended throughout each session.

Your action checklist:

• Create memory/ directory in your project root
• Copy the starter MEMORY.md template above and fill in your context
• Verify plugins.slots.memory is set to "memory-core" (or your chosen plugin)
• Add your 3–5 most critical behavioral rules under ## [PINNED] in MEMORY.md
• After your first session, confirm a dated daily note was written
• If semantic search feels off, run openclaw reindex to rebuild the vector index

The architecture is sound once you understand it. Most forgetting issues resolve within 10 minutes of following this checklist.