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

​
System-Generated Documents

​
How Documents Affect Behavior

​
SOUL.md

The most important alignment document. It defines the agent’s core values and decision-making hierarchy:
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:

​
USER.md

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

​
Workspace Directory

Alignment documents live in the agent workspace directory:
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.