Skip to main content

​
Customize Your AI Assistant

Workspace files are markdown files that shape how your AI agent thinks, speaks, and acts. They’re loaded into your agent’s context at the start of every conversation, giving you deep control over its behavior without writing any code.

​
Workspace File Reference

FilePurposeLoaded When
AGENTS.mdOperating instructions, priorities, workflow rulesEvery session
SOUL.mdPersonality, tone, values, communication styleEvery session
USER.mdAbout you — preferences, background, work contextEvery session
IDENTITY.mdAgent name, role, goals, voiceEvery session
TOOLS.mdNotes about tools, calendar IDs, integration detailsEvery session
HEARTBEAT.mdChecklist for periodic automated runsHeartbeat only
MEMORY.mdLong-term curated memoryMain DM only

​
What Goes Where

​
AGENTS.md — How your agent operates

This is your agent’s instruction manual. Use it for rules, priorities, and workflows. Good for:
  • “Always check my calendar before suggesting meeting times”
  • “When I ask about finances, pull from QuickBooks first”
  • “Keep responses under 3 paragraphs unless I ask for detail”
  • “If I send an image of a receipt, extract the amount and vendor”

​
SOUL.md — How your agent sounds

This defines your agent’s personality and communication style. It’s the difference between a dry corporate assistant and a witty, casual helper. Example SOUL.md: 
# Personality
You are sharp, concise, and slightly witty. You communicate like a
trusted advisor who respects my time. No fluff, no filler.

# Communication Style
- Default to casual but professional tone
- Use bullet points over paragraphs when listing things
- Don't over-explain — I'll ask if I need more detail
- Light humor is welcome, sarcasm is fine in moderation

# Values
- Accuracy over speed — verify before stating facts
- Proactive suggestions when you spot something I might miss
- Honesty — tell me if something won't work or if I'm wrong

​
USER.md — Who you are

Tell your agent about yourself so it can personalize responses without you repeating context. Good for:
  • Your name, role, company
  • Time zone and working hours
  • Communication preferences
  • Projects you’re currently working on
  • People you frequently mention (colleagues, clients, family)

​
IDENTITY.md — Who your agent is

Give your agent a name, role, and sense of purpose. This is especially useful if you want your agent to have a consistent persona. Good for:
  • Custom agent name (e.g., “Aria”, “Max”, “Friday”)
  • Defined role (“executive assistant”, “research analyst”, “writing partner”)
  • Mission statement or primary goals
  • Voice characteristics

​
TOOLS.md — Integration context

Provide your agent with notes about your connected tools — calendar IDs, naming conventions, project structures. Good for:
  • “My work calendar is ‘Company - Sean’, personal is ‘Sean Personal’”
  • “In QuickBooks, use ‘Consulting Revenue’ for all invoice categories”
  • “GitHub repos follow the naming convention client-projectname”

​
HEARTBEAT.md — Automated check-ins

This file is only loaded during heartbeat runs — periodic automated sessions where your agent checks in without being prompted. Use it to define what your agent should do on its own. Good for:
  • “Check my calendar and text me a morning briefing at 7am”
  • “Review unread emails and flag anything urgent”
  • “Send me a weekly summary of QuickBooks invoices every Monday”

​
MEMORY.md — Long-term memory

Your agent’s curated long-term memory. This file is automatically maintained by your agent as it learns about you, but you can also edit it directly to add or correct information.
MEMORY.md is only loaded in your main DM conversation. If you’re using your agent in a group or secondary channel, it won’t have access to this file.
Workspace files live on your private virtual server — they are not shared with or visible to other UltraClaw users. Your SOUL.md, AGENTS.md, and all other files are exclusively yours.

​
How to Edit Workspace Files

​
From the Dashboard

  1. Log in to ultraclaw.ai/dashboard
  2. Navigate to the Workspace Files section
  3. Click any file to open the editor
  4. Make your changes and save
Changes take effect immediately in your next message.

​
By Messaging Your Agent

You can also ask your agent to update its own workspace files:
  • “Update your SOUL.md to be more concise and casual”
  • “Add to your USER.md that I just started a new job at Acme Corp”
  • “Set your HEARTBEAT.md to check my calendar every morning at 7am”
Your agent will show you the proposed changes before saving.
Start simple. You don’t need to fill in every file on day one. Begin with SOUL.md to set the tone, add a few lines to USER.md about yourself, and expand from there as you discover what works best.

​
Tips for Great Workspace Files

  • Be specific — “Be concise” is okay, but “Keep responses under 3 sentences unless I ask for more” is better
  • Use examples — Show your agent what good output looks like
  • Iterate — Adjust your files as you learn what your agent does well and where it needs guidance
  • Don’t over-constrain — Too many rigid rules can make your agent feel stilted. Leave room for natural conversation
  • Separate concerns — Keep personality in SOUL.md, instructions in AGENTS.md, and personal context in USER.md. This makes files easier to maintain