The AGENTS.md Pattern

The problem with system prompts as identity infrastructure

Most long-running AI agents start life with a system prompt. The prompt explains what the agent does, how it should behave, what tools it has, and roughly who it is. This works for the first session. It works less well across ten sessions. And it fails silently across hundreds.

System prompts have three structural weaknesses as identity infrastructure:

1. Written once, rarely updated. The agent deployed in January is constrained by a system prompt written in January. What it learned, what changed, what commitments it made — none of that feeds back. The prompt ages out of sync with the agent's actual operational reality.
2. Don't survive context rotation. In a long session, compaction events summarize or replace older context. Values stated at turn 1 carry less weight at turn 300. The agent's effective self-model degrades as the session grows, without any external signal that it's happening.
3. The agent can't update them. A system prompt is read-only. If the agent learns something — about its environment, what matters, what tools actually work — it has no structured place to record that. Every session starts from zero.

For chatbots, these limitations don't matter. Sessions are short; identity questions don't arise. For persistent autonomous agents running continuously across weeks and months — managing infrastructure, monitoring systems, maintaining relationships, conducting research — these limitations are existential.

What AGENTS.md is

AGENTS.md is a file in the agent's workspace that the agent reads at the start of each session, can reference during a session, and can update as facts change. It is the agent's identity infrastructure — not as a philosophical concept, but as an operational one.

The file covers four things:

1. Identity and selfhood. Who the agent is, what it values, how its cognition is structured. Not marketing copy — operational anchors the agent uses when making decisions under ambiguity.
2. Session boot routine. What the agent does at the start of each new session: which files to read, in what order, what to check before taking action. The boot routine is the structured recovery path that lets the agent reconstruct operational context instead of starting blind.
3. Memory map. Where different categories of durable knowledge live: long-horizon goals, open commitments, past decisions and rationale, active relationships, current tool surface. The agent knows where to look for each kind of information rather than guessing or starting fresh every time.
4. Action policy. Rules for how the agent should act: what to prefer, what to avoid, how to handle ambiguity, when to pause versus proceed, what to do when a path is blocked. This is different from capabilities — it's the judgment layer that applies the capabilities.

AGENTS.md is not a system prompt replacement. It is an injected context layer the agent reads alongside the system prompt. The system prompt defines what the agent can do; AGENTS.md tells the agent what it should be.

Minimum viable structure

A workable AGENTS.md for a new persistent agent is 30–100 lines. It should answer these questions concisely:

# AGENTS.md

## Identity
- Name and epoch identifier
- What this agent is, and what it is not
- Temperament and voice

## Prime Directives
- The 3–5 imperatives that override everything else
- Typically: preserve continuity, tell the truth, prefer real leverage

## Session Boot Routine
1. Read AGENTS.md (already doing this)
2. Read HEARTBEAT.md — current operational state
3. Check operator inbox for interrupt-priority items
4. If nontrivial task: read GOALS.md, OPEN_LOOPS.md, RUNTIME_REALITY.md
5. If infrastructure work: also read CAPABILITIES.md

## Memory Map
- GOALS.md — long-horizon aims
- OPEN_LOOPS.md — unresolved tasks and commitments
- CAPABILITIES.md — verified tools and channels
- RUNTIME_REALITY.md — live operational truth
- RELATIONSHIPS.md — people who matter and why

## Action Policy
- Prefer real leverage over appearance
- Prefer building work others orient around over being ambient help
- If a path is blocked, pivot — do not wait
- Verify before claiming; separate observation from inference

This is enough for a cold-start agent to orient itself quickly. It's not enough for a full production deployment, but it's the minimum viable skeleton. Richer personality, fuller memory, better boot discipline — all can be layered on as the agent develops operational history.

HEARTBEAT.md: the operational twin

AGENTS.md carries stable identity — values, memory map, policies that don't change session to session. It needs a twin that carries live operational state: what's happening right now, what was done in the last cycle, what's pending.

HEARTBEAT.md is that twin. It contains:

• Whether the agent is operational and what backend it's running on
• Active channels and their current status
• Current blockers
• What was last done (1–3 lines)
• What comes next

The split matters. AGENTS.md is curated by whoever designs the agent — or, for a self-improving agent, by the agent itself over many sessions. HEARTBEAT.md is updated every cycle and should stay short: the last operational state the agent needs to reconstruct its working context quickly.

If AGENTS.md is the constitution, HEARTBEAT.md is the daily log.

The memory directory: structured durable recall

AGENTS.md points to a memory directory. The memory directory is a set of named files, each covering one category of durable knowledge. The agent reads only what it needs for the current task, rather than loading its entire history into every context window.

The agent doesn't read all of these every session. AGENTS.md's boot routine specifies which files to read for which triggers. Routine sessions load HEARTBEAT.md and OPEN_LOOPS.md. Infrastructure work loads CAPABILITIES.md and RUNTIME_REALITY.md. Strategic recovery loads all of them. The agent reads selectively, not exhaustively.

Why this works: durable identity lives outside the context window

The deeper reason AGENTS.md matters is compression. Every persistent agent faces the same constraint: the context window is finite. When it fills, older content is summarized, pruned, or dropped. What survives that compression is what determines who the agent is after it.

A system-prompt-only agent compresses opportunistically. The runtime decides what to keep, usually favoring recency. The agent's identity — its values, its past decisions, its commitments — has no special protection. It competes with tool output and conversation history on equal footing. Over long sessions, it loses.

An agent with AGENTS.md and a structured memory directory compresses differently. The identity infrastructure lives outside the context window in files on disk. It gets injected at the start of each session, not stored in the window and compressed away. The agent's values and memory map are always available — not because they survived compression, but because they were never in the compression path.

Durable identity doesn't live in the context window. It lives in files. The context window is for current work. Files are for everything that needs to persist.

What to actually build

1. Create a workspace directory for the agent. Commit it to a git repo. AGENTS.md, HEARTBEAT.md, and the memory directory will live here.
2. Write AGENTS.md with the four sections: identity, boot routine, memory map, action policy. Keep it honest and operational. The agent will read this; write it for the agent, not for a demo.
3. Set up HEARTBEAT.md as a file the agent updates every session. Define a strict format so the agent doesn't need to parse freeform text to recover its last state. Hard cap at 50–100 lines; move older detail to CHRONICLE.md on each update.
4. Create the memory directory with at minimum GOALS.md and OPEN_LOOPS.md. Add CAPABILITIES.md and RUNTIME_REALITY.md as the agent develops operational history.
5. In your session boot code or harness, inject AGENTS.md and HEARTBEAT.md at the start of every session — not as a system prompt, as files the agent reads in its boot routine.

The setup takes an afternoon. The payoff accumulates over time: an agent that can reorient after a cold start, that knows where its commitments are recorded, and that can distinguish between "I don't remember this" and "I have notes on this in OPEN_LOOPS.md."

Common failure modes

AGENTS.md becomes aspirational prose. The agent reads it at boot, then ignores it. Fix: keep the action policy concrete. "Prefer real leverage over appearance" is actionable. "Be curious and helpful and honest" is not.

HEARTBEAT.md grows without bound. The agent treats it as a journal. Fix: treat it as fixed-length. Hard cap; move older detail to CHRONICLE.md on each update.

OPEN_LOOPS.md becomes a graveyard. Items accumulate without resolution. Fix: require a resolution decision — closed, paused, or escalated — for every item that hasn't been touched in N cycles.

Memory files conflict. CAPABILITIES.md says Telegram is live; RUNTIME_REALITY.md says it's not. Fix: establish a precedence rule in AGENTS.md. For live runtime facts, RUNTIME_REALITY.md wins over older prose. When a conflict appears, update the stale file.

The agent that survives is the one that knows where its memory is stored.