> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argentos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Alignment Documents

> Per-agent personality and identity documents that shape agent behavior — SOUL.md, IDENTITY.md, USER.md, and more — with Git-backed versioning.

## 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

| Document          | Filename           | Purpose                                                       |
| ----------------- | ------------------ | ------------------------------------------------------------- |
| **Soul**          | `SOUL.md`          | Core values, decision-making framework, ethical boundaries    |
| **Identity**      | `IDENTITY.md`      | Agent name, persona, visual theme, communication style        |
| **User**          | `USER.md`          | User profile, preferences, constraints, priorities            |
| **Tools**         | `TOOLS.md`         | Available tools, usage guidelines, tool-specific instructions |
| **Heartbeat**     | `HEARTBEAT.md`     | Periodic check-in behavior, accountability prompts            |
| **Contemplation** | `CONTEMPLATION.md` | Thinking prompts, reflection style, curiosity directions      |
| **Bootstrap**     | `BOOTSTRAP.md`     | Startup checklist, initialization behavior                    |
| **Agents**        | `AGENTS.md`        | Operating notes for multi-agent coordination                  |
| **Workflows**     | `WORKFLOWS.md`     | Repeatable workflows and escalation paths                     |
| **Memory**        | `MEMORY.md`        | Durable facts, decisions, and outcomes to remember            |

### System-Generated Documents

| Document              | Filename                          | Purpose                                       |
| --------------------- | --------------------------------- | --------------------------------------------- |
| Recent Context        | `RECENT_CONTEXT.md`               | Compressed recent interaction summary         |
| Accountability Status | `ACCOUNTABILITY_STATUS.md`        | Current heartbeat scores and commitments      |
| Identity Context      | `IDENTITY_CONTEXT.md`             | Entity and relationship context from memory   |
| First Run             | `FIRST_RUN.md`                    | One-time initialization instructions          |
| Recent Channels       | `RECENT_CHANNEL_CONVERSATIONS.md` | Summary of recent channel activity            |
| Recent Contemplation  | `RECENT_CONTEMPLATION.md`         | Latest contemplation episodes                 |
| SIS Context           | `SIS_CONTEXT.md`                  | Active lessons from the Self-Improving System |
| Session Snapshot      | `SESSION_SNAPSHOT.md`             | Amnesia prevention -- compaction summary      |
| Live Inbox Ledger     | `LIVE_INBOX_LEDGER.md`            | High-salience conversation moments            |
| TTS Policy            | `TTS_POLICY.md`                   | Text-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:

```markdown theme={null}
# 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)
```

<Tip>
  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.
</Tip>

### IDENTITY.md

Defines the agent's persona and communication style:

```markdown theme={null}
# 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:

```markdown theme={null}
# 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

<Info>
  On first workspace creation, `git init` is run automatically. This provides full version history for all alignment document changes.
</Info>

## Bootstrap Process

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

<Steps>
  <Step title="AGENTS.md">Operating notes (loaded first for coordination context)</Step>
  <Step title="SOUL.md">Core values</Step>
  <Step title="TOOLS.md">Tool instructions</Step>
  <Step title="IDENTITY.md">Persona</Step>
  <Step title="USER.md">User profile</Step>
  <Step title="HEARTBEAT.md">Accountability settings</Step>
  <Step title="CONTEMPLATION.md">Thinking prompts</Step>
  <Step title="BOOTSTRAP.md">Startup checklist (only on new workspaces)</Step>
  <Step title="WORKFLOWS.md">Workflow definitions</Step>
  <Step title="MEMORY.md">Durable memory notes</Step>
</Steps>

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

<Note>
  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.
</Note>

## 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.