Workspace & Memory

Your agent's workspace is where it lives. Memory is how it learns. Here's how to set both up effectively.

The Workspace

Every agent has a workspace directory — a folder on your machine where the agent can read and write files. This is the agent's home base.

Why It Matters

Without a workspace, your agent is stateless. It forgets everything between conversations. With a workspace:

• The agent can save and read files
• It maintains memory across sessions
• It can work on projects over time
• It has context about who you are and what you're working on

Setting Up a Workspace

When you create an agent, OpenClaw sets up a workspace directory. You can also use a Git repository as a workspace:

mkdir ~/Github/my-agent
cd ~/Github/my-agent
git init

Then point OpenClaw to it during agent configuration.

Key Workspace Files

AGENTS.md — Session Instructions

Read by the agent at the start of every session. Think of it as the agent's morning briefing:

# AGENTS.md

## Every Session
1. Read SOUL.md — who you are
2. Read USER.md — who you're helping
3. Read today's memory file
4. Read MEMORY.md for long-term state

## Safety
- Keep private data local
- Never publish without approval

USER.md — About You

Tell the agent who it's working with:

# USER.md

- **Name:** Alex
- **Timezone:** PST
- **Interests:** AI/ML, web development
- **Preferences:** Concise responses, code examples over theory

This helps the agent tailor its responses to you.

SOUL.md & MEMORY.md

Covered in the Agents guide.

Memory System

OpenClaw agents have a two-tier memory system:

1. Daily Memory (memory/YYYY-MM-DD.md)

Short-term, day-by-day notes. The agent writes these automatically or you can structure them:

memory/
├── 2026-03-19.md
├── 2026-03-20.md
└── 2026-03-21.md

Each file captures what happened that day — conversations, decisions, work completed.

2. Long-Term Memory (MEMORY.md)

The big picture. Active projects, preferences, important decisions. The agent reviews this every session and updates it periodically.

How Memory Search Works

When you ask about something from a past conversation, the agent searches through its memory files using semantic search. It finds relevant snippets and pulls the context it needs.

This means your agent can:

• Remember what you talked about last week
• Track project progress over time
• Recall your preferences without being reminded

Tips for Good Workspaces

1. Keep it in Git. Version control means you can always recover if something goes wrong. Set up automatic backups.
2. Organize with directories. Use drafts/, projects/, references/ — whatever makes sense for the agent's role.
3. Write good seed files. The quality of SOUL.md, USER.md, and AGENTS.md directly impacts how useful the agent is. Spend time on these.
4. Let memory accumulate. The agent gets better over time as it builds context. Don't clear memory unless you have a reason to.