Skip to main content

Agent Workspace

The workspace is where the agent lives. It contains configuration, workspace context files, skills, logs, and memory data. The default local location is ~/.mushroom_agent/.

Directory layout​

~/.mushroom_agent/
├── config.yaml          # Main configuration file
├── prompts/             # Prompt files generated by init
│   ├── AGENTS.md        # Rules and constraints
│   ├── SOUL.md          # Persona and tone
│   ├── IDENTITY.md      # Self-identity
│   └── APPROACH_GREETING.md # Camera-approach greeting style
├── HEARTBEAT.md         # Workspace context: heartbeat checklist
├── skills/              # Local skills directory
├── memory/              # Agent memory storage
└── logs/                # Runtime logs

workspace.path is the path anchor for this layout. The local starter generated by mushroom-agent init points it at ~/.mushroom_agent/, and runtime derives skills/, memory/, and tool working directories from there.

Root-level AGENTS.md, SOUL.md, and IDENTITY.md remain supported for existing workspaces and take precedence over files in prompts/.

APPROACH_GREETING.md is event-scoped: it is read only when the camera proximity flow asks the agent to greet someone who has approached. It is editable from the local Prompts UI, but it is not injected into every turn as workspace context.

Workspace context files​

The agent reads these files at the start of each session and injects their contents into the system prompt:

FilePurposeWhen injected
AGENTS.mdProject rules, operating constraints, execution boundariesEvery turn (unless skipped)
SOUL.mdPersona and tone — voice, style, characterEvery turn (unless skipped)
IDENTITY.mdCanonical self-identity and roleEvery turn (unless skipped)
HEARTBEAT.mdHeartbeat checklist and guidanceOnly on heartbeat turns

All files are optional — only existing files in the workspace are loaded.

APPROACH_GREETING.md is intentionally separate from this table because it is not loaded globally. The runtime combines that file's greeting style guidance with code-owned dynamic facts, such as a recognized display name, and hard privacy constraints.

Loading behavior​

Files are loaded by load_workspace_context_files() and injected by render_workspace_context_message():

  • Files are read from the workspace root directory
  • They are loaded in order (AGENTS.md → SOUL.md → IDENTITY.md)
  • Each file is capped at 4000 characters
  • Total context across all files is capped at 12000 characters
  • Exceeding content is truncated with the marker: [truncated to fit prompt budget]
  • If IDENTITY.md is present, the agent treats it as the canonical self-identity source
  • Missing files are silently skipped (no marker injected)

Skipping context​

Set agent.skip_context_files: true in config.yaml to prevent any workspace context files from being injected. Sub-agents use this by default for isolation.

Sub-agent workspaces​

When spawned via delegate_task, sub-agents:

  • Skip workspace context files entirely
  • Run with quiet_mode: true
  • Receive task instructions via ephemeral_system_prompt
  • Share the same workspace directory as the parent

See also​