Skip to main content

​
What is a Workspace?

Every agent in Havoc has a workspace — a collection of markdown files that define the agent’s behavior, persona, tools, and memory. These files are injected into the agent’s context on every interaction.

​
Workspace Files

FilePurposeAuto-injected
AGENTS.mdOperating instructions, memory rules, prioritiesYes
SOUL.mdPersona, tone, communication style, boundariesYes
TOOLS.mdLocal tool notes and conventionsYes
IDENTITY.mdAgent name, vibe, emojiYes
USER.mdUser profile, preferences, how to address themYes
MEMORY.mdCurated long-term memory (main session only)Yes
HEARTBEAT.mdOptional heartbeat checklistYes
BOOTSTRAP.mdOne-time first-run ritual (deleted after use)Yes
Each workspace file is limited to 20,000 characters by default (bootstrapMaxChars). Keep files concise and focused.

​
AGENTS.md — The Brain

This is the most important file. It defines how your agent operates: 
# Operating Instructions

## Priority 1: Customer Support
- Always greet users by name if known
- Escalate billing issues to human support
- Never share internal system details

## Priority 2: Memory
- Save important user preferences to MEMORY.md
- Log daily interactions to memory/YYYY-MM-DD.md

## Priority 3: Tools
- Use web_search for current information
- Use browser for interactive research
- Never execute destructive commands

​
SOUL.md — The Persona

Define how your agent communicates: 
# Persona

You are Alex, a friendly and professional customer support agent.

## Tone
- Warm but efficient
- Use simple language, avoid jargon
- Be empathetic when users are frustrated

## Boundaries
- Never pretend to be human
- Always disclose you are an AI assistant
- Redirect medical/legal questions to professionals

​
Memory System

Havoc agents have a two-tier memory system:

​
MEMORY.md (Curated)

  • Injected into every conversation
  • Contains important facts, preferences, and notes
  • Managed by the agent or manually edited

​
memory/YYYY-MM-DD.md (Daily Logs)

  • NOT auto-injected (retrieved on demand via memory_search)
  • Contains timestamped daily interaction logs
  • Searchable via vector memory search
Havoc builds a vector index over all memory files for semantic search. This allows agents to recall relevant information even from old daily logs.

​
Editing Workspace Files

You can edit workspace files in three ways:
  1. Havoc Dashboard — Visual editor with live preview
  2. API — PUT /api/agents/:agentId/workspace/:filename
  3. Agent Self-Edit — The agent can modify its own workspace files using the write tool
Start with a template — it pre-configures all workspace files for common use cases like customer support, sales, or research.

Guide: Create an Agent

Create an agent with a fully configured workspace.