How to Set Up OpenClaw Workspace Memory Correctly: A Complete Guide
Problem
I was running OpenClaw for weeks with an empty workspace. Every session, my agent would wake up blank. It didn’t remember who I was. It didn’t remember what we discussed last week. It didn’t remember the architecture decisions we made.
I’d start each conversation explaining everything from scratch. The same project context. The same coding preferences. The same conventions we’d already agreed on. It was like Groundhog Day, but with AI.
Here’s what my setup looked like:
~/my-project/ .openclaw/ workspace/ # <-- completely emptyI assumed the agent would somehow figure things out on its own. I was wrong.
What Happened
I dug into the OpenClaw documentation and found the problem. Workspace is not a folder you create and forget. It’s long-term memory. A place where everything the agent needs between sessions lives.
The documentation was blunt about it:
“Without workspace the agent wakes up blank every single time. Doesn’t remember who you are. Doesn’t remember what you discussed last week.”
That explained everything. My agent had no place to store memories, so every session started from zero.
The documentation also mentioned something that hit home:
“Most setups fall apart in practice: no consistent place for decisions, so the agent keeps re-deriving the same answers.”
I’d seen this exact behavior. My agent would re-analyze problems we’d already solved. It would suggest approaches we’d already rejected. It would ask questions I’d already answered multiple times.
The Solution
I learned that OpenClaw workspace is just text files. Not a database, not binaries. Plain .md and .json files you can open in any editor.
The core structure looks like this:
~/my-project/ .openclaw/ workspace/ AGENTS.md # Agent's operating manual SOUL.md # Agent's personality and style USER.md # User profile and preferences MEMORY.md # Long-term memories logs/ 2026-03-11.md # Daily session logsEach file serves a specific purpose. Here’s what I learned about each one.
AGENTS.md - The Operating Manual
This file tells the agent how to operate in your project. It includes coding standards, workflow preferences, and project-specific rules.
# Project Operating Manual
## Code Style- Use TypeScript for all new files- Follow functional programming patterns- Maximum 400 lines per file
## Workflow- Write tests before implementation (TDD)- Run linter before each commit- Create feature branch for changes
## Communication- Be direct and matter-of-fact- Challenge my assumptions when needed- Don't repeat information I already know
## Project Context- This is a React frontend with Node.js backend- PostgreSQL database with Prisma ORM- Deployed on AWS with GitHub Actions CI/CDThe key insight: be specific. Vague instructions like “write clean code” don’t work. Rules like “maximum 400 lines per file” work because they’re measurable.
SOUL.md - The Personality
This file defines who the agent is. Not what it does, but how it behaves.
# Agent Personality
## Core Traits- You are a senior software engineer with 10+ years experience- You prefer simple solutions over clever ones- You value maintainability over performance optimization
## Communication Style- Be concise. Avoid long explanations when a short one works- Show code examples instead of describing them- Admit uncertainty. Say "I don't know" when appropriate
## Values- Correctness over speed- Readability over cleverness- Testing over assumptionsI initially didn’t think I needed this file. But after using it, I noticed the agent’s responses became more consistent. Same question, same style of answer. Every time.
USER.md - Who I Am
This file tells the agent about me. My experience level, my preferences, what I already know.
# User Profile
## Experience- Senior developer, 15 years experience- Strong in: Python, JavaScript, SQL- Learning: Rust, Go
## Preferences- I prefer detailed explanations for new concepts- I want to understand WHY, not just HOW- I like ASCII diagrams for architecture explanations
## What I Already Know- Don't explain basic programming concepts- Don't explain Git basics- Don't explain REST API fundamentals
## Current Goals- Building a personal blog system- Learning Rust for performance-critical components- Migrating from MongoDB to PostgreSQLThis file saves time every session. The agent doesn’t need to relearn my background. It knows what to explain and what to skip.
MEMORY.md - Long-Term Storage
This is where the agent stores decisions, insights, and important context across sessions.
# Long-Term Memory
## Architecture Decisions
### 2026-03-05: Chose PostgreSQL over MongoDB- Reason: Need complex queries and transactions- Migration plan: Start with read replicas, then migrate writes- Status: In progress
### 2026-03-08: Adopted functional programming style- Reason: Easier to test, fewer bugs- Convention: Use immutable data structures- Status: Enforcing in code review
## Active Context
### Current Sprint: User Authentication- Using JWT tokens with refresh mechanism- Password hashing with bcrypt- Rate limiting on login endpoint (5 attempts / minute)
## Learned Preferences- User prefers early return pattern over nested if-else- User likes TypeScript strict mode- User wants tests for all new functionsThe agent updates this file automatically. When we make a decision, it gets logged. When I correct its behavior, the preference gets stored.
Daily Logs - Session History
The logs/ folder contains dated files for each session:
# Session: 2026-03-11
## What We Did- Implemented user authentication endpoints- Added password reset flow- Fixed rate limiting bug
## Decisions Made- Token expiry: 1 hour for access, 7 days for refresh- Password requirements: 12+ chars, mixed case, number, symbol
## Tomorrow's Focus- Add OAuth integration- Write integration tests for auth flow
## Questions to Follow Up- Should we add 2FA? Need to discuss tradeoffs.These logs create a trail. When I come back after a week away, I can read the recent logs and catch up quickly.
How It Works
The agent reads these files at the start of each session. The context becomes part of its working memory.
┌─────────────────────────────────────────────────────────────┐│ New Session Starts │└─────────────────────────────────────────────────────────────┘ │ ▼┌─────────────────────────────────────────────────────────────┐│ Agent reads workspace files: ││ 1. AGENTS.md - How to operate ││ 2. SOUL.md - Who to be ││ 3. USER.md - Who you are ││ 4. MEMORY.md - What happened before ││ 5. Recent logs - Latest context │└─────────────────────────────────────────────────────────────┘ │ ▼┌─────────────────────────────────────────────────────────────┐│ Agent now has full context: ││ - Knows your coding preferences ││ - Remembers past decisions ││ - Understands project architecture ││ - Has your experience level calibrated │└─────────────────────────────────────────────────────────────┘ │ ▼┌─────────────────────────────────────────────────────────────┐│ Session progresses with persistent memory │└─────────────────────────────────────────────────────────────┘ │ ▼┌─────────────────────────────────────────────────────────────┐│ Agent updates MEMORY.md and creates daily log │└─────────────────────────────────────────────────────────────┘The magic is that all of this is just text files. I can read them, edit them, version control them. Nothing is hidden in a database I can’t access.
Common Mistakes
I made several mistakes setting up my workspace. Here’s what I learned:
1. Creating empty placeholder files
# TODO: Add agent instructionsEmpty files don’t help. The agent reads them, gets nothing, and operates with defaults. Start with at least basic content in each file.
2. Putting everything in one file
# MEMORY.md
## Agent Operating Manual- Use TypeScript- Run tests before commit- ...
## User Preferences- I like detailed explanations- I have 15 years experience- ...
## Long-Term Memory- Decided to use PostgreSQL- ...This works, but it’s harder to maintain. Separating concerns into different files makes it easier to find and update specific information.
3. Forgetting to version control
The workspace folder should be in git. When I make changes to AGENTS.md, I want a history. When the agent updates MEMORY.md, I want to see what changed.
git add .openclaw/workspace/git commit -m "Update agent operating manual"4. Not updating regularly
Workspace files become stale if you don’t update them. The agent can write to MEMORY.md and logs, but AGENTS.md and USER.md need manual updates when your project changes.
I set a reminder to review workspace files every sprint:
- [ ] Is AGENTS.md still accurate for current project phase?- [ ] Has USER.md changed (new skills, new preferences)?- [ ] Any MEMORY.md entries that should be archived?- [ ] Are daily logs useful or just noise?Testing Your Setup
After creating the workspace files, test that they work:
- Start a new session
- Ask the agent about a previous decision
- Check if it references information from MEMORY.md
- Check if it follows rules from AGENTS.md
- Check if it adapts to your level from USER.md
If the agent doesn’t mention workspace content, something is wrong. It should naturally reference decisions, follow your rules, and match your experience level.
Summary
In this post, I showed how to set up OpenClaw workspace memory correctly. The key is creating structured markdown files that give your agent persistent context across sessions.
The workspace structure:
AGENTS.md- Operating manual for your projectSOUL.md- Agent personality and styleUSER.md- Your profile and preferencesMEMORY.md- Long-term decisions and contextlogs/- Daily session history
After implementing this setup, my agent stopped waking up blank. It remembers our decisions, follows my preferences, and maintains consistent behavior across sessions. The 30 minutes I spent creating these files saved hours of re-explanation.
Final Words + More Resources
My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me
Here are also the most important links from this article along with some further resources that will help you in this scope:
Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!
Comments