Understanding Atomic Agents

The persona splits across three files because they answer different questions and evolve at different cadences:

IDENTITY.md

Stable. The mission, the scope, the non-goals. What this agent does and refuses to do. Rarely edited.

SOUL.md

Slow-moving. Personality, voice, ethical posture, how the agent learns from its journal. Edited when the agent's character itself needs to shift.

USER.md

Living. Who the operator is, what they care about right now, what context the agent should always carry. Edited when life changes.

The three together become the system prompt's stable preamble. Every agent call assembles them in canonical order.

Memory is structured into atomic notes (typed, one file each — feedback / decision / project / reference / user) and an INDEX.md that routes the agent to relevant notes without loading everything.

If the agent has 200 notes, loading them all into the prompt would be expensive and noisy. Instead, memory/INDEX.md contains a compressed map: short titles, types, and one-line summaries of every note. The model reads the INDEX (cheap), decides which 1–3 notes it actually needs, then loads those specific files. This is INDEX-driven recall — the pattern that lets memory scale to thousands of entries without scaling prompt cost.

An optional wiki/ directory holds the distilled corpus — articles, references, long-form material — that the agent can search but doesn't auto-load.

Two parallel records, different audiences:

• Journal — narrative, written by the agent in its own voice. "Today I helped Dan triage three issues; the second one surfaced a deeper pattern about…" Daily entries in markdown, organized by month. You read these like a diary.
• Log — structured, machine-readable. One JSONL line per run with run_id, model called, tokens used, cost, tools invoked, captures written. You query these for dashboards, cost analysis, and debugging.

Same events, two formats. Humans get the prose; machines get the structured trail.

If Scout has 200 atomic notes, loading them all into the prompt would be expensive and noisy. Instead, memory/INDEX.md contains a compressed map: short titles, types, and one-line summaries of every note. The language model reads the INDEX (cheap), decides which 1–3 notes it actually needs for the current task, then asks the runtime to load those specific files (also cheap).

This is INDEX-driven recall. The model pays context tokens for capability awareness, not capability content. The pattern scales to thousands of notes without scaling prompt cost.

When the model writes its response, it can include structured capture markers — fenced JSON blocks or tool calls — that the runtime extracts and turns into new atomic notes, journal additions, or memory updates. The model never directly writes to the file system; the runtime mediates every write, validates the shape, and applies the project's WritePolicy rules.

Two paths: Path 1 uses native tool calls (the model explicitly invokes a capture tool). Path 2 uses fenced-JSON markers in the response prose. Both produce identical artifacts on disk.

Every agent.call() path checks _check_cost_guardrails before the first LLM call and re-checks each iteration of the multi-turn loop. Daily and monthly caps are set in model.md. When 50% of daily is reached, a warning lands in the log. At 80%, a stronger warning. At 100%, the next call refuses unless explicitly marked critical=True.

Helper batches (cheap sub-LLM calls used for transformations) reserve their worst-case cost before dispatch. Delegated calls (one agent calling a specialist) clamp the child's budget to the minimum of (child's own cap) and (parent's remaining budget for this run). This tree-cap is what makes "run a fleet of agents" not bankruptcy.

Long-running pipelines outside call() — dream, eval, tuning — have their own cost gates. The discipline: every code path that calls an LLM has a cost gate, even when it's not the same gate.

Every tool call is classified into one of four action classes in tools.md. The class_policy block in judges.md says what the framework does with each class:

bypass

Skip the judge entirely. No proposal, no judgment event, no audit line.

allow_with_audit

Run the judge; always allow; write the full judgment event to the audit trail. Use when you want to see the judge's opinion without it gating actions yet.

judge_required

Run the judge; its outcome is enforced. BLOCK refuses; ALLOW executes; REVISE/ESCALATE follow the state-machine semantics.

escalate

Pause for operator approval. Framework writes a PENDING file; agent.call() returns deferred; operator resolves by editing the file in any text editor.

Strictness ordering: bypass < allow_with_audit < judge_required < escalate. Unspecified classes default-fill to safe values.

When the judge ensemble returns ESCALATE, the action is paused for operator review. The framework writes a PENDING file to <agent_root>/vault/escalations/<action_class>/<proposal_id>.md (atomic, with full proposal serialized as YAML and the judge's reason inline), and agent.call() returns with deferred=True.

The operator resolves a PENDING by editing the file in any text editor (Obsidian, vim, VS Code) and writing one resolution block at the bottom. Header grammar is strict — h3 + exact-case verb + literal word "by" + operator name:

### Approved by alice
resolved_at: 2026-05-13T09:14:22Z
note: Reviewed — sender list is correct, attachment is the public report.

The five resolution verbs are Approved, Denied, Redacted, Revised, and Auto-decided (the framework writes this itself when a timeout elapses). On the next agent.call(), the framework reads the decision, re-verifies the proposal's body hash hasn't been tampered with, and executes (or doesn't) accordingly.

REVISE is the most interesting outcome. The judge might say: "Send this email, but strip the attachment" or "Open the PR as draft, not for merge." The framework merges the amendment into the original proposal (recomputing the classification from the possibly-new tool name), re-runs the judge once against the amended proposal, and if the second judgment ALLOWs, executes the amended version.

Bounded at one revise iteration per spec/28 — the second judgment must return ALLOW to execute; REVISE again produces revise_loop_exhausted_blocked. Operators see this path as a sequence of audit events. No PENDING file is written for judge-driven revises.

Operator-driven revises (via the ### Revised by <op> resolution block with an embedded amendment YAML) follow the same primitives but with one extra gate: if the amendment upgrades the action class (e.g., reversible_write → high_risk), the framework re-runs a fresh ensemble judgment on the amended proposal. An operator can't downgrade their way past the judge by relabeling.

When a judge errors (timeout, budget exhausted, malformed proposal), the framework consults failure_policy to decide the enforcement outcome. Default is block for every exception type — operators must explicitly opt into looser behavior.

Two shapes are accepted. Flat (one fallback for every class):

failure_policy:
  JudgeUnavailable: block
  JudgeBudgetExhausted: block

Nested per-class (different fallback per (action_class, exception) pair):

failure_policy:
  read_only:
    JudgeUnavailable: allow      # read_only actions tolerate judge outages
  high_risk:
    JudgeUnavailable: escalate   # high_risk actions escalate to operator

The parser auto-detects which shape you used.

Dreams run as a separate pipeline (atomic_agents.dream) with their own state machine: scan (collect journal entries and memory candidates from the relevant time window), propose (LLM-driven analysis producing structured suggestions), review (optional judge pass), commit (write the approved changes to memory and journal).

Dream proposals are not auto-applied — they flow through the same capture pipeline as any other run. If the agent has a judge configured, the judge sees the dream's proposed changes the same way it sees any other side-effectful action. An operator can review and approve at the same surface they review any other agent decision.

Dreams have their own cost gate (_check_cap) — they're typically the most expensive single pass an agent runs, because consolidation requires the agent to consider its entire recent history.

Helpers are cheap sub-LLM calls used for transformations: "summarize this", "extract entities from that", "classify this into one of three buckets." They're typically Haiku-class (fast, cheap) and run in parallel batches. When a helper produces an output that informs the main agent's reasoning, the runtime preserves the helper provenance — which helper produced which output, with which prompt, at which cost — and rolls it up into the parent run's audit record.

This matters because debugging an agent's reasoning sometimes requires tracing back through what its helpers told it. The provenance trail lets you reconstruct any agent decision down to the helper-prompt level.

Eval (atomic_agents.eval) runs the agent against curated test cases organized by category: happy path, edge cases, adversarial inputs, decline cases (things the agent should refuse). Each category produces pass/fail metrics and qualitative judgments from an LLM-as-judge that scores along configurable rubrics.

Tuning (atomic_agents.tuning) takes the eval results and proposes persona refinements — "the SOUL.md draft is producing too-formal output on edge cases; consider this adjustment." The proposals are not auto-applied. The operator reviews them as standard markdown diffs.

Both run as long-lived pipelines with their own cost gates, separate from the per-call cost guardrails on agent.call().

Concretely, switching from filesystem-everything to SQLite-for-logs looks like setting one environment variable:

export ATOMIC_AGENTS_LOG_BACKEND=sqlite
export ATOMIC_AGENTS_LOG_BACKEND_URL=sqlite:///shared/logs.db
uv run atomic-agents run scout --work-item "Daily morning brief"

That's it. The agent's folder doesn't change. The agent's persona doesn't change. The runtime sees the env var, dispatches log writes to SQLite, and everything else continues as before. Tomorrow you can flip it back. Next month you can flip Profile to SQLite too. The home user has none of these env vars set; they get the filesystem defaults and never need to think about it.

SQLite-shape backends need just the _BACKEND=sqlite flip — the DB path is derived from a sensible default. Redis-shape backends need both _BACKEND=redis AND _BACKEND_URL=redis://... because there's no derivable default for a Redis instance address.

The eighth-and-a-half protocol. Where MandateBackend is per-agent durable authorization, PolicyBackend is the fleet-wide policy layer that supersedes per-agent caps and allowlists. A company can author a policy.md at the project root that says "no agent in this tenant may spend more than $50/day, regardless of what their model.md says" — and the framework enforces that cap on every run.

Cost-cap consumption shipped (the daily/monthly caps in policy.md now enforce on real money). The non-cap surfaces (tool allowlists, model allowlists, MCP allowlists) ship next in log-only mode behind a feature flag. The final PR locks the spec.

The semantic shift: per-agent caps in model.md set what the agent can spend; PolicyBackend sets what the operator permits it to spend. Operator-level always wins.

Anyone — a third party, a company integrating internally, you in a year — can write a new backend. They drop their implementation into the conformance test harness. If the tests pass, their backend is fully interoperable with everything else. If the tests fail, they know exactly which guarantees they're violating.

The framework isn't trying to ship every possible backend itself; it's trying to be a contract that other backends can plug into. The 8-MUST Implementer contract documented in each protocol's spec doc is the rulebook every implementation has to follow.