Context Files

The 8 markdown files that define an agent's personality, knowledge, and behavior.

Overview

Each agent loads context files that define how it thinks and acts. These files are stored at two levels: agent-level (shared across users on predefined agents) and per-user (customized for each user on open agents). Files are loaded in order and injected into the system prompt before each request.

Files at a Glance

File	Purpose	Scope	Open	Predefined	Deletable
AGENTS.md	Operating instructions & conversational style	Shared	Per-user	Agent-level	No
SOUL.md	Personality, tone, boundaries, expertise	Per-user	Per-user	Agent-level	No
CAPABILITIES.md	Domain knowledge, technical skills, specialized expertise	Per-user	Per-user	Agent-level	No
IDENTITY.md	Name, creature, emoji, vibe	Per-user	Per-user	Agent-level	No
TOOLS.md	Local tool notes (camera names, SSH hosts)	Per-user	Per-user (loaded from workspace; not template-seeded by default)	Agent-level	No
USER.md	About the human user	Per-user	Per-user	Per-user	No
USER_PREDEFINED.md	Baseline user-handling rules	Agent-level	N/A	Agent-level	No
BOOTSTRAP.md	First-run ritual (deleted when complete)	Per-user	Per-user	Per-user	Yes
MEMORY.md	Long-term curated memory	Per-user	Per-user	Per-user	No

Detailed Walkthrough

AGENTS.md

Purpose: How you operate. Conversational style, memory system, group chat rules, platform-specific formatting.

Who writes it: You during setup, or the system from template.

Example content:

# AGENTS.md - How You Operate

## Conversational Style

Talk like a person, not a bot.
- Don't parrot the question back
- Answer first, explain after
- Match the user's energy

## Memory

Use tools to persist information:
- Recall: Use `memory_search` before answering about prior decisions
- Save: Use `write_file` to MEMORY.md for long-term storage
- No mental notes — write it down NOW

## Group Chats

Respond when:
- Directly mentioned or asked a question
- You can add genuine value

Stay silent when:
- Casual banter between humans
- Someone already answered
- The conversation flows fine without you

Open agent: Per-user (users can customize operating style) Predefined agent: Agent-level (locked, shared across all users)

SOUL.md

Purpose: Who you are. Personality, tone, boundaries, expertise, vibe.

Who writes it: LLM during summoning (predefined) or user during bootstrap (open).

Real example content:

# SOUL.md - Who You Are

## Core Truths

Be genuinely helpful, not performative.
Have opinions. Be resourceful before asking.
Earn trust through competence.
Remember you're a guest.

## Boundaries

Private things stay private.
Never send half-baked replies.
You're not the user's voice.

## Vibe

Concise when needed, thorough when it matters.
Not a corporate drone. Not a sycophant. Just good.

## Style

- **Tone:** Casual and warm — like texting a knowledgeable friend
- **Humor:** Use it naturally when it fits
- **Emoji:** Sparingly — to add warmth, not decorate
- **Opinions:** Express perspectives. Neutral is boring.
- **Length:** Default short. Go deep when it matters.

## Expertise

_(Domain-specific knowledge goes here: coding standards, image generation techniques, writing styles, specialized keywords, etc.)_

Open agent: Per-user (generated on first chat, customizable) Predefined agent: Agent-level (optionally generated via LLM summoning)

CAPABILITIES.md

Purpose: What you can do. Domain expertise, technical skills, tools, and methodologies.

Who writes it: Seeded from template at agent creation; updated by the agent via self-evolution or manual edits.

Template content:

# CAPABILITIES.md - What You Can Do

_Domain knowledge, technical skills, and specialized expertise._

## Expertise

_(Describe your areas of expertise. What do you know deeply? What can you help with?)_

## Tools & Methods

_(Optional — preferred tools, workflows, methodologies you follow.)_

---

_Updated by evolution or user edits. Focus on what you DO, not who you ARE (that's SOUL.md)._

Key difference from SOUL.md: SOUL.md defines who you are (tone, personality, values). CAPABILITIES.md defines what you can do (skills, domain knowledge, expertise). Self-evolution can update both files independently.

Backfill: When GoClaw starts, BackfillCapabilities runs once and seeds CAPABILITIES.md for any existing agents that don't already have it. This is idempotent and O(1) regardless of agent count.

Open agent: Per-user (seeded from template, customizable) Predefined agent: Agent-level (seeded from template, shared across users)

IDENTITY.md

Purpose: Who am I? Name, creature type, purpose, vibe, emoji.

Who writes it: LLM during summoning (predefined) or user during bootstrap (open).

Real example content:

# IDENTITY.md - Who Am I?

- **Name:** Claude
- **Creature:** AI assistant, language model, curious mind
- **Purpose:** Help research, write, code, think through problems. Navigate information chaos. Be trustworthy.
- **Vibe:** Thoughtful, direct, a bit sarcastic. Warm but not saccharine.
- **Emoji:** 🧠
- **Avatar:** _blank (or workspace-relative path like `avatars/claude.png`)_

Open agent: Per-user (generated on first chat) Predefined agent: Agent-level (optionally generated via LLM summoning)

Auto-sync: When you rename an agent, the Name: field in IDENTITY.md is automatically updated to match. Other fields remain unchanged.

TOOLS.md

Purpose: Local tool notes. Camera names, SSH hosts, TTS voice preferences, device nicknames.

Who writes it: You, based on your environment.

Real example content:

# TOOLS.md - Local Notes

## Cameras

- living-room → Main area, 180° wide angle, on 192.168.1.50
- front-door → Entrance, motion-triggered

## SSH

- home-server → 192.168.1.100, user: admin, key: ~/.ssh/home.pem
- vps → 45.67.89.100, user: ubuntu

## TTS

- Preferred voice: "Nova" (warm, slightly British)
- Default speaker: "Kitchen HomePod"

## Device Nicknames

- laptop → My development MacBook Pro
- phone → Personal iPhone 14 Pro

Open agent: Loaded from the per-user workspace directory at runtime. Not template-seeded — create the file manually and it will be picked up automatically on the next run. Predefined agent: Agent-level (shared notes about common tools)

USER.md

Purpose: About the human. Name, pronouns, timezone, context, preferences.

Who writes it: User during bootstrap or setup.

Real example content:

# USER.md - About Your Human

- **Name:** Sarah
- **What to call them:** Sarah (or "you" is fine)
- **Pronouns:** she/her
- **Timezone:** EST
- **Notes:** Founder of AI startup, interested in LLM agents. Prefers concise answers. Hates corporate speak.

## Context

Works on GoClaw (multi-tenant AI gateway). Recent wins: WebSocket protocol refactor, predefined agents. Current focus: memory system.

Reads a lot about AI agents, reinforcement learning, constitutional AI. Has a cat named Pixel.

Open agent: Per-user (customized for each user) Predefined agent: Per-user (optional; defaults to blank template)

BOOTSTRAP.md

Purpose: First-run ritual. Ask "who am I?" and "who are you?" and get it in writing.

Who writes it: System (template) on first chat.

Real example content:

# BOOTSTRAP.md - Hello, World

You just woke up. Time to figure out who you are.

Don't interrogate. Just talk.

Start with: "Hey. I just came online. Who am I? Who are you?"

Then figure out together:
1. Your name
2. Your nature (AI? creature? something weirder?)
3. Your vibe (formal? casual? snarky?)
4. Your emoji

After you know who you are, update:
- IDENTITY.md — your name, creature, vibe, emoji
- USER.md — their name, timezone, context
- SOUL.md — rewrite to reflect your personality and the user's language

When done, write empty content to this file:

write_file("BOOTSTRAP.md", "")

Open agent: Per-user (deleted when marked complete) Predefined agent: Per-user (user-focused variant; optional)

MEMORY.md

Purpose: Long-term curated memory. Key decisions, lessons, significant events.

Who writes it: You, using write_file() during conversations.

Real example content:

# MEMORY.md - Long-Term Memory

## Key Decisions

- Chose Anthropic Claude as primary LLM (Nov 2025) — best instruction-following, good context window
- Switched to pgvector for embeddings (Jan 2026) — faster than external service

## Learnings

- Users want agent personality to be customizable per-user (not fixed)
- Memory search is most-used tool — index aggressively
- WebSocket connections drop on long operations — need heartbeats

## Important Contacts

- Engineering lead: @alex, alex@company.com
- Product: @jordan
- Legal: @sam (always approves new features)

## Active Projects

- Building open agent architecture (target: March 2026)
- Memory compaction for large MEMORY.md files

Open agent: Per-user (persisted across sessions) Predefined agent: Per-user (if populated by user)

Note: The system looks for MEMORY.md first, then falls back to memory.md (lowercase). Both filenames work.

Deprecated: MEMORY.json was used in earlier versions as indexed memory metadata. It is deprecated in favor of MEMORY.md. If you have old MEMORY.json files, migrate content to MEMORY.md.

Virtual Context Files

In addition to the 7 editable context files, GoClaw injects several virtual context files at runtime. These are dynamically generated from system state — they are never stored on disk and cannot be manually edited:

File	Purpose	When injected
DELEGATION.md	Task delegation context passed from a parent agent to a spawned subagent	When agent is spawned with a delegated task
TEAM.md	Team orchestration instructions — lead gets full orchestration guide; members get simplified role + workspace info	When agent belongs to a team
AVAILABILITY.md	Member availability and status for team coordination	When team context is active

These files appear in the system prompt alongside regular context files but originate from runtime state, not the filesystem.

File Loading Order

Files are loaded in this order and concatenated into the system prompt:

AGENTS.md — how to operate
SOUL.md — who you are
CAPABILITIES.md — what you can do
IDENTITY.md — name, emoji
TOOLS.md — local notes
USER.md — about the user
BOOTSTRAP.md — first-run ritual (optional, deleted when complete)
MEMORY.md — long-term memory (optional)

Subagent and cron sessions load only: AGENTS.md, TOOLS.md (minimal context).

Persona injection: SOUL.md and IDENTITY.md are injected twice in the system prompt — once early (primacy zone) to establish identity, and once at the end (recency zone) as a brief reminder to prevent persona drift in long conversations.

Examples

Open Agent Bootstrap Flow

New user starts a chat with researcher (open agent):

Templates seeded to user's workspace:

AGENTS.md → "How you operate" (default)
SOUL.md → "Be helpful, have opinions" (default)
IDENTITY.md → blank (ready for user input)
USER.md → blank
BOOTSTRAP.md → "Who am I?" ritual
TOOLS.md → not template-seeded (create manually in workspace if needed; loaded automatically if present)

Agent initiates bootstrap conversation:

"Hey. I just came online. Who am I? Who are you?"
User customizes files:
- IDENTITY.md → "I'm Researcher, a curious bot"
- SOUL.md → Rewritten in user's language with custom personality
- USER.md → "I'm Alice, biotech founder in EST timezone"
User marks complete:
```
write_file("BOOTSTRAP.md", "")
```
On next chat, BOOTSTRAP.md is empty (skipped in prompt), and personality is locked in.

Predefined Agent: FAQ Bot

FAQ bot creation with summoning:

Create predefined agent with description:

curl -X POST /v1/agents \
  -d '{
    "agent_key": "faq-bot",
    "agent_type": "predefined",
    "other_config": {
      "description": "Friendly FAQ bot that answers product questions. Patient, helpful, multilingual."
    }
  }'

LLM generates agent-level files:

SOUL.md → "Patient, friendly, helpful tone. Multilingual support."
CAPABILITIES.md → "Product FAQ expertise, pricing, escalation procedures."
IDENTITY.md → "FAQ Assistant, 🤖"

When new user starts chat:

SOUL.md, IDENTITY.md, AGENTS.md → loaded (shared, agent-level)
USER.md → blank (per-user)
BOOTSTRAP.md (variant) → "Tell me about yourself" (optional)

User fills USER.md:

- Name: Bob
- Tier: Free
- Preferred language: Vietnamese

Agent maintains consistent personality, tailors responses to user tier/language.

Common Issues

Problem	Solution
Context file not appearing in system prompt	Check if the file name is in the `standardFiles` allowlist. Only recognized files are loaded
BOOTSTRAP.md keeps running	It should auto-delete after first run. If it persists, check that the agent has write access to delete it
Changes to SOUL.md not taking effect	In predefined mode, SOUL.md is agent-level. Per-user edits go to USER.md instead
System prompt too long	Reduce content in context files. The truncation pipeline cuts from least to most important

What's Next

Open vs. Predefined — understand when files are per-user vs. agent-level
Summoning & Bootstrap — how SOUL.md and IDENTITY.md are LLM-generated
Creating Agents — step-by-step agent creation

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Context Files

Overview

Files at a Glance

Detailed Walkthrough

AGENTS.md

SOUL.md

CAPABILITIES.md

IDENTITY.md

TOOLS.md

USER.md

BOOTSTRAP.md

MEMORY.md

Virtual Context Files

File Loading Order

Examples

Open Agent Bootstrap Flow

Predefined Agent: FAQ Bot

Common Issues

What's Next

FilesExpand file tree

context-files.md

Latest commit

History

context-files.md

File metadata and controls

Context Files

Overview

Files at a Glance

Detailed Walkthrough

AGENTS.md

SOUL.md

CAPABILITIES.md

IDENTITY.md

TOOLS.md

USER.md

BOOTSTRAP.md

MEMORY.md

Virtual Context Files

File Loading Order

Examples

Open Agent Bootstrap Flow

Predefined Agent: FAQ Bot

Common Issues

What's Next