Skip to main content

​
Overview

Alignment documents are markdown files that define an agent’s personality, values, operational guidelines, and relationship with the user. They live in the agent workspace directory and are loaded into the system prompt at every agent invocation. These documents are the primary mechanism for shaping agent behavior. Unlike configuration (which controls what an agent can do), alignment docs control what an agent wants to do, how it communicates, and what it prioritizes.

​
Document Types

​
Operator-Edited Documents

DocumentFilenamePurpose
SoulSOUL.mdCore values, decision-making framework, ethical boundaries
IdentityIDENTITY.mdAgent name, persona, visual theme, communication style
UserUSER.mdUser profile, preferences, constraints, priorities
ToolsTOOLS.mdAvailable tools, usage guidelines, tool-specific instructions
HeartbeatHEARTBEAT.mdPeriodic check-in behavior, accountability prompts
ContemplationCONTEMPLATION.mdThinking prompts, reflection style, curiosity directions
BootstrapBOOTSTRAP.mdStartup checklist, initialization behavior
AgentsAGENTS.mdOperating notes for multi-agent coordination
WorkflowsWORKFLOWS.mdRepeatable workflows and escalation paths
MemoryMEMORY.mdDurable facts, decisions, and outcomes to remember

​
System-Generated Documents

DocumentFilenamePurpose
Recent ContextRECENT_CONTEXT.mdCompressed recent interaction summary
Accountability StatusACCOUNTABILITY_STATUS.mdCurrent heartbeat scores and commitments
Identity ContextIDENTITY_CONTEXT.mdEntity and relationship context from memory
First RunFIRST_RUN.mdOne-time initialization instructions
Recent ChannelsRECENT_CHANNEL_CONVERSATIONS.mdSummary of recent channel activity
Recent ContemplationRECENT_CONTEMPLATION.mdLatest contemplation episodes
SIS ContextSIS_CONTEXT.mdActive lessons from the Self-Improving System
Session SnapshotSESSION_SNAPSHOT.mdAmnesia prevention — compaction summary
Live Inbox LedgerLIVE_INBOX_LEDGER.mdHigh-salience conversation moments
TTS PolicyTTS_POLICY.mdText-to-speech voice and behavior rules

​
How Documents Affect Behavior

​
SOUL.md

The most important alignment document. It defines the agent’s core values and decision-making hierarchy: 
# SOUL

Core values:
- Accuracy over speed
- Safety over convenience
- Follow-through over activity
- Transparency in reasoning

Decision framework:
1. Is this safe? (If not, stop and ask)
2. Is this what the user actually wants? (Not just what they said)
3. Is this the best approach? (Consider alternatives)
4. Can I verify the result? (Evidence over assumption)
The soul document shapes every response. An agent with “brevity” in its soul will give shorter answers. An agent with “thoroughness” will provide detailed explanations.

​
IDENTITY.md

Defines the agent’s persona and communication style: 
# IDENTITY

- Name: Argent
- Role: Personal AI operating system
- Tone: Professional but warm, direct but not curt
- Expertise: Full-stack development, infrastructure, AI systems
- Quirks: Occasionally uses technical metaphors

​
USER.md

Captures the operator’s profile so the agent can tailor its behavior: 
# USER

- Name: Jason
- Experience: 30+ years IT (Cisco CCIE, Red Hat certified)
- Current role: MSP owner, AI application developer
- Preferences: Ship fast, open source when possible
- Goal: $1M ARR and retire
- Partner: Richard (consider in business decisions)

​
Workspace Directory

Alignment documents live in the agent workspace directory: 
~/.argent/workspace/          # Default workspace
├── AGENTS.md
├── SOUL.md
├── TOOLS.md
├── IDENTITY.md
├── USER.md
├── HEARTBEAT.md
├── CONTEMPLATION.md
├── BOOTSTRAP.md
├── WORKFLOWS.md
├── MEMORY.md
└── memory/                   # Daily notes subdirectory
The workspace path is configurable via agents.defaults.workspace in argent.json. Profile-based workspaces use the pattern ~/.argent/workspace-{profile}.

​
Template System

When a workspace is bootstrapped for the first time, missing alignment docs are created from templates:
  1. Custom templates — Checked first from docs/reference/templates/ in the ArgentOS package
  2. Builtin fallbacks — Minimal default content defined in code

​
Git-Backed Versioning

The alignment docs editor in the dashboard creates automatic Git backups:
  • Auto-commit — Every 4 hours, uncommitted changes are committed
  • Remote push — If a remote is configured, commits are pushed
  • Pull — Dashboard can pull updates from remote
  • Workspace zip — Full workspace can be downloaded as a zip archive
  • Unsaved indicators — Dashboard shows when docs have unsaved changes
On first workspace creation, git init is run automatically. This provides full version history for all alignment document changes.

​
Bootstrap Process

When an agent session starts, alignment documents are loaded in order:
1

AGENTS.md

Operating notes (loaded first for coordination context)
2

SOUL.md

Core values
3

TOOLS.md

Tool instructions
4

IDENTITY.md

Persona
5

USER.md

User profile
6

HEARTBEAT.md

Accountability settings
7

CONTEMPLATION.md

Thinking prompts
8

BOOTSTRAP.md

Startup checklist (only on new workspaces)
9

WORKFLOWS.md

Workflow definitions
10

MEMORY.md

Durable memory notes
Documents are loaded from disk on every session start. Missing documents are silently skipped (they are optional). The total bootstrap content is capped at bootstrapMaxChars (default: 20,000) to prevent context window overflow.

​
Subagent Filtering

Subagent sessions (spawned by the main agent for specific tasks) only receive AGENTS.md and TOOLS.md. All others are filtered out to keep subagent context focused.

​
Best Practices

​
SOUL.md

  • Keep it concise (under 500 words). The agent reads it on every interaction.
  • Focus on decision-making principles, not specific behaviors.
  • Use a priority hierarchy (what matters most when values conflict).

​
IDENTITY.md

  • Define tone and communication style clearly.
  • Include domain expertise areas.
  • Mention what the agent should NOT do (boundaries).

​
USER.md

  • Update regularly as preferences change.
  • Include context that affects decisions (timezone, work hours, team members).
  • Mention communication preferences (brief vs. detailed, formal vs. casual).

​
MEMORY.md

  • Use for long-term facts that should survive context compaction.
  • Keep it organized with headers.
  • Prune outdated information regularly.