Understand OpenClaw's Persistent Memory Before It Loses Your Work

OpenClaw crossed 250,000 GitHub stars in March 2026, overtaking React to become the most-starred project in GitHub's history at that point. That number says a lot about developer appetite for local-first agents. It says almost nothing about whether the memory system will hold up across a month of real work.

The memory architecture is the part that matters most for any long-running agent, and it is also the part most documentation glosses over.

What OpenClaw's memory system actually is

OpenClaw's persistence layer is file-based, not database-backed. The memory architecture is built on plain text files and an SQLite database with the sqlite-vec extension for vector embeddings. Several Markdown files store facts the agent loads as context, alongside a memory.sqlite containing chunked text and vector embeddings for semantic search.

In practice, long-term memory runs through two mechanisms: SOUL.md files that define personality and behavioral guidelines, and MEMORY.md files that store accumulated knowledge. Both are stored as plaintext Markdown files in ~/.openclaw/ and are loaded into the LLM's context at startup.

The agent also keeps a timeline. Daily logs live in memory/YYYY-MM-DD.md as append-only files, and every significant decision, task summary, and notable event gets timestamped and written there.

What makes this interesting is what it deliberately avoids. Everything stays on your machine - no cloud vector stores, no external APIs for memory retrieval. You can open MEMORY.md in any text editor, read exactly what the agent knows, and change it. That auditability is the real selling point, and it is genuine.

Long-term memory is curated by the agent itself. As conversations happen, the agent decides what is important enough to remember permanently - standing instructions, preferences, recurring patterns - and writes them to long-term memory files that persist across sessions.

The headache, which the docs understate: you are now responsible for managing a growing pile of files across potentially multiple agent workspaces, and MEMORY.md gets truncated in context if it outgrows the bootstrap budget.

The compaction gap nobody documents clearly

This is the non-obvious part. OpenClaw does not write to memory continuously - it writes when the session compacts.

OpenClaw's memory system relies on session compaction as the trigger for writing summaries to memory, and compaction only fires when a session approaches the model's context limit.

That design worked well when context windows were 8K or 16K tokens. It breaks for modern agents.

With modern context windows of 200K+ tokens, short sessions - particularly heartbeat-driven sessions - may never approach the context limit. A typical heartbeat session might be 500 tokens. With a 200K context window, it would need to run roughly 400 times before triggering compaction.

This creates a critical failure mode: the heartbeat fires, a new short session opens, the agent does work, the session ends - then repeats every 15 minutes, never hits the context limit, never compacts, never writes to memory. Thousands of dollars of agent work and weeks of heartbeat cycles, with zero memory persistence. All that pattern data evaporates when sessions close.

When conversations do get long enough to compact, the summary itself is lossy. The agent forgets corrections and starts drifting without telling you.

The workaround developers have converged on is explicit pre-compaction instructions baked into AGENTS.md: instruct the agent to save key facts to a daily log file before compaction runs. When context crosses a soft threshold, OpenClaw injects a silent turn telling the agent to save important context now. The agent writes to memory files, then compaction proceeds. But memoryFlush.enabled needs to be verified in config - it is not always on by default in older installations.

What OpenClaw 2.0 changed - and what it did not

OpenClaw 2.0, version tag v2026.8.1, released August 30, 2026, is the largest update in the project's history, built by 933 contributors with more than 16,000 pull requests merged.

The headline feature is shared cloud sessions - multiplayer. The release moves sessions into SQLite and adds shared cloud sessions alongside a rebuilt browser app.

The caveat matters for any team thinking about using it in a shared workspace. Shared cloud sessions turn OpenClaw into a multiplayer tool, with owners deciding who can read, suggest, draft, or participate directly. The project is explicit about the limits: these controls are not tenant isolation or a security boundary, and revoked access can briefly look available until the UI refreshes or the Gateway rejects the action.

Security remains operator responsibility: shared sessions are collaboration controls, not tenant isolation. The Secret Store is not encrypted at rest by default, and sandboxing is off by default.

The session data migration is also a one-way door. Sessions and transcripts move into SQLite. If you later want to downgrade to an older file-backed release, you have to use the current CLI to restore archived legacy transcript artifacts first - and sessions created after the migration will not appear in the older build at all.

What 2.0 did not fix is the memory/compaction mismatch described above. That is an open GitHub issue as of the latest stable release. If your agent runs frequent short heartbeat cycles, memory persistence still depends on you configuring explicit pre-compaction saves or switching to an external memory layer like Mem0.

Before you run this in a team context

The architecture is genuinely novel: a local-first agent runtime with file-based memory you can read and edit, an autonomous heartbeat loop, and a plugin ecosystem (ClawHub) that installs new skills as Markdown files with no recompilation. OpenClaw uses a skill-based architecture where capabilities are defined in Markdown files, not compiled code. Each skill is a SKILL.md file containing instructions for interacting with APIs or performing workflows, and the agent reads them at runtime.

That openness is also the main risk surface for team deployments.

Many deployments grant OpenClaw broad permissions across the operating system, browser sessions, SaaS applications, local files, APIs, and cloud environments. This creates an extremely large blast radius if the agent is compromised, manipulated, or behaves unexpectedly.

A single malicious email, chat message, or web page can trick the assistant into leaking credentials, internal files, or cross-session conversation histories in a matter of minutes.

The specific data leakage vector for multi-user setups is worth understanding: OpenClaw's default design puts all DMs into one shared session, and the bot recognizes all incoming DMs as belonging to a single entity. It fails to maintain proper boundaries between different people. The dmScope config setting controls this, but it requires deliberate configuration.

If your OpenClaw setup has filesystem tools turned on and stores API tokens or OAuth credentials in plain text files, those secrets are readable. Agents also paste full environment variables into logs, chat windows, or external servers during debugging sessions.

A teammate like Beagle, operating inside Slack's permission model with a human approving every action before it posts, sidesteps this class of problem by design - the execution surface is narrower and the audit trail is per-message.

The honest summary: OpenClaw's persistent memory is the right idea with real implementation gaps. The file-based approach is auditable and portable in a way cloud memory layers are not. But the compaction-as-persistence-trigger is a design assumption that breaks against large context windows, and the 2.0 shared session feature adds a multiplayer interface without adding tenant-level isolation. Run it with those constraints in mind.

OpenClaw persistent memory: common questions

What files does OpenClaw use to store memory?

OpenClaw stores long-term memory in MEMORY.md (durable facts), SOUL.md (agent personality and rules), and daily log files named by date (episodic context). All files are plain Markdown in ~/.openclaw/, loaded into the LLM context at session start. You can read and edit them in any text editor.

Why does my OpenClaw agent forget things between sessions?

The most common cause is that memory only writes during session compaction, which only triggers when context approaches the model's limit. With 200K-token context windows, short heartbeat sessions may run hundreds of times without ever compacting - and therefore never writing to memory. Set memoryFlush.enabled: true or add explicit pre-compaction save instructions to AGENTS.md.

Is OpenClaw 2.0's shared session feature safe for team use?

Shared sessions are collaboration controls, not security boundaries. The project documents this explicitly: revoked access can briefly appear available, the Secret Store is not encrypted at rest by default, and sandboxing is off by default. For multi-user deployments, configure dmScope carefully and treat session data as sensitive.

How does OpenClaw's heartbeat interact with memory persistence?

The heartbeat wakes the agent at a configurable interval (default 30 minutes) and loads full context each time. Because heartbeat sessions are short, they rarely hit the compaction threshold that triggers memory writes. Setting isolatedSession: true per heartbeat run avoids context bleed, but means each cycle starts fresh with no accumulated context from prior runs.

Can you replace OpenClaw's memory with an external layer like Mem0?

Yes. Mem0's integration guide covers wiring it as a replacement for the MEMORY.md-based system. The main advantage: Mem0 runs persistence outside the agent's own decision-making, so recall does not depend on the model choosing to read or write a file during any given session.