How OpenClaw’s Memory System Makes Your AI Truly Remember You

OpenClaw’s memory mechanism works on a simple principle: only data written to files is retained; anything said only in the conversation will eventually disappear. Understanding this lets you configure the system correctly.

Four Memory Layers

The system has four distinct layers, each with its own lifespan and failure mode:

Startup files (SOUL.md, AGENTS.md, etc.) – loaded from disk at each session start and persist permanently.

Conversation record (JSONL file) – stores dialogue history on disk; semi‑permanent but compressed when the context buffer fills.

LLM context window – the model’s current view of the conversation; temporary and overflows when full.

Retrieval index (memory_search) – a searchable vector index rebuilt from files; permanent.

Core File Set

OpenClaw automatically loads exactly eight files at startup; the filenames must match precisely:

SOUL.md

AGENTS.md

USER.md

TOOLS.md

IDENTITY.md

HEARTBEAT.md

BOOTSTRAP.md

MEMORY.md

Any other file (e.g., my-rules.md, notes.md) will not be loaded, so critical knowledge must be placed in one of the eight.

File Responsibilities

SOUL.md – defines the AI’s persona, tone, and style.

AGENTS.md – the operation manual that tells the AI which files to read, which steps to take, and the behavior constraints; the most important rule file.

USER.md – stores user‑specific preferences, background, and tool dislikes; no size limit.

MEMORY.md – long‑term memory for decisions, preferences, and facts that must survive across sessions.

TOOLS.md – lists available tools and usage guidelines.

IDENTITY.md – prevents the AI from introducing its own system ID.

HEARTBEAT.md – configures periodic self‑check tasks.

BOOTSTRAP.md – initialization commands executed at startup.

Daily Memory Files

In addition to the eight startup files, OpenClaw supports two daily memory mechanisms:

Log‑type memory – memory/YYYY-MM-DD.md files that are appended each day and automatically loaded for today and yesterday.

Long‑term memory – MEMORY.md for facts that must persist for many days; if both exist, OpenClaw de‑duplicates automatically.

When to Write Where

Official guidance:

Decisions, preferences, and durable facts → MEMORY.md.

Today's log, runtime context → memory/YYYY-MM-DD.md.

Active Retrieval Tools

OpenClaw provides two utilities to make the AI retrieve memories proactively:

memory_search – semantic vector search (supports OpenAI, Gemini, Ollama embeddings) combined with BM25 keyword search.

memory_get – precise read of a specific Markdown file when the location is known.

To enforce proactive search, add a rule in AGENTS.md such as:

- Before executing any task, run memory_search to retrieve relevant memories.

Memory Flush Mechanism

When the context buffer nears its token limit, OpenClaw silently triggers a “Memory Flush”: it prompts the AI to write important notes to a daily log before compression. The feature is configured in openclaw.json:

{
  "agents": {
    "defaults": {
      "compaction": {
        "reserveTokensFloor": 20000,
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 4000,
          "systemPrompt": "Session nearing compaction. Store durable memories now.",
          "prompt": "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store."
        }
      }
    }
  }
}

The flush runs silently; it requires a writable workspace—if the workspace is read‑only, the protection is skipped.

Advanced Vector Memory Search

If MEMORY.md grows large, keyword search may become insufficient. Enabling a vector index lets the AI retrieve memories by semantic similarity. Community‑tested options include:

QMD (default) – free, local, precise.

ByteRover Memory Skill – 92% accuracy, saves 50‑70% tokens.

Mem0 + Ollama – strong automation with local embeddings.

LanceDB – fast, fully private, suited for privacy‑sensitive scenarios.

Common Pitfalls

Symlinked workspace files – OpenClaw’s safety check silently ignores symlinked files, causing them not to load. Use real file copies instead.

Overwriting MEMORY.md – a single write operation can replace the entire file, erasing dozens of memories. Declare that the AI may only append, and add the prohibition in AGENTS.md and SOUL.md.

Putting rules only in conversation – rules spoken to the AI disappear when the context is compressed. Persistent rules must be written to files; conversational statements have the same short lifespan as the LLM context window.

Three‑Step Best Practice

Write persistent rules to MEMORY.md and AGENTS.md, never rely on in‑conversation instructions.

Enable Memory Flush and set softThresholdTokens above 4000 to give the AI enough room to store notes before compression.

In AGENTS.md, enforce a rule that the AI must run memory_search before any action, making retrieval a habit rather than an occasional step.

With the memory system correctly configured, OpenClaw transforms from a “stranger” that forgets you each session into a digital companion that truly knows and remembers you.