Understanding OpenClaw Memory: How Your Agent Remembers

Every time you start a new session with your OpenClaw agent, you might wonder: does it remember what we talked about last time? The answer depends entirely on how you configure memory. Out of the box, each conversation starts fresh. But with the right memory setup, your agent can retain project context, personal preferences, learned patterns, and accumulated knowledge across sessions. This guide explains every type of OpenClaw memory, how each one works, and how to configure them for your workflow.

Why Memory Matters

Without memory, every interaction with your agent starts from zero. You have to re-explain your project structure, remind the agent of your coding conventions, and repeat context that it should already know. This is not just annoying — it wastes tokens, slows down your workflow, and produces worse output because the agent lacks the context it needs to make good decisions.

Memory solves this by giving the agent persistent context that carries over between sessions. The agent reads this context at the start of every interaction, which means it already knows your project, your preferences, and the decisions you have made together.

The Memory Stack

OpenClaw uses a layered memory system. Each layer serves a different purpose and has different scope. Understanding the stack helps you put the right information in the right place.

CLAUDE.md — Your Primary Project Memory

CLAUDE.md is the most important memory file in the OpenClaw ecosystem. It lives in the root of your project directory and serves as the agent's primary briefing document. Every time the agent starts a session in your project, it reads CLAUDE.md first.

What belongs in CLAUDE.md:

• Project overview and architecture decisions
• Technology stack and versions
• Coding conventions and style guide preferences
• Build and deployment commands
• Important file paths and directory structure
• Common patterns used in the codebase
• Known issues and workarounds

Example CLAUDE.md structure:

# Project: Inventory Management API

## Stack
- Node.js 20, TypeScript 5.3, Express 4
- PostgreSQL 15, Prisma ORM
- Jest for testing, ESLint for linting

## Conventions
- Use functional programming patterns, avoid classes
- All API responses follow the envelope pattern: { data, error, meta }
- Database queries go through the repository layer, never direct ORM calls in routes
- Error handling uses custom AppError class in src/lib/errors.ts

## Commands
- Dev server: npm run dev (port 3001)
- Tests: npm test
- Lint: npm run lint
- Build: npm run build

## Directory Structure
- src/routes/ — Express route handlers
- src/repositories/ — Database access layer
- src/services/ — Business logic
- src/middleware/ — Express middleware
- src/lib/ — Shared utilities

This gives the agent everything it needs to work effectively in your project from the very first message of a new session.

Best practices for CLAUDE.md:

• Keep it concise. The agent reads this every session, so every word costs tokens. Aim for 200 to 500 words.
• Update it when your project changes. If you switch from Jest to Vitest, update CLAUDE.md immediately.
• Focus on things the agent cannot infer from the code itself. The agent can read your package.json to see your dependencies. It cannot read your mind to know that you prefer functional patterns over classes.

memory.md — Session-Persistent Learning

While CLAUDE.md is a static document you maintain manually, memory.md is designed for the agent to write to. It captures things the agent learns during sessions so it can reference them later.

What goes into memory.md:

• Corrections you have made ("I told you not to use semicolons, remember that")
• Preferences discovered through interaction ("The user prefers verbose error messages")
• Patterns identified during code review ("This codebase uses barrel exports in every directory")
• Decisions made during sessions ("We decided to use Redis for caching instead of in-memory cache")

How it works: When the agent encounters new information about your preferences or project, it writes an entry to memory.md. On subsequent sessions, it reads memory.md alongside CLAUDE.md to build a fuller picture of your context.

Configuration options:

[memory]
enabled = true
file = "memory.md"
max_entries = 100
auto_prune = true

The auto_prune setting removes the oldest entries when the file exceeds max_entries, keeping the memory file from growing indefinitely.

Best practices for memory.md:

• Review it periodically. The agent is not perfect, and it might record incorrect assumptions. Scan memory.md every few weeks and delete entries that are wrong or no longer relevant.
• Do not duplicate CLAUDE.md content. If something is important enough to be in CLAUDE.md, put it there. memory.md is for things that emerge organically from your interactions.

Project Memory — Shared Team Context

Project memory extends the concept of CLAUDE.md to team environments. When multiple people work on the same project, each person's agent needs access to the same baseline context.

How it works: Project memory files are committed to version control alongside your code. Every team member's agent reads the same project memory, which ensures consistency. When the tech lead updates the project memory with a new architectural decision, everyone's agent picks up that change on the next pull.

What belongs in project memory:

• Team coding standards and conventions
• Architectural decisions and their rationale
• Onboarding context that helps new team members' agents get up to speed
• Shared workflows and command references

What does not belong in project memory:

• Individual preferences (use personal memory for those)
• Sensitive information like API keys or credentials
• Temporary context that will change next sprint

User Memory — Personal Preferences Across Projects

User memory lives outside any specific project. It stores preferences and patterns that apply to everything you do, regardless of which project you are working on.

Examples of user memory:

• "I prefer TypeScript over JavaScript in all projects"
• "Always explain your reasoning before showing code"
• "Use American English spelling"
• "I am colorblind — do not use color as the only differentiator in explanations"

Configuration:

User memory is typically stored in your global OpenClaw configuration directory, which means it persists across all projects and sessions.

[user_memory]
enabled = true
path = "~/.openclaw/user-memory.md"

Best practices:

• Keep user memory focused on universal preferences. If a preference only applies to one project, put it in that project's CLAUDE.md instead.
• Be explicit. "I prefer concise responses" is better than "be brief" because it leaves less room for misinterpretation.

How the Memory Stack Loads

When you start a new session, the agent loads memory in a specific order. Understanding this order helps you know which memory takes priority when instructions conflict.

1. User memory loads first — your global preferences
2. Project memory loads second — shared team context
3. CLAUDE.md loads third — project-specific instructions
4. memory.md loads last — learned context from previous sessions

Later layers override earlier layers when there is a conflict. If your user memory says "use tabs" but the project CLAUDE.md says "use spaces," the agent follows the project instruction. This is the correct behavior — project conventions should override personal preferences.

Configuring Memory for Your Workflow

Solo Developer Setup

If you work alone, the simplest effective setup is:

1. Create a CLAUDE.md in every project with stack info, conventions, and commands
2. Enable memory.md for session-to-session learning
3. Optionally configure user memory for universal preferences

This covers ninety percent of solo developer needs.

Team Setup

For teams, add project memory to the mix:

1. Create a shared CLAUDE.md committed to version control
2. Establish a review process for changes to CLAUDE.md (treat it like code)
3. Each team member configures their own user memory for personal preferences
4. Enable memory.md per user (do not commit personal memory.md files)

Non-Developer Setup

If you use OpenClaw for writing, research, or analysis rather than coding, memory is even more important because the agent cannot infer your preferences from code.

1. Create a CLAUDE.md that describes your writing style, audience, and formatting preferences
2. Enable memory.md to capture corrections and refinements over time
3. Use user memory for preferences that apply across all your projects

Memory Maintenance

Memory is not a set-it-and-forget-it system. Regular maintenance keeps your agent sharp.

Monthly review: Read through CLAUDE.md and memory.md once a month. Remove outdated entries, update changed conventions, and consolidate redundant entries.

After major changes: When you refactor your project, upgrade a major dependency, or change a core architectural decision, update CLAUDE.md immediately. Stale memory is worse than no memory because the agent confidently follows outdated instructions.

When output quality drops: If the agent starts producing output that does not match your expectations, the first place to check is memory. Conflicting entries, outdated instructions, or an overly long memory file can all degrade performance.

Common Memory Mistakes

Putting everything in CLAUDE.md: If your CLAUDE.md is 2,000 words long, the agent spends too many tokens reading context and has less room for your actual conversation. Be ruthless about what goes in and what stays out.

Never reviewing memory.md: The agent writes to memory.md automatically, and it does not always get things right. Unchecked, memory.md can accumulate incorrect assumptions that degrade output over time.

Duplicating context across layers: If the same instruction appears in user memory, project memory, and CLAUDE.md, you have wasted tokens three times and created a maintenance burden. Put each piece of context in exactly one layer.

Ignoring memory for non-code projects: Writers and researchers benefit from memory just as much as developers. If you use OpenClaw for any recurring task, configure memory.

Your agent's memory is only as good as the context you give it. Invest a few minutes in setting up CLAUDE.md, configure memory.md for ongoing learning, and review both regularly. The payoff is an agent that feels less like a blank-slate chatbot and more like a colleague who knows your project inside and out.

Browse the Skills Directory

Find the right skill for your workflow. The OpenClaw Bazaar skills directory has over 2,300 community-rated skills — searchable, sortable, and free to install.

Browse Skills →

Want a Pre-Built Setup?

If you would rather skip the browsing, OpenClaw personas come with curated skill sets already configured. Pick a persona that matches your role and start working immediately. Compare personas →