Templates

MushroomAgent loads workspace context files to customize the agent's behavior, persona, and operating constraints. Place these files in your workspace directory and the agent reads them at the start of each session.

How it works

When the agent starts a session, it scans the workspace for recognized filenames and loads them as context. Each file has a specific purpose — the agent uses them to understand its rules, identity, and operating boundaries.

Recognized files

File	Purpose
AGENTS.md	Project rules, operating constraints, and execution boundaries
SOUL.md	Persona and tone — voice, style, and character
IDENTITY.md	Canonical self-identity, role, and self-description
HEARTBEAT.md	Heartbeat checklist and heartbeat-specific operating guidance

Files are optional — only those that exist in the workspace are loaded. The agent reads them as raw context and applies them when relevant during the think phase.

File placement

~/.mushroom_agent/
├── config.yaml
├── 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        #
├── memory/
├── logs/
└── skills/

Root-level AGENTS.md, SOUL.md, and IDENTITY.md are still supported and take precedence over files in prompts/ when both exist.

APPROACH_GREETING.md is also generated under prompts/, but it is event-scoped rather than global workspace context. The camera-approach greeting flow reads it when someone walks up, then the runtime adds dynamic facts and hard privacy constraints in code.

Loading behavior

• Files are loaded at session startup and injected into the agent's context prompt
• Each file is loaded as a separate context section
• Files exceeding 4000 characters are truncated (configurable via max_file_chars)
• Total context from all files is capped at 12000 characters (configurable via max_total_chars)
• If IDENTITY.md is present, the agent treats it as the canonical self-identity source

Customizing

Simply create these files in your workspace directory with the content you want. The agent will pick them up on the next session or restart.