---
id: "framework-markdown-agent-os-architecture"
type: "framework"
source_timestamps: ["00:06:37", "00:07:18"]
tags: ["architecture", "configuration"]
related: ["concept-markdown-as-agent-os"]
sources: ["s08-real-problem-agents"]
sourceVaultSlug: "s08-real-problem-agents"
originDay: 8
---
# Markdown Agent OS Architecture

## Summary

The standard directory structure and file architecture found in successful, sticky [[entity-openclaw-d8]] agent deployments. Plain-text Markdown files act as the agent's operating system. See [[concept-markdown-as-agent-os]] for the conceptual frame.

## The components

### 1. `soul.md`
Defines the agent's role, job description, tone, and operational boundaries. *What is this agent for? What is it NOT for?*

### 2. `identity.md`
Defines the agent's name and specific personality constraints. *How does it speak? What's its character?*

### 3. `user.md`
Contains a detailed profile of the human user, including preferences, schedule patterns, and communication style. *Who is the agent serving, and how do they like things done?*

### 4. `heartbeat.md`
A checklist the agent reviews periodically to decide if there is actionable work to do. *What should the agent check on a schedule?*

### 5. Cron Job
A simple scheduling mechanism that maps the agent's activity to the human's actual operating rhythm. The agent doesn't run continuously — it wakes up on a heartbeat and consults [[concept-markdown-as-agent-os|its OS files]].

### Optional: Memory layer
Advanced deployments augment static files with [[entity-openbrain-d8]] or a similar database, allowing the agent to learn over time. See [[action-implement-agent-memory]].

## Why this works

This architecture enforces [[concept-agentic-separation-of-concerns]] by giving every agent its own self-contained context, while remaining human-readable and version-controllable.

## Related
- [[action-create-markdown-os]]
- [[claim-markdown-quality-determines-agent-quality]]