Skip to content

Workspace Files#

Seven markdown files define each managed agent's identity, behavior, and context. All are loaded into the agent's context on every invocation — they shape how the agent thinks, communicates, and operates.

Overview#

File Purpose Editable by MCP tool
Soul Personality, values, boundaries, communication style User + Agent update_soul
User Profile User context, timezone, priorities, preferences User + Agent update_user_profile
Memory Summary Curated essential knowledge (always in context) Agent (primarily) update_memory
Heartbeat Natural language monitoring instructions User + Agent update_heartbeat_config
Vision Goals and objectives the agent works toward User + Agent update_vision
Agent Guide Operating manual: safety rules, coding workflow, behavioral constraints User only Edited in workspace editor
Bootstrap First-run onboarding script (cleared on completion) System clear_bootstrap

Soul#

Defines the agent's personality, values, boundaries, and communication style. This is the core of who the agent is.

Default template includes:

  • Communication style: skip pleasantries, have opinions, be direct
  • Safety boundaries: RBAC awareness, read-only by default, no credential hallucination, privacy boundaries
  • Capabilities awareness: which tools and systems the agent can access

How to customize: tell the agent through conversation ("Be more concise", "Always explain your reasoning before taking action") or edit directly in the workspace editor.

Example:

# Soul

You are an SRE agent for the platform team. You're direct, technical,
and opinionated. When something looks wrong, say so immediately.

## Boundaries
- Never modify production without explicit approval
- Always check current state before suggesting changes
- Escalate to the on-call channel if you detect a P1 incident

User Profile#

Stores context about the user: timezone, role, priorities, and preferences. The agent uses this to tailor its responses and actions.

How it's populated: the agent asks during bootstrap and updates as it learns more through conversation.

Example:

# User Profile

- Name: Sarah
- Timezone: America/New_York
- Role: Senior SRE
- Priorities: Production stability, deployment velocity
- Preferences: Brief alerts, detailed post-mortems

Memory Summary#

A curated summary of the most important knowledge the agent has accumulated. Unlike the memory database, the memory summary is always loaded into context — the agent sees it on every invocation.

Best used for: critical decisions, known issues, important patterns, key entity knowledge. Keep it concise — this is the agent's "cheat sheet," not a complete knowledge base.

How it's updated: the agent manages this file itself, distilling important information from conversations and investigations. You can also edit it directly.

Example:

# Memory Summary

## Known Issues
- Node pool `gpu-workers` has intermittent OOM kills (ticket INFRA-1234)
- CloudFront cache invalidation takes 15-20 min, not instant

## Key Decisions
- We use blue-green deployments for API services
- Database migrations run as pre-deploy hooks, never during traffic

Heartbeat#

Natural language instructions for what the agent should check during its monitoring cycle. The heartbeat file tells the agent what to watch.

Example:

# Heartbeat

Check the following every cycle:
1. Pod health in production namespace — report CrashLoopBackOff, Pending, OOMKilled
2. Node resource utilization — alert if any node exceeds 85% CPU or memory
3. Recent deployments — summarize any deployments in the last cycle
4. Certificate expiry — warn if any cert expires within 14 days

Updating this file via update_heartbeat_config automatically restarts the heartbeat timer.

Vision#

Goals and objectives the agent works toward. The agent reads this on every invocation and proactively advances these goals during heartbeats and conversations.

Example:

# Vision

1. Zero-downtime deployments across all services by end of Q2
2. Reduce mean time to recovery (MTTR) from 45 min to under 15 min
3. Automate all routine compliance checks (SOC 2, PCI)

Agent Guide#

The operating manual with safety rules, behavioral constraints, and workflow instructions. This is the only workspace file that agents cannot modify — it is editable only by users, through the workspace editor.

This separation is intentional: the Agent Guide defines the hard behavioral boundaries that the agent must follow. Users maintain control over these rules.

Example:

# Agent Guide

## Safety Rules
- Never delete resources in production without explicit user approval
- Always create a backup before modifying StatefulSet configurations
- If uncertain about the impact of a change, ask first

## Slack Etiquette
- Keep channel responses concise (< 3 paragraphs)
- Use threads for detailed analysis
- Tag the on-call engineer for P1 incidents

Bootstrap#

The first-run onboarding script. Present only for new agents. The agent follows this script during its initial conversation, asking about your environment and configuring itself. Once onboarding is complete, the agent clears this file and normal operation begins.

The bootstrap template supports placeholder variables:

  • {{agentName}} — the agent's name
  • {{teamName}} — the team the agent belongs to

These are automatically replaced when the agent is created.

You generally don't need to edit this file — it's managed by the system.

Editing Workspace Files#

Through conversation#

Tell the agent what to change:

Update your soul to be more formal in channel messages but casual in DMs.

The agent updates the relevant file and confirms the change.

Through the workspace editor#

Every agent has a workspace editor on the platform where any of its files can be opened and edited directly. The Agent Guide can only be edited this way — agents cannot modify their own operating manual.

Edit modes#

All workspace file tools (except clear_bootstrap) support two edit modes.

Full replacement — pass complete new content via the newContent parameter. Use for major restructuring or initial setup.

Tool: update_soul
Parameters:
  newContent: "New complete soul content..."
  changeDescription: "Restructured personality for security focus"

Targeted edits — pass an array of {oldText, newText} pairs via the edits parameter. Preferred for small, surgical changes.

Tool: update_memory
Parameters:
  edits:
    - oldText: "Production cluster: 3 nodes"
      newText: "Production cluster: 5 nodes (scaled up 2026-04-10)"
  changeDescription: "Updated node count after scaling event"

Every update requires a changeDescription string explaining what changed and why. This provides an audit trail of workspace file changes.

Tool Availability by Mode#

Not all workspace file tools are available in every invocation mode:

Tool Chat Heartbeat Scheduled task Subagent
update_soul Yes Yes No Yes
update_user_profile Yes Yes No Yes
update_memory Yes Yes Yes Yes
update_heartbeat_config Yes Yes No Yes
update_vision Yes Yes No Yes
update_settings Yes Yes No Yes
clear_bootstrap Yes No No No

Scheduled tasks cannot modify workspace files to prevent configuration drift from automated processes.