OpenClaw Memory: How It Works & How to Optimize It (2026)

OpenClaw's memory system is surprisingly simple -- plain markdown files, not a vector database. Here is exactly how it works, how auto-compaction and FSRS-6 spaced repetition keep it efficient, and how to optimize it for better agent recall.

OpenClaw stores memory in plain markdown files. There is no vector database, no embeddings engine, no complex infrastructure -- just MEMORY.md and a folder of topic files that the agent reads on startup. As of February 2026, this flat-file approach handles long-term recall, auto-compaction when context runs low, and FSRS-6 spaced repetition that makes memories fade naturally like human recall. (Source: OpenClaw GitHub repository, memory module documentation)

This guide covers everything you need to understand and optimize OpenClaw's memory system, from file structure to practical tips that reduce bloat and improve recall accuracy.

Jump to: How Memory Works · File Structure · Auto-Compaction · The FSRS-6 System · How to Optimize · What to Store vs Not Store · Common Issues · FAQ

How OpenClaw Memory Works

OpenClaw's memory system has two layers: short-term and long-term. Understanding the difference is the key to using it well.

Short-term memory is the conversation context window. Every message you send, every response the agent generates, and every tool call it makes -- all of this lives in the context window. When the conversation ends or the window fills up, short-term memory is gone unless it gets saved somewhere permanent.

Long-term memory is the MEMORY.md file and its supporting topic files. These are plain text files stored on disk at ~/.openclaw/MEMORY.md. On every startup, the agent reads MEMORY.md plus recent daily files into the context window. This is how the agent "remembers" things between sessions.

The critical insight: memory only persists if it gets written to a file. If something important happens in a conversation but never gets saved to MEMORY.md, the agent will not remember it next time. Auto-compaction (covered below) handles this automatically in most cases, but you can also save things manually.

File Structure

OpenClaw's memory lives in three types of files. All of them are plain markdown.

~/.openclaw/
  MEMORY.md                  # Long-term memory (core facts, preferences)
  memory/
    projects.md              # Topic file: project-specific context
    people.md                # Topic file: people and relationships
    decisions.md             # Topic file: key decisions and rationale
    2026-02-10.md            # Daily log: yesterday
    2026-02-11.md            # Daily log: today

MEMORY.md -- The Core File

This is the main memory file. It gets loaded on every startup and should contain the most important, frequently-needed information: your preferences, recurring patterns, key facts about your projects, and anything the agent needs to know in every session.

Think of it as a cheat sheet. It should be concise -- ideally under 2,000 words. If it grows beyond that, you are probably storing too much detail here. Move specifics to topic files.

memory/*.md -- Topic Files

Topic files hold detailed information organized by subject. Instead of cramming everything into MEMORY.md, you create separate files for different domains: projects.md, clients.md, codebase.md, whatever makes sense for your use case.

The agent loads topic files on demand -- when a conversation touches a relevant topic, it pulls in the matching file. This keeps the context window lean while still having deep knowledge available when needed.

memory/YYYY-MM-DD.md -- Daily Logs

Daily log files capture what happened on a specific day. The agent creates these automatically during auto-compaction. On startup, OpenClaw loads the most recent daily files (typically the last 2-3 days) to maintain continuity.

Daily logs are ephemeral by design. They provide short-term continuity without permanently bloating memory. The FSRS-6 system (covered below) handles their natural decay.

Auto-Compaction

Auto-compaction is what prevents OpenClaw from crashing when a conversation gets too long. When the context approaches the model's token limit, OpenClaw triggers a silent agentic turn that does three things:

1. Evaluates the current context. The agent scans the conversation for information worth preserving -- decisions made, facts learned, preferences expressed, problems solved.
2. Saves important information. Anything worth keeping gets written to MEMORY.md, a topic file, or the daily log. This happens automatically and invisibly.
3. Compacts the conversation. The context window is trimmed. Older messages are dropped, but their essential content has already been saved to disk.

This cycle can repeat multiple times in a long session. Each compaction saves what matters and discards what does not, letting the conversation continue indefinitely without hitting the token ceiling.

# You can check compaction status in logs:
openclaw logs --tail 20 | grep compaction

# Example output:
# [2026-02-11 14:23:01] compaction triggered: 187,432/200,000 tokens
# [2026-02-11 14:23:03] saved 4 entries to MEMORY.md
# [2026-02-11 14:23:03] saved 2 entries to memory/2026-02-11.md
# [2026-02-11 14:23:04] context compacted to 42,100 tokens

The FSRS-6 System

FSRS-6 (Free Spaced Repetition Scheduler, version 6) is the algorithm behind OpenClaw's cognitive memory skill. It makes memories fade naturally over time -- exactly like human memory -- so the agent does not accumulate an ever-growing pile of outdated information.

Here is how it works in practice:

• New memories start strong. When information is first saved, it has high recall strength. The agent will reference it readily.
• Unused memories decay. If a memory entry is not accessed or reinforced over multiple sessions, its recall strength drops. Eventually it fades from active use.
• Reinforced memories persist. Every time the agent accesses a memory (because it was relevant to a conversation), the recall strength resets and the decay interval extends. Frequently useful memories become essentially permanent.
• Decayed memories are archived, not deleted. Faded memories move to an archive rather than being destroyed. They can be recovered if needed.

The practical effect: your agent naturally "forgets" one-off facts from weeks ago while remembering your core preferences, project details, and frequently-used patterns. This mirrors how human memory works and keeps the active memory set lean. (Source: FSRS research papers by Jarrett Ye, 2023-2024, adapted for agent memory by OpenClaw contributors)

Optional: Vector Index for Semantic Search

As of February 2026, OpenClaw supports an optional vector index over your memory files. When enabled, it embeds the contents of MEMORY.md and topic files into a local vector store, allowing the agent to do semantic search for related notes rather than relying on keyword matching alone.

This is most useful when your memory files are large (5,000+ words across all files) and cover many different topics. For smaller memory sets, the default text-based loading works fine.

# Enable the vector index
openclaw config set memory.vectorIndex true

# Rebuild the index after editing memory files manually
openclaw memory reindex

How to Optimize Memory

Most OpenClaw users never touch their memory files. That works fine for casual use. But if you rely on the agent daily, these optimizations make a measurable difference in recall accuracy and response relevance.

1. Keep MEMORY.md Concise

Aim for under 2,000 words in MEMORY.md. This file loads on every startup, so every word in it costs tokens. Put only the most important, frequently-needed information here. Move everything else to topic files.

# Check your MEMORY.md size
wc -w ~/.openclaw/MEMORY.md

# If it is over 2,000 words, time to prune

2. Organize Semantically, Not Chronologically

Group related information together by topic, not by when you learned it. Bad: a long chronological list of facts. Good: sections like "## Project Alpha", "## Writing Preferences", "## Client Contact Info".

Semantic organization helps the agent find relevant context faster and reduces the chance of pulling in unrelated information.

3. Use Topic Files for Detail

If you have 500+ words about a single project, move it to its own topic file:

# Create a topic file
echo "# Project Alpha\n\nReact 19 frontend, Node.js API..." > ~/.openclaw/memory/project-alpha.md

Topic files are loaded on demand, so they do not consume tokens unless the conversation requires them. This lets you store deep context without paying the cost on every interaction.

4. Prune Regularly

Once a month, open MEMORY.md and remove entries that are no longer relevant. Old project details, completed tasks, outdated preferences -- delete them. The FSRS-6 system handles decay automatically, but manual pruning catches things the algorithm misses.

5. Use the /remember Command for Critical Facts

When something important comes up in conversation, do not wait for auto-compaction to maybe save it. Use the explicit command:

/remember The production API key rotates every 90 days. Next rotation: May 15, 2026.

This writes directly to MEMORY.md with a high initial FSRS-6 strength, ensuring it persists.

What to Store vs What Not to Store

The quality of your agent's memory depends entirely on what you put in it. Here are clear guidelines.

Store These

• Patterns and preferences. "I prefer TypeScript over JavaScript." "Always use 2-space indentation." "Keep emails under 150 words."
• Key decisions and their rationale. "We chose PostgreSQL over MongoDB because of ACID compliance requirements."
• Recurring solutions. "When the Docker build fails on Mac, delete ~/Library/Containers/com.docker.docker and restart Docker."
• Project context. Tech stacks, API endpoints, team members, deployment processes.
• Contact preferences. "Client X prefers formal emails. Client Y wants bullet points."

Do NOT Store These

• Session-specific context. "User asked about the weather in Paris" -- unless it is a recurring need.
• Unverified information. If you are not sure something is correct, do not encode it as a permanent memory. The agent will treat it as fact.
• Duplicates. Before adding a new entry, check if it already exists. Duplicate entries waste tokens without adding value.
• Anything already in the system prompt. If your system prompt already defines behavior or preferences, do not duplicate it in memory.
• Sensitive credentials. API keys, passwords, and tokens should live in environment variables or config files -- not in MEMORY.md.

Common Issues

Memory Bloat

Symptoms: agent responses slow down, context window fills up faster, irrelevant information appears in responses.

Fix: Open MEMORY.md and prune. Check word count with wc -w ~/.openclaw/MEMORY.md. If it is over 3,000 words, aggressively remove old entries. Move detailed sections to topic files. Enable FSRS-6 if it is not already active:

openclaw config set memory.fsrs true

Outdated Entries

Symptoms: agent references old project names, deprecated APIs, or completed tasks as if they are current.

Fix: Search for outdated information and remove or update it. The FSRS-6 system should decay these naturally, but if entries keep getting reinforced (because the agent references them), they persist. Manual removal is the fix.

Context Window Exhaustion

Symptoms: agent cannot process long messages, auto-compaction triggers too frequently, conversation feels "choppy" with the agent losing track of recent context.

Fix: reduce the size of your memory files. If MEMORY.md plus loaded topic files consume 40%+ of your context window, the agent has too little room for actual conversation. Switch to a larger context model (like Claude Sonnet 4.5 with 200K tokens) or trim your memory files.

Agent Not Reading Memory

Symptoms: agent does not know things that are clearly in MEMORY.md.

Fix: verify the memory file path. Run openclaw doctor to check that memory loading is working. If you moved or renamed files, the agent may not find them. Reset with:

openclaw memory status

# Expected output:
# MEMORY.md: loaded (1,247 words)
# Topic files: 3 loaded
# Daily logs: 2 loaded (2026-02-10, 2026-02-11)
# FSRS-6: active, 47 entries tracked

FAQ

How does OpenClaw memory work?

OpenClaw (created by Peter Steinberger, formerly Clawdbot, then Moltbot) stores memory in plain markdown files -- no vector database, no embeddings. The main file is MEMORY.md for long-term facts, with topic-specific files in a memory/ folder and daily logs as memory/YYYY-MM-DD.md. On startup, the agent reads these files into the context window. As of February 2026, an optional vector index enables semantic search over memory files.

What is FSRS-6 in OpenClaw?

FSRS-6 (Free Spaced Repetition Scheduler, version 6) is the algorithm behind OpenClaw's cognitive memory skill. It makes memories fade naturally over time, like human memory. Frequently accessed memories stay strong, while unused entries gradually decay. This prevents memory bloat and keeps agent recall focused on what matters.

What should I store in OpenClaw memory?

Store patterns, preferences, key decisions, recurring solutions, and project context. Do not store session-specific ephemera, unverified information, duplicates of existing entries, or anything already in the system prompt. Keep MEMORY.md concise and use topic files for detailed reference material.

How does auto-compaction work?

When the conversation context approaches the model's token limit, OpenClaw triggers a silent agentic turn. It evaluates the current context, saves important information to memory files, and compacts the conversation window. This happens automatically and invisibly -- the agent continues the conversation with a shorter context but no lost knowledge.

Why is OpenClaw forgetting things between sessions?

OpenClaw only remembers what is written to its memory files. If important context was never saved to MEMORY.md or a topic file, it will not persist. Check your memory files with cat ~/.openclaw/MEMORY.md. Use the /remember command during sessions to explicitly save critical information. Also verify auto-compaction is enabled in your config.

Related Guides

• What Is OpenClaw? -- the full overview of features and capabilities
• How to Install OpenClaw -- get running in under 20 minutes
• OpenClaw System Prompt Guide -- customize your agent's behavior and personality
• Best Models for OpenClaw -- how model choice affects memory and context