A workspace that hosts an agent is not the same shape as a workspace that hosts only a developer. The agent will read the files there at the start of every session, will form opinions about what they mean, and will use those opinions to decide what to do next. Files in an agent workspace are not documentation for humans; they are documentation for an interpreter that has preferences.

This piece is the dogfooding account. Triadive runs on these patterns itself; the file layout described here is the layout that runs this website. The patterns are not new — they have been stable in software teams for decades — but the way an agent reads them is new, and the discipline that keeps them sharp is new.

The patterns apply whether the workspace is a single project or a fleet of projects. The unit of hygiene is the project; the unit of consistency is the operator.

The core files and what each is for

A well-run agent workspace has, at minimum, four files. Each has a distinct job; mixing jobs is the most common hygiene failure.

AGENTS.md — the operating manual

AGENTS.md is the file the agent reads first. It says what the project is, what files the agent may touch, what files the agent must not touch, and what the agent should do when a task falls outside the named scope. It is the project-level layer of the system prompt composition.

A good AGENTS.md is short. It names scope, tools, memory use, refusal, and escalation. It does not name the agent's personality or the project's history. History belongs in MEMORY.md; personality belongs in SOUL.md; conventions and tooling specifics belong in TOOLS.md.

A bad AGENTS.md is a kitchen sink. It contains the project history, the team's values, every tool that has ever been tried, every incident that ever happened, and a long list of "always" and "never" that contradict each other. The agent reads all of it and follows none of it.

SOUL.md — the agent's voice and values

SOUL.md is the file that names how the agent should sound. Tone, voice, the values the agent is supposed to embody, the line between "honest pushback" and "sycophancy" — those belong here.

This file is short by design. It exists so the agent has a stable character across many sessions and many projects, so the operator can edit the character without editing the operating manual, and so the boundary between "what the agent should do" and "how the agent should sound" stays clean.

A common mistake is to merge SOUL.md into AGENTS.md. The mistake looks harmless; the consequence is that every voice edit becomes a scope edit, and every scope edit risks changing the voice. The two files exist separately so they can change separately.

TOOLS.md — environment-specific notes

TOOLS.md is the file that names the quirks of the local environment. Camera names, SSH hosts, TTS voices, paths to non-obvious credentials, conventions for naming files, the one line about why a particular CLI flag matters here. None of this is load-bearing for the operating manual; all of it is the difference between an agent that works and one that wastes an hour rediscovering a quirk.

TOOLS.md is the file most likely to grow without bound. The hygiene discipline is to prune it quarterly: anything that has not been needed in the last 90 days probably does not belong in the environment notes, because either it is no longer needed or it has been promoted to a more durable file.

MEMORY.md — the curated long-term memory

MEMORY.md is the file that holds the long-term notes the operator wants to keep. It is not a log; it is a curated summary. Daily notes go in dated files; the curated distillation goes here. The distinction is what separates a MEMORY.md that is useful from a MEMORY.md that has become a write-only graveyard.

The standard practice is to keep MEMORY.md short — a few pages at most — and to put day-to-day observations in dated files like memory/2026-08-09.md. The curated file is what the agent reads when it needs a fast orientation; the dated files are what the agent reads when it needs a specific day's context. Both are part of the memory model, and both have different jobs.

Daily notes as the spillover layer

Daily notes — one file per day, named by date — are the layer that absorbs everything that does not fit elsewhere. They are where the operator records observations, decisions, lessons, and small incidents. They are where the agent records the same.

The discipline that makes daily notes useful is indexability. A daily note that lives as 2026-08-09.md is greppable; a daily note that lives in notes/july/late-summer-9.md is not. The naming convention is part of the contract.

The discipline that makes daily notes survivable is rotation. Daily notes are append-only during the day; at the end of the day, the operator (or a scheduled job) extracts the durable lessons into MEMORY.md and discards the noise. Without rotation, the daily note folder becomes a swamp, and the agent stops reading it because it cannot find anything.

For the trade-off between daily notes and durable memory, see memory: short, long, and semantic.

What each file is not for

A useful way to keep the workspace clean is to name what each file is not for. The list is short:

  • AGENTS.md is not the place for project history. History goes in MEMORY.md or in the daily notes.
  • SOUL.md is not the place for tool conventions. Tool conventions go in TOOLS.md.
  • TOOLS.md is not the place for the operating manual. The operating manual goes in AGENTS.md.
  • MEMORY.md is not the place for everything the agent has ever seen. Daily notes are for the volume; MEMORY.md is for the distillate.
  • README.md is not a substitute for the four core files. README.md is for the human reader who has just cloned the repo; the four core files are for the agent that has just started a session.

The discipline is one job per file. When a file starts holding two jobs, it is time to split or to move one of them.

The anti-pattern: dumping everything into README

The single most common workspace failure is dumping everything into README.md. The failure mode is easy to spot: a README.md that is 3,000 words long, that mixes operating manual with voice with environment notes with curated memory with project history, and that the agent reads at session start and cannot parse.

The agent does not refuse to read a long README.md. It reads it all, weights every section equally, and produces a confused interior. The operator then concludes that the agent is broken. The agent is not broken; the operator handed it a junk drawer and expected it to find the screwdriver.

The fix is structural, not editorial. Split the file into the four core files by job. The README.md becomes short — a paragraph or two, plus a pointer to each of the four files. The agent reads the right file for the right question.

Explicit files vs implicit context

There is a real trade-off here. Explicit files have cost: every file is a thing the agent reads, a thing the operator maintains, a thing that can drift out of date. Implicit context — relying on what the agent already knows — has the opposite cost: the agent has to re-derive the convention every session, and may re-derive it differently.

The rule that resolves the trade-off: anything the operator wants the agent to follow reliably should be explicit; anything the agent already does well should be implicit.

"Always read MEMORY.md at session start" is explicit. "Use a friendly tone" is borderline — it could go in SOUL.md or it could be left to the model's defaults. The right answer depends on whether the operator has observed the agent defaulting to a tone that does not match the project's voice. If yes, make it explicit. If no, leave it implicit.

The cost of being too explicit is the cost of every file becoming a liability. The cost of being too implicit is the cost of every session producing slightly different behavior. The middle is the place where each rule earns its keep by being needed more than once.

Minimum viable workspace

A workspace that meets the bar without overengineering has exactly these files:

  • AGENTS.md — under 200 lines. Scope, tools, memory, refusal, escalation.
  • SOUL.md — under 50 lines. Voice, values, the pushback line.
  • TOOLS.md — under 200 lines, pruned quarterly.
  • MEMORY.md — under 5 pages. Curated long-term notes only.
  • memory/ — daily notes, one file per day, rotated.

Anything beyond this minimum is justified by a specific need, not by a vague sense that the workspace should be tidier. A workspace with five well-kept files is better than a workspace with fifty half-kept ones.

When the workspace serves multiple agents

A workspace that hosts more than one agent — a primary session plus sub-agents, or a multi-agent orchestration setup — has the additional question of which files each agent reads. The pattern that works is shared TOOLS.md and MEMORY.md, agent-specific AGENTS.md and SOUL.md.

Shared files hold things that are true for everyone in the workspace. Agent-specific files hold things that are true for one agent only. A SOUL.md that is shared across agents will eventually diverge from each agent's actual voice; better to keep it per-agent and let the operator edit one when its agent drifts.

For the deeper pattern of how sub-agents inherit and override the parent's operating context, see sessions and sub-agents.

Where the workspace meets the platform

The workspace files are not the whole picture. They are the project-level layer; they sit on top of an agent default and a platform default the operator may not see. When the project-level file contradicts the agent default, the agent default usually wins, silently. When the agent default contradicts the platform default, the platform default usually wins, silently.

The consequence is that some rules belong in the project file and some belong elsewhere. The hygiene discipline is to keep the project file honest about what it can and cannot control: a rule that needs to be enforceable must live in the right layer, and the project file is not always it.

For the platform-side view of these layers, see OpenClaw control on Mac and in the browser.

Workspace hygiene under scheduled work

Cron jobs and heartbeats compound the hygiene problem. A cron session starts cold; the only context it has is what it loads at intake. The agent does not have the operator's recent memory of what changed last week.

The discipline that keeps scheduled work legible is: every cron prompt must name the files it should read at intake, must name the files it must not touch, and must name the file where it should record its results. A cron that loads MEMORY.md and the daily notes, runs, and appends to the daily notes, is a cron that is auditable. A cron that reads whatever it feels like and writes wherever is a cron that cannot be debugged.

The cron pattern forces hygiene on the workspace, in the same way a disciplined API forces hygiene on the underlying data model. The workspace that cannot be loaded cold cannot be run on a schedule.

See also

  • [Sessions, Sub-Agents, and Child Sessions](/articles/concepts/sessions-sub-agents/) — how the workspace files flow into sub-agents.
  • [Memory: Short-Term, Long-Term, and Semantic](/articles/concepts/what-is-memory-short-long-semantic/) — the three-layer memory model that MEMORY.md and the daily notes are part of.
  • Cron Jobs and Heartbeats — scheduled work is where poor workspace hygiene becomes a production incident.
  • [OpenClaw Control on Mac and in the Browser](/articles/concepts/openclaw-control-mac-and-browser/) — the workspace layers above and below the project file.
  • Context vs Memory — the distinction this piece assumes throughout.