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

# Agent Workspace

> The workspace is your agent's home directory — alignment docs, memory logs, and skills all live here.

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

### Recommended: Push to a private repo

```bash theme={null}
cd ~/.argent/workspace
git remote add origin https://github.com/you/my-agent-workspace.git
git push -u origin main
```

Then periodically:

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

```bash theme={null}
nano ~/.argent/workspace/SOUL.md
```

Changes take effect on the next agent session.

### Via CLI

```bash theme={null}
argent configure --section workspace
```

## Custom Workspace Location

Override the default location in `~/.argentos/argent.json`:

```json theme={null}
{
  "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:

```bash theme={null}
tar czf argent-workspace-backup.tar.gz ~/.argent/workspace
```

Restore:

```bash theme={null}
tar xzf argent-workspace-backup.tar.gz -C /
argent gateway restart
```