OpenClaw solves AI conversation forgetfulness with a combination of short-term context and long-term file-based memory. The core pattern uses
MEMORY.mdas an index and stores durable knowledge in four file types:user,project,feedback, andreference. Keywords: OpenClaw, memory system, MEMORY.md.
| Parameter | Description |
|---|---|
| Project/Topic | OpenClaw memory system configuration |
| Language/Format | Markdown, YAML Front Matter |
| Storage Method | Current session context + persistent memory/ directory |
| Core Protocol/Mechanism | File index loading, on-demand retrieval, cross-session persistence |
| GitHub Stars | Not provided in the source; cannot be confirmed |
| Core Dependencies | MEMORY.md, user_profile.md, project_*.md, feedback_*.md, reference_*.md |
OpenClaw uses a two-layer memory architecture to solve AI forgetfulness.
The core limitation of traditional chat-based AI is not generation quality, but the inability to preserve state across sessions. Every time users start a new conversation, they must restate their identity, project status, and output preferences. That repeated synchronization increases collaboration cost over time.
OpenClaw splits memory into two layers: short-term memory handles the current task, while long-term memory preserves continuity across sessions. The former depends on the context window; the latter lives in the workspace file system and works well for high-value information that changes infrequently.
~/.openclaw/workspace/memory/
├── MEMORY.md # Memory index
├── user_profile.md # User profile
├── project_openclaw.md # Project background
├── feedback_doc_style.md # Feedback log
└── reference_docs.md # External referencesThis directory structure defines the minimum viable skeleton for long-term memory.
AI Visual Insight: This image serves as the article’s primary visual and emphasizes the themes of AI forgetfulness and memory persistence. It works well as a chapter cover for memory systems rather than as a detailed architecture diagram, so it communicates concepts rather than executable configuration details.
MEMORY.md should be designed as an index, not a content repository.
Whether long-term memory works reliably depends less on how many files you have and more on whether the entry point is clear. MEMORY.md should do exactly one job: tell the AI what memories exist and what problem each one solves.
If you dump all content directly into MEMORY.md, the AI will load redundant information at startup, retrieval efficiency will drop, and conflicts will become harder to maintain. The correct pattern is simple: one memory per file, and the index stores descriptions only.
# Memory Index
- [User Profile](user_profile.md) — Professional background, work preferences, communication style
- [Project: OpenClaw Practical Series](project_openclaw.md) — Series goals, progress, output conventions
- [Feedback: Documentation Style](feedback_doc_style.md) — Confirmed writing constraints
- [Reference: Resource Library](reference_docs.md) — Frequently used document links and pathsThis index lets the AI selectively read memory files based on the task context.
Long-term memory works best when split into four types.
The first type is user, which answers the question “Who am I?” It describes profession, toolchain, writing style, and collaboration preferences, helping the AI quickly match the right communication mode in a new task.
The second type is project, which answers the question “What are we working on now?” It should record project goals, phase progress, constraints, and key output paths, so you do not need to resynchronize project context every time.
---
name: Project: OpenClaw Practical Guide Series
type: project
---
Series goal: Continuously publish practical OpenClaw articles
Current progress: Completed 01-19, currently writing 20-21
Writing conventions: Lead with the conclusion, keep paragraphs short, optimize for mobile reading
Save path: ~/.openclaw/workspace/reports/articles/This configuration converts project state from “chat memory” into “file memory.”
Feedback records are the highest-compounding memory asset.
The third type is feedback. It is not a casual note. It is a behavioral constraint derived from correcting the AI. Anything that falls into the category of “the AI got this wrong before and should not get it wrong again” belongs here.
The fourth type is reference. It does not store the body of knowledge itself. Instead, it stores where external documents live and what they are used for, so the AI can trace back to the source when needed instead of answering from vague recollection.
---
name: Feedback: Article Structure
type: feedback
---
Rule: Once the article structure is confirmed, do not skip confirmation and jump straight into drafting
Reason: A previous mismatch in structure caused rework
Scope: All technical writing tasksThis feedback memory can significantly reduce the recurrence of similar errors.
Memory writes must follow the principles of high value, low redundancy, and reusability.
Four categories of information are appropriate for long-term memory: things the user explicitly asks the AI to remember, corrections made to the AI, confirmed non-obvious decisions, and major project state changes.
It is equally clear what should not go into long-term memory: information that can be derived directly from the code, temporary intermediate states, and rules that already exist in AGENTS.md or SOUL.md. Storing those again only creates conflicts.
from pathlib import Path
memory_root = Path.home() / ".openclaw/workspace/memory"
index_file = memory_root / "MEMORY.md"
# Core logic: ensure the memory directory exists
memory_root.mkdir(parents=True, exist_ok=True)
# Core logic: write the index template during first-time initialization
if not index_file.exists():
index_file.write_text("# Memory Index\n", encoding="utf-8")This code initializes the OpenClaw long-term memory directory and index file.
Memory retrieval should be triggered by the task, not by indiscriminate full loading.
In real collaboration, the AI does not need to read all memories every time. A better approach is to read MEMORY.md first and then decide which files to load based on the current task.
For example, if the user says, “Continue the last OpenClaw article,” the system should prioritize the corresponding project and feedback files. If the user switches to a new topic, the system should keep only user memory and general rules, reducing irrelevant context usage.
Memory conflicts must be resolved against current facts.
Long-term memory is not absolute truth. It is a compressed snapshot of historical state. When file content conflicts with the current state of the project, trust current facts first and then write the correction back to the memory file. Otherwise, the system will keep amplifying outdated information.
## Run on every startup
1. Read `memory/MEMORY.md` and identify available memories
2. Load relevant memory files for the current task
3. Mark memories not updated for more than 30 days as "needs verification"
4. If conflicts are found, update the original memory based on current factsThis startup checklist can be added directly to BOOT.md to automate memory governance.
A memory system avoids information decay only with continuous maintenance.
The most common problem in long-term memory is not missing information, but stale information. Once paths change, projects end, or rules become invalid, old memories start to mislead the AI and create the illusion that it “knows you” while actually reading an outdated record.
Review the system at least once a month: remove completed projects, update the user profile, verify reference links, and fix broken paths. feedback files deserve special attention. Keep the rules that continue to generate value, and retire one-off constraints.
You can complete a minimum viable setup in three steps.
First, create memory/ and MEMORY.md. Second, add a user profile and the current project background. Third, convert the three most recent critical corrections into feedback files. At that point, cross-session AI stability will improve noticeably.
FAQ
What is the essential difference between short-term memory and long-term memory?
Short-term memory depends on the current conversation context and disappears when the session ends. Long-term memory is stored in files under memory/, persists across conversations, and is suitable for user preferences, project background, and correction rules.
Why should MEMORY.md not contain all content directly?
Because its job is indexing, not storing the knowledge body itself. Putting everything into it creates redundant loading, makes maintenance harder, increases conflicts, and reduces retrieval efficiency.
Which type of memory is most worth writing first?
Prioritize feedback. It directly records mistakes the AI has already made and should not repeat, so it delivers the strongest long-term improvement in collaboration quality and the clearest compounding effect.
Core Summary: This article systematically breaks down OpenClaw’s two-layer memory architecture, explains how short-term context and the long-term memory/ directory work together, and provides practical templates, write triggers, retrieval logic, and maintenance methods for MEMORY.md, user profiles, project background, feedback logs, and reference files. The goal is to help AI evolve from a session-bound tool into a sustainable digital collaborator.