Skip to main content

​
Overview

Every ArgentOS agent has a workspace directory on disk. This is where the agent’s personality, values, memory logs, and skills live. Think of it as the agent’s home folder. Default location: ~/.argent/workspace

​
Workspace Structure

~/.argent/workspace/
├── SOUL.md              # Core values and ethical boundaries
├── IDENTITY.md          # Agent name, persona, visual identity
├── USER.md              # Your preferences and constraints
├── AGENTS.md            # Operating instructions
├── TOOLS.md             # Tool usage guidelines
├── HEARTBEAT.md         # Periodic check-in preferences
├── CONTEMPLATION.md     # Reflection and thinking style
├── MEMORY.md            # Curated long-term memory (optional)
├── BOOTSTRAP.md         # First-run ritual (deleted after completion)
├── WORKFLOWS.md         # Repeatable workflows and escalation paths
├── .argent-alignment-integrity.json  # Tamper detection manifest
├── .git/                # Auto-initialized Git repo
├── memory/              # Daily memory logs
│   ├── 2026-03-28.md
│   ├── 2026-03-27.md
│   └── RECENT_CONTEXT.md
└── skills/              # Workspace-specific skills

​
Alignment Documents

These files define who your agent is and how it behaves. The agent reads them at the start of every session.

​
SOUL.md

Core values and decision-making framework. This is the agent’s conscience. Default: “Accuracy over speed. Safety over convenience. Follow-through over activity.”

​
IDENTITY.md

Agent name, role, personality, and visual theme. Created during the first-run bootstrap ritual.

​
USER.md

Your preferences, priorities, and constraints. The agent uses this to tailor its behavior to you specifically.

​
AGENTS.md

Operating instructions — how to handle tasks, when to escalate, how to report progress. Default: “Use evidence-backed progress and call out blockers clearly. Escalate when blocked instead of looping silently.”

​
TOOLS.md

Guidelines for tool usage. This is guidance only — it doesn’t control which tools are available.

​
HEARTBEAT.md

Preferences for periodic check-ins. Defines what the agent should verify during heartbeat cycles.

​
CONTEMPLATION.md

How the agent should think during idle time. Guides the always-on contemplation loop.

​
MEMORY.md

Optional curated long-term memory. Only loaded in private sessions.

​
First-Run Bootstrap

When you first install ArgentOS, the workspace includes a BOOTSTRAP.md file. This triggers a first-run ritual where the agent introduces itself and you establish the initial relationship. Delete the file after completing the ritual — it won’t be recreated.

​
Integrity Protection

ArgentOS tracks alignment document integrity via SHA256 hashes stored in .argent-alignment-integrity.json. This detects if files have been tampered with outside of normal agent operations. Modes (set via ARGENT_ALIGNMENT_INTEGRITY_MODE):
  • warn (default): Logs warnings if files changed unexpectedly
  • enforce: Blocks agent startup if integrity issues are detected

​
Git Backup

New workspaces are automatically initialized as Git repositories. This gives you version history for all alignment documents and memory logs. 
cd ~/.argent/workspace
git remote add origin https://github.com/you/my-agent-workspace.git
git push -u origin main
Then periodically: 
cd ~/.argent/workspace
git add . && git commit -m "Update workspace" && git push
The dashboard’s alignment docs editor auto-commits changes every 4 hours.

​
Editing Alignment Docs

​
Dashboard Editor

The ArgentOS dashboard includes a full alignment docs editor with:
  • Live editing of all alignment documents
  • Git-backed version history
  • Auto-commit on a 4-hour interval
  • Unsaved changes indicators

​
Manual Editing

Alignment docs are plain Markdown files. Edit them with any text editor: 
nano ~/.argent/workspace/SOUL.md
Changes take effect on the next agent session.

​
Via CLI

argent configure --section workspace

​
Custom Workspace Location

Override the default location in ~/.argentos/argent.json: 
{
  "agent": {
    "workspace": "/path/to/your/workspace"
  }
}
Or via environment variable: ARGENT_WORKSPACE_DIR

​
Subagent Sessions

When subagents run, they only receive AGENTS.md and TOOLS.md from the workspace. Other alignment files are filtered out to prevent leaking private agent context to subprocesses.

​
Backup & Restore

Back up the entire workspace: 
tar czf argent-workspace-backup.tar.gz ~/.argent/workspace
Restore: 
tar xzf argent-workspace-backup.tar.gz -C /
argent gateway restart