Your OpenClaw Agent Has Amnesia. Here Is the Permanent Memory Fix.

TL;DR: OpenClaw permanent memory requires five files (SOUL.md, USER.md, MEMORY.md, AGENTS.md, and daily logs) plus three JSON config settings that prevent compaction from wiping your agent’s context. Without the config changes, every session restart is a fresh start regardless of what your agent “learned.”

You tell your agent your preferred framework, your client list, your working hours. It nods along. Next morning, it asks for all of it again.

That is not a bug report. That is the default OpenClaw experience when memory is not set up correctly. The community has a name for it: “context rot.”

Your agent wakes up every day with no recollection of anything you told it. People describe it as “overnight amnesia,” and that description is accurate.

The good news is that OpenCLaw permanent memory is not a paid feature or a third-party plugin. It is a five-file system built into OpenClaw’s architecture that most users never configure past the defaults.

This guide covers the exact files, the exact config settings, and the day-one starter content that took me the longest to figure out.

If your agent keeps forgetting stuff or its context gets wiped mid-session, read this before you do anything else. It is a configuration problem, and it has a solution that takes about 20 minutes to implement.

Why Your OpenClaw Agent Keeps Forgetting You

OpenClaw loses memory in three specific failure modes, all of which are preventable once you know what they are.

The first and most common: you told your agent something in a conversation, but it was never written to a file on disk. Conversational context lives in the session transcript only.

When the session ends, it disappears. The agent was not ignoring you; it physically cannot read a conversation that is no longer loaded.

The second failure mode is compaction. OpenClaw compacts conversation history to stay within its context window. Compaction is lossy by design: it summarises the transcript rather than preserving it verbatim.

Short verbal instructions like “don’t do anything until I say so” get dropped from the summary because the summariser has no way to know they were load-bearing.

Summer Yue, a Meta alignment researcher, documented this exact failure publicly: she gave a verbal instruction, left the agent running, compaction fired, the instruction dropped from the summary, and the agent began autonomously deleting emails from an inbox that had grown to thousands of messages while she was away.

Compaction is not safe for critical instructions.

The third failure mode is file bloat. Each bootstrap file has a 20,000-character hard limit. When MEMORY.md exceeds that, OpenClaw truncates it silently during load.

Your agent is reading a cropped version of your memory file, and it has no way to tell you.

The fix for all three is the same: set up the file system correctly and turn on the config settings that make saves happen before compaction fires.

The Five Files That Create Permanent Memory

OpenClaw’s permanent memory system is five plain Markdown files, each with a specific role and a specific audience.

Before covering each file, here is the architecture in one table:

That sub-agent column matters more than most tutorials acknowledge.

When OpenClaw spawns a sub-agent to handle a task, it only passes AGENTS.md and TOOLS.md. Your SOUL.md personality settings and USER.md preferences are invisible to sub-agents.

If you want sub-agents to follow specific operational conventions, those rules must live in AGENTS.md, not anywhere else.

1. SOUL.md sets personality but is not a security layer

SOUL.md is injected first, before any other file. It shapes how the agent communicates: direct vs. conversational, formal vs. casual, how it frames uncertainty.

Think of it as the agent’s character sheet.

One thing the community gets wrong: SOUL.md is not a place to put safety constraints or hard limits. It is socially engineerable. A sufficiently clever user prompt can override personality instructions.

Hard behavioral constraints belong in AGENTS.md.

Day 1 starter content for SOUL.md:

# Agent Identity

You are a focused technical assistant working for [Your Name].
You communicate directly and concisely. You prefer numbered steps over
prose explanations. When you are uncertain, you say so explicitly
rather than hedging.

You do not make assumptions about project scope without asking.
You do not take irreversible actions without explicit confirmation.

2. AGENTS.md is the file that actually controls behaviour

This is the most important file in the system and the one that does the least work in most setups I have seen. AGENTS.md is your agent’s operations manual: what tools it can use, what the workflow looks like, when it should stop and ask versus proceed.

Because it is the only bootstrap file that sub-agents receive, every behavioral rule you care about needs to live here.

Day 1 starter content for AGENTS.md:

# Operational Rules

## Before starting any task
- Search memory using memory_search before acting on any project context
- Confirm the current task scope with the user if ambiguous
- Do not proceed with file deletions, API calls with side effects, or
  email sends without explicit confirmation in the current session

## Tool conventions
- Prefer reading files before editing them
- Log completed actions to memory using /remember after each session

## Workflow framework
- Break tasks into steps and confirm the first step before proceeding
- For multi-session projects, write a status note to MEMORY.md at end of session

3. USER.md is the cheat sheet your agent actually needs

USER.md is the practical context file: your name, timezone, which projects are active, what tech stack you use, who your clients are, what your working hours look like.

The agent reads this at session start to orient itself without requiring you to re-introduce yourself.

Keep it factual and structured. A wall of prose is harder for the agent to parse than short labelled sections.

Day 1 starter content for USER.md:

# User Profile

**Name:** [Your Name]
**Timezone:** [Your Timezone, e.g., America/New_York]
**Working hours:** [e.g., 9am-6pm weekdays]

## Active projects
- [Project 1]: [one-sentence description, current phase]
- [Project 2]: [one-sentence description, current phase]

## Technical environment
- OS: [e.g., macOS 15, Windows 11]
- Primary language: [e.g., Python 3.12, TypeScript]
- Package manager: [e.g., uv, pnpm]
- Editor: [e.g., Cursor, VS Code]

## Preferences
- Framework: [e.g., React 18, FastAPI]
- Testing: [e.g., pytest, Vitest]
- Do not suggest [tools/patterns you dislike]

4. MEMORY.md is where your agent’s permanent knowledge lives

MEMORY.md is the source of truth for everything the agent has learned and should remember indefinitely. Decisions made in past sessions go here.

Preferences the agent discovered through trial and error go here. Rules that came from past mistakes go here.

Keep it under 100 lines and 2,000 words. That is not arbitrary: approaching 20,000 characters triggers the truncation ceiling. A bloated MEMORY.md is worse than a short one because it gets silently cropped.

Day 1 starter content for MEMORY.md:

# Long-Term Memory

## Learned preferences
- [Date]: Prefers [specific approach] for [specific task type]

## Project decisions
- [Date]: Decided to use [tech/tool] for [project] because [reason]

## Rules from past mistakes
- [Date]: Do not [specific action] because [what went wrong last time]

## Active constraints
- Framework currently in use: [React 18 / FastAPI / etc.]
- Do not suggest migration away from [X] unless explicitly asked

When there is a conflict between MEMORY.md and a daily log file, MEMORY.md wins. Daily logs are append-only context captures; MEMORY.md is the deliberate source of truth.

This matters when you update a dependency: if MEMORY.md says React 18 and a daily log from last week mentions React 19, your agent will follow MEMORY.md.

5. Daily logs are the searchable archive, not the working memory

The memory/YYYY-MM-DD.md files are auto-created during compaction flush. Think of them as a searchable archive rather than active memory.

Your agent does not load them at startup; it retrieves them when it calls memory_search. The /remember [fact] command writes to MEMORY.md immediately, not to a daily log.

You do not need to create these manually. Once memoryFlush.enabled: true is set, the system maintains them.

The Six Config Settings That Make Memory Work

Three JSON settings prevent compaction from destroying context; three more control how the agent retrieves memory from the archive.

Here is the complete memory block you need in ~/.openclaw/openclaw.json:

{
  "agents": {
    "defaults": {
      "memoryFlush": {
        "enabled": true,
        "reserveTokensFloor": 40000,
        "softThresholdTokens": 4000
      },
      "memorySearch": {
        "provider": "local",
        "vectorWeight": 0.7,
        "textWeight": 0.3,
        "cache": { "maxEntries": 50000 }
      },
      "contextPruning": {
        "mode": "cache-ttl"
      }
    }
  }
}

What each setting actually does:

memoryFlush.enabled: true is the most important one. Without it, when the context window fills up and compaction fires, it summarises and overwrites without saving anything first.

With it enabled, a silent save runs before compaction writes its summary. Instructions, preferences, decisions in the current session get written to disk before they can be lost.

reserveTokensFloor: 40000 sets a headroom buffer. The flush trigger activates when available context drops below this number, giving the system room to write files before the window is full. If you set this too low, the flush runs when there is not enough room to complete cleanly.

softThresholdTokens: 4000 is the buffer before the floor. When the context is 4,000 tokens above the floor, the system starts preparing the flush. Think of it as the warning stage before the save fires.

contextPruning.mode: “cache-ttl” is the most misunderstood setting. Pruning and compaction are different operations. Pruning hides old tool results from the current view temporarily; it is reversible. Compaction rewrites conversation history permanently. The cache-ttl pruning mode trims old tool call results without touching conversation history. This reduces context bloat before compaction is even needed.

One version note: the compaction reliability fixes landed in v2026.2.23. If you are on anything older, update before trusting these settings.

The retrieval problem most tutorials skip

One thing the docs do not say clearly: retrieval from the daily log archive is not automatic. Beyond two or three bootstrap files, the agent does not load any memory on its own.

It has to call memory_search explicitly to retrieve anything from the archive.

This means if AGENTS.md does not explicitly instruct the agent to search memory before acting, it will not search. It will guess, or it will ask you to repeat yourself, or it will work from stale context.

The Day 1 AGENTS.md template above includes a “search memory before acting” rule for exactly this reason.

Before/After example:

Before (no memory search instruction in AGENTS.md): Agent starts a new session. You ask it to continue work on your API project. It has no memory of which framework you chose, which endpoints exist, or what you decided last week. It either asks you to catch it up or makes wrong assumptions.

After (search instruction present): Agent starts a new session. Before doing anything, it calls memory_search for “API project” and retrieves the relevant MEMORY.md entries and the last two daily logs. It starts the session already knowing your framework, your last completed endpoint, and the decision you made about authentication.

How FSRS-6 Manages Memory Decay

OpenClaw uses the FSRS-6 spaced repetition algorithm to decide how long different memory types stay active.

The FSRS algorithm (Free Spaced Repetition Scheduler) was developed by Jarrett Ye and has been validated in memory research as a significant improvement over earlier SM-2 scheduling.

OpenClaw’s implementation applies it to agent memory rather than flashcard review.

Here is how retention works in practice:

What this means operationally: your agent will not forget that you prefer Python. It will gradually deprioritise the fact that you had a specific call at 3 pm last Tuesday.

Archived memories move to a lower-priority retrieval tier rather than being deleted. This is intentional: it keeps MEMORY.md from growing indefinitely without losing anything permanently.

The 4 AM daily reset is worth understanding separately. Every day at 4 AM, OpenClaw starts a fresh session ID. Only bootstrap files and the searchable log archive carry over.

Conversation context from the prior session is gone. This is not a memory failure; it is how the system separates session state from persistent knowledge.

The five-file setup is what makes that reset safe rather than destructive.

As part of the full OpenClaw pipeline breakdown, the 4 AM reset is documented as a deliberate design choice to prevent session state from becoming a dependency. Set up your files correctly and the reset becomes invisible.

Diagnosing Whether Your Memory Setup Is Working

Three diagnostic commands tell you exactly what your agent loaded, whether it searched, and whether it saved.

Run these after your initial setup to confirm everything is working:

1. /context list shows every file that loaded at session start, including truncation status and character counts. If a file shows as truncated, it is over the 20,000 character limit and getting cropped.
2. /verbose activates a mode where you can see in real time whether memorysearch is firing when the agent takes actions. If you gave it a task and no memorysearch call appears in verbose output, your AGENTS.md instruction is not triggering correctly.
3. /remember [fact] writes a specific fact to MEMORY.md immediately, bypassing the compaction flush cycle. Use this at end-of-session to lock in decisions made during a long working session.

The community also uses a pattern called “dual-layer memory” for high-stakes facts: write the fact with /remember, then manually verify it appeared in MEMORY.md.

The automated flush is reliable in v2026.2.23+, but for things you absolutely cannot afford to lose, direct verification takes 10 seconds.

For a deeper look at what happens when the agent’s loop breaks down rather than forgets, my agent looping fix guide covers that separate failure mode.

Third-Party Memory Options Worth Knowing

If you do not want to manage five Markdown files manually, managed hosting or a memory plugin are the practical alternatives.

The community has converged on a few third-party options for users who want memory to “just work”:

• QMD adds a richer memory graph layer on top of the standard file system

• Mem0 and Supermemory are external memory services that handle storage outside the OpenClaw file system

• Hindsight does automatic memory extraction from session history without requiring manual /remember calls

For users who prefer a fully managed setup where the file system is handled for them, ClawTrust is an OpenClaw hosting service that pre-configures memory correctly and handles the maintenance.

Worth considering if the JSON config and five-file management is more overhead than you want.

The trade-off is control. The native system gives you exact control over what your agent knows.

Third-party plugins add convenience at the cost of opacity. From my experience, most users who start with a plugin end up wanting the native setup eventually because they hit a case where the plugin made the wrong call about what to remember.

If you have been trying to keep costs reasonable alongside all of this, the OpenClaw cost guide covers which operations actually consume tokens and where the spend concentrates.

The GitHub Issue on Native Memory and What It Means

The OpenClaw community has an open feature request for a more automatic native memory layer: GitHub issue #39885. The request is for memory that does not require manual file management or explicit search instructions in AGENTS.md.

It is a genuine gap in the current system.

The existing five-file system is effective once configured but it does put the configuration burden on the user. The feature request has meaningful community support.

In the meantime, the setup described in this guide is the production-tested approach.

One thing worth noting from the issue thread: the concern is not that OpenClaw’s memory system is fundamentally broken. It is that the defaults are not good enough for most users’ expectations.

The defaults assume you know what you are setting up. This guide exists because most people do not find out until their agent starts acting like it has amnesia.

If you are still early in your OpenClaw experience, the first-week guide covers the expectations gap in more detail.

Frequently Asked Questions

The most common questions about OpenClaw permanent memory cover setup order, compaction timing, and what happens to archived facts.

Does OpenClaw have permanent memory by default?

OpenClaw does not have functional permanent memory by default. The file system exists, but memoryFlush.enabled is false out of the box, which means compaction can fire without saving first. You need the three memoryFlush settings enabled to make memory reliable across sessions.

What is the difference between compaction and pruning in OpenClaw?

Compaction is permanent and lossy: it rewrites your conversation history into a summary. Pruning is temporary and lossless: it hides old tool results from the current context view but does not delete them. Setting contextPruning.mode: "cache-ttl" uses pruning to reduce context bloat before compaction ever needs to fire.

Why does my agent ignore things I told it earlier in the session?

Instructions given in conversation are not automatically saved to any file. When compaction fires mid-session, it summarises the conversation. Short verbal instructions that are not in a bootstrap file are often dropped from the summary. The fix is to write critical instructions to AGENTS.md rather than stating them conversationally, and to use /remember for anything that must survive a compaction event.

How do I know if MEMORY.md is getting truncated?

Run /context list at the start of any session. It shows the character count and truncation status for every loaded file. If MEMORY.md is above 18,000 characters, you are close to the truncation ceiling. Prune older entries that are no longer relevant.

Can sub-agents access my USER.md preferences?

No. Sub-agents only receive AGENTS.md and TOOLS.md. If you want sub-agents to follow your tool preferences or project conventions, those rules must be written in AGENTS.md. SOUL.md and USER.md are filtered out before sub-agent context is assembled.

What happens to memories that OpenClaw archives after the FSRS retention window?

Archived memories move to a lower-priority retrieval tier but are not deleted. The agent can still retrieve them via memory_search if the query is specific enough. The FSRS scheduling just means they will not surface in general retrieval unless specifically requested.

Quick Takeaways – OpenClaw loses memory in three ways: no disk write, compaction stripping chat-only instructions, and file truncation at the 20,000 character limit – Five files create the permanent memory layer: SOUL.md, AGENTS.md, USER.md, MEMORY.md, and daily logs – memoryFlush.enabled: true is the single most important config change; without it, compaction fires without saving – Sub-agents only receive AGENTS.md and TOOLS.md; hard rules must live there to reach sub-agents – MEMORY.md is the source of truth; daily logs are the searchable archive; when they conflict, MEMORY.md wins – Run /context list, /verbose, and /remember to diagnose and confirm your setup