When an agent starts a session, it does not start empty. It starts with a set of files it can read — operating instructions, personality and principles, environment notes, long-term knowledge, project folders, and secrets. That set of files is the workspace. It is the agent's home directory, its memory bank, and its operating manual, all at once.

This piece is a practical first-day guide. It covers what a workspace is, what the minimum viable version looks like, which files you cannot skip, which files you add second, and what you should never put at the root.

What a workspace is

Think of the workspace as a directory tree. At the top is a root — usually ~ or a project folder — and underneath are the files the agent can reach. When the session starts, the agent reads certain files first: the operating instructions, the voice and principles, the environment notes, the long-term knowledge, and the relevant project folders. Those files become the agent's context before the first user message arrives.

The mental model: workspace equals filesystem as context. The agent reads files, and those files are its memory. When it writes a summary to a memory file, that summary becomes available to the next session. When it retrieves a secret from an environment variable, that secret is available without re-entry.

The practical implication: the workspace is the agent's interface to the world. The files in it determine what the agent can perceive, what it can do, and what it will do when no one is watching.

The minimum viable workspace

A workspace that actually works has three things: an operating instructions file, a long-term memory file, and one project folder. That is the floor. Everything else is optional, and most of it can be added later.

What you do not need on day one: a skills directory, a scripts directory, a wiki, a daily-notes folder, or a glossary. Those emerge as patterns emerge. A workspace that starts minimal and grows as patterns appear is healthier than a workspace that starts comprehensive and accumulates files nobody reads.

The temptation is to front-load everything — to write the perfect operating instructions file, to fill the memory file with every fact that might matter, to create directories for things that do not exist yet. The problem with front-loading is that you are guessing. You do not yet know which files you will actually use, which patterns will persist, and which directories will become clutter.

The file you cannot skip: AGENTS.md

The operating instructions file is the one file a workspace cannot run without. In OpenClaw, it is conventionally named AGENTS.md. It lives at the root of the workspace and is read at the start of every session.

What goes in it: the operator's operating principles, the do and do-not list, pointers to other files that carry specialized knowledge, the workspace layout convention, and the agent's priorities when instructions conflict. The AGENTS.md file is the operator's interface to the agent's judgment — it is where the operator encodes the things the agent should know without being told every time.

What does not go in it: long memory (that is the memory file), secrets (those belong in environment variables or a keychain), project content (that belongs in the project folder), and debugging logs. The file should be short enough to actually read at the start of every session. A file that is 500 lines long is not an operating manual — it is a book report that nobody reads.

The test: if the agent reads it and does not know what to do next, the file is too short. If the agent reads it and nothing changes, the file is too long or too vague.

The file you add second: MEMORY.md

The long-term memory file is where durable facts live — the things the agent should know across sessions: entity names and roles, current project status, key decisions, credential locations (not the credentials themselves), API endpoints, tax filing status. The MEMORY.md file is the curated record of what the operator has decided to make persistent.

What does not go in it: recent activity (that belongs in daily notes), debugging logs, and session transcripts. Memory is what you want the agent to know the first time it starts a new session. Daily notes are what happened in a specific session that may or may not matter later.

Memory is written to be read — it should be coherent enough that a human could read it and understand the state of the workspace. Daily notes are written to be processed — they are timestamped and rough. When a daily note entry becomes a standing decision, it graduates to memory. When it becomes stale, it is deleted.

The piece on memory: short, long, and semantic covers the three memory layers and why the distinction between memory and daily notes is the first memory design decision.

Project folders

A project gets its own folder when it meets one of four conditions: it has its own entity or legal identity, its own deployment, its own scheduled work, or its own memory that should not mix with other projects. Not before.

A personal workspace with one project does not need a project folder — the workspace root is the project. A workspace with two or three unrelated projects — a business entity, a content site, a personal project — should have separate folders, because the agent's memory about each should not blend.

The rule: if the agent would be confused by having the files in the same folder, or if the operator would be confused by searching for a file and finding files from a different project, they should be in separate folders.

The glossary entry on context versus memory covers the foundational distinction: context is what the model sees in the current call, memory is what survives between calls. Project folders are part of the memory layer — they persist across sessions and carry the state of each project forward.

The daily notes

Daily notes are timestamped entries — typically memory/YYYY-MM-DD.md — that record what happened in a specific session: what was decided, what is open, what the agent was asked to do, and what the outcome was.

The value of timestamped daily notes is that they are recoverable. When something goes wrong in a session, the daily note from that day is the first place to look. When the agent produces a summary that later turns out to be wrong, the daily notes are what the operator uses to check whether the agent's memory has drifted.

The risk is treating daily notes as a scratchpad rather than a log. A note that is overwritten each day is not a daily note — it is a single-session scratchpad with a date on it. The practical discipline: append to daily notes, do not overwrite them. The file should grow over time, not cycle.

The piece on how an agent understands covers the three places model — context, memory, and pattern-matching — and why a fact with no place at all produces silence or a guess. Daily notes are the mechanism for putting a fact into the memory layer so it survives the session.

What not to put at the root

The workspace root is the entry point, not a general-purpose directory. The files at the root should be the files the agent needs at the start of every session.

What should not be at the root: live website content, generated HTML files, large binaries, plaintext credentials, and anything the agent would not need to read at session start. These belong in subdirectories — the project folder for website content, a scripts/ directory for scripts, a secrets/ directory that the agent reads via environment variables.

The audit pattern: ask of every file at the root, "does the agent need to read this at the start of every session?" If the answer is no, the file belongs in a subdirectory. The root should answer the question "what is this workspace and what is the agent supposed to do here" without requiring the agent to read through a list of unrelated files.

The piece on workspace organization and project hygiene covers the conventions in depth — AGENTS.md, SOUL.md, TOOLS.md, MEMORY.md, and where each belongs.

How a workspace grows

The honest trajectory is: minimal first week, expand as patterns emerge, archive or delete what is not used.

The first week: three files — AGENTS.md, MEMORY.md, and one project folder. The operator runs sessions, the agent writes daily notes, and patterns start to appear.

The second month: the operator has a sense of what files they actually use. The workspace has grown in the directions that were actually needed, not the directions that seemed important when planning ahead.

The sixth month: files have accumulated that are not being used. The healthy practice is the archive pass: move what is not being used to an archive, delete what is obviously dead, keep what is live.

The discipline is the same throughout: the workspace should serve the operator, not the other way around. A workspace that requires constant maintenance to stay organized is a workspace that started with too much structure.

What this is not

This piece is not a reference for OpenClaw-specific conventions. The file names — AGENTS.md, MEMORY.md, SOUL.md, TOOLS.md — are OpenClaw conventions; other runtimes implement them differently. The underlying concepts apply broadly.

This piece is not a guide to the memory system. The memory: short, long, and semantic piece covers the three memory layers in depth.

This piece is not a guide to workspace safety. The piece on sandbox and terminal safety covers the threat model and the discipline of bounding what the agent can do.

See also