Antigravity Multi-Agent State Tiers — A Three-Layer Design with Ephemeral, Journal, and Canonical

Journal — days to weeks of decision logs that you could re-derive, but slowly

Journal is for information that you can technically reconstruct, but only at meaningful cost in time or money. Agent decision rationales, A/B intermediate scores, Browser Sub-agent observations of an AdMob dashboard delta, automatic-repair logs — all journal.

The test for journal is one question: "If we lost this, could we live without it but only at a half-day cost?" I have had multiple incidents where missing journal data meant burning a day or two replaying agent decisions. The painful variant is when the output survived but the reasoning did not — you can see what the agent produced, yet you cannot tell why it branched that way, so you walk into the same mistake again. I take that tier seriously now.

Cloudflare KV is a near-perfect physical match — cheap reads, metered writes, eventual consistency, all of which suit "write rarely, read sometimes, freshness is loose."

// state/journal.ts
export class JournalStore {
  constructor(private kv: KVNamespace, private agentId: string) {}
 
  private k(scope: string, id: string): string {
    // Namespace by agent so cross-agent reads cannot collide.
    return `journal:${this.agentId}:${scope}:${id}`;
  }
 
  async append(scope: string, entry: Record<string, unknown>): Promise<void> {
    const id = crypto.randomUUID();
    const value = JSON.stringify({ at: Date.now(), ...entry });
    // Always set a 30-day TTL. Journal is not permanent.
    await this.kv.put(this.k(scope, id), value, { expirationTtl: 60 * 60 * 24 * 30 });
  }
 
  async list(scope: string, limit = 50): Promise<Array<Record<string, unknown>>> {
    const { keys } = await this.kv.list({ prefix: this.k(scope, ""), limit });
    const items = await Promise.all(keys.map((k) => this.kv.get(k.name, "json")));
    return items.filter(Boolean) as Array<Record<string, unknown>>;
  }
}

Two operational notes. First, always prefix journal keys with journal: even if you do not share KV with canonical today — your future self will thank you when the boundary moves. Second, always attach a TTL. Without one, agents start dragging months of context into their next decision and begin to behave erratically. I have made that mistake twice across this fleet and now hard-code 30 days for everything.

At a small scale — on the order of 100k writes and 1M reads a month — the journal tier fits inside the KV allowance that comes with the Workers paid plan. In my setup it has never become a line item worth worrying about inside the ¥800/month per-site envelope.

Canonical — the source of truth your product cannot survive without

Canonical is the information whose loss ends the product. Published article slugs, Stripe purchases, premium membership records, monthly AdMob revenue rollups (technically refetchable, but throttled by API limits) — canonical.

My personal rule is strict: the agent never owns canonical. Canonical lives in the surrounding system, and the agent only reads or writes back to it. The moment an agent thinks it owns canonical, an agent bug becomes a product-wide outage.

For physical mapping I lean on two choices depending on the shape of the data.

A concrete case: in Antigravity Lab, the canonical list of published slugs is the GitHub repo itself. The agent clones it, reads it, and writes back only via the GitHub API. The agent's KV and DO are journal-tier; once the change lands in Git, they can be thrown away.

Here is a minimal Durable Object adapter for the case of "concurrent purchase grants" — the kind of canonical write where two requests can hit the same key at the same time.

// state/canonical-do.ts
export class PurchaseRegistry {
  state: DurableObjectState;
  constructor(state: DurableObjectState) { this.state = state; }
 
  async fetch(req: Request): Promise<Response> {
    const url = new URL(req.url);
    if (req.method === "POST" && url.pathname === "/grant") {
      const { email, slug } = await req.json<{ email: string; slug: string }>();
      // Safe under concurrent retries — DO guarantees single-instance semantics.
      const key = `grant:${email}:${slug}`;
      const existing = await this.state.storage.get(key);
      if (existing) return new Response(JSON.stringify({ already: true }));
      await this.state.storage.put(key, { grantedAt: Date.now() });
      return new Response(JSON.stringify({ granted: true }));
    }
    return new Response("not found", { status: 404 });
  }
}

Resuming a long-running task after a crash is a separate concern, which I cover in Antigravity × Durable Execution: Designing Fault-Tolerant Long-Running AI Tasks; here I only care about what lives outside the agent.

Keeping canonical outside the agent buys you something priceless: the freedom to throw the agent away and rebuild. An agent that owns canonical is one you are scared to redeploy. Working solo, I rebuild agents constantly, so that freedom is a structural asset rather than a nicety.

Mapping three tiers onto Cloudflare stores — KV / DO / R2 / D1

I decide the mapping with three axes:

1. Lifetime: 1 run / dozens of days / permanent
2. Concurrent writes: can multiple agents hit the same key at the same time?
3. Query shape: single-key read, prefix scan, or SQL/joins?

That collapses into a near-mechanical decision tree.

• 1 run, no concurrency, single-key reads → ephemeral (in-memory Map).
• Dozens of days, near-zero concurrency, prefix scans suffice → journal (KV).
• Permanent, concurrent writes, single-key reads → canonical (Durable Object).
• Permanent, no concurrency, want SQL → canonical (D1).
• Permanent, large, read-heavy → canonical (R2 snapshots).

Early on I dumped everything into KV and accidentally crossed agent boundaries five or six times due to missing prefixes. It only dawned on me that the design was the problem while I was writing the same fix for the third time. Switching to the three-axis decision rule effectively eliminated state-tier bugs at design time. I recommend forcing yourself through these three questions every time you add a new state key.

Boundary design — where to write back, where to snapshot

Splitting the tiers is not enough; you also have to decide where information crosses between tiers. In my fleet there are three boundaries worth naming.

Step 1. ephemeral → journal (write-down) Only the decisions worth replaying should land in journal — typically the moments an agent branched on a non-trivial choice. Writing every intermediate value bloats the journal; I keep the rule "log a journal entry only when the agent made a branching decision."

Step 2. journal → canonical (write-back) This is the boundary you must design most carefully. I strongly recommend a human-in-the-loop checkpoint here, or at minimum an out-of-band notification (email or Slack). I have had an agent decide on its own to flip 12 premium articles back to free in a single batch, and the recovery took half a day. A 5-second confirmation delay or a single approval click would have caught it.

Step 3. canonical → journal (read-back snapshot) The reverse flow is just as important. Periodically snapshotting canonical into journal keeps the agent from spamming canonical reads (and helps you stay under GitHub's 5,000 req/hour ceiling). An hourly snapshot is usually enough.

A write that was supposed to cross a boundary and never happened at all is a different failure, and I catch it with a separate observability layer — see Catching "Running but Doing Nothing" Antigravity Subagents — A 3-Layer Observability Pattern Across Six Production Apps.

Once you spell these three boundaries out in code, the agent reads dramatically more clearly. Leave them implicit, and you will not be able to tell whether a given function is touching ephemeral or canonical without a 10-minute audit.

Implementing the approval gate — the smallest code that stops a write-back

"Put a human in the loop" is easy to say and easy to lose in implementation. The smallest version I use carries the tier in the type signature and drops canonical writes into a pending queue instead of applying them.

// state-gate.ts — one gate, three tiers, different write semantics
type Tier = "ephemeral" | "journal" | "canonical";
 
interface PendingWrite {
  id: string;
  key: string;
  value: unknown;
  reason: string;      // why the agent wanted to write
  createdAt: number;
}
 
interface GateDeps {
  journal: KVNamespace;
  canonical: DurableObjectStub;
  notify: (w: PendingWrite) => Promise<void>;
}
 
const JOURNAL_TTL = 60 * 60 * 24 * 30; // 30 days
 
export async function write(
  tier: Tier,
  key: string,
  value: unknown,
  reason: string,
  deps: GateDeps,
): Promise<{ applied: boolean; pendingId?: string }> {
  if (tier === "ephemeral") {
    // caller keeps it in a Map; nothing is persisted
    return { applied: true };
  }
 
  if (tier === "journal") {
    await deps.journal.put(key, JSON.stringify({ value, reason }), {
      expirationTtl: JOURNAL_TTL,
    });
    return { applied: true };
  }
 
  // canonical never applies inline
  const pending: PendingWrite = {
    id: crypto.randomUUID(),
    key,
    value,
    reason,
    createdAt: Date.now(),
  };
  await deps.journal.put(`pending:${pending.id}`, JSON.stringify(pending), {
    expirationTtl: 60 * 60 * 24 * 3, // expires in 3 days if nobody approves
  });
  await deps.notify(pending);
  return { applied: false, pendingId: pending.id };
}
 
export async function approve(id: string, deps: GateDeps): Promise<boolean> {
  const raw = await deps.journal.get(`pending:${id}`);
  if (!raw) return false; // expired — a deliberate rejection, not a dropped write
  const p = JSON.parse(raw) as PendingWrite;
  await deps.canonical.fetch("https://do/put", {
    method: "POST",
    body: JSON.stringify({ key: p.key, value: p.value }),
  });
  await deps.journal.delete(`pending:${id}`);
  return true;
}

The return type of write() is the part that matters. Because there is a path that returns applied: false, the calling agent cannot proceed as if the write landed. Make the function return void instead, and the agent has no way to distinguish "pending" from "applied" — it will happily treat a stale value as canonical.

The three-day expiry on pending: is also deliberate. Let approvals pile up indefinitely and you end up approving a change a month later with no memory of what it was for. A forgotten change is safer left unapplied.

Headless runs used to auto-approve silently — a premise that changed

An approval gate is worthless if the execution layer approves on your behalf. This is a case where the ground actually shifted, so it is worth recording.

Antigravity CLI 1.1.3 (2026-07-16) shipped two fixes around headless execution (-p). The first: tools requiring confirmation would either hang the process or get silently auto-approved. After the fix, they soft-reject and print the allow rule name needed for permission to stderr. The second: in always-proceed mode, file writes outside the workspace were being auto-approved by mistake.

If you run tasks unattended overnight, both fixes change your assumptions. On anything older than 1.1.3, a flow you believed was gated may have been passing straight through.

Here is how I verified mine:

1. Check the CLI version with antigravity --version
2. If it is below 1.1.3, update. If you cannot, stop canonical writes from headless runs until you can
3. After updating, run one operation that should require approval under -p and watch for the allow rule name on stderr
4. If nothing appears, that tool is already permitted by an allow rule — go audit the rule list

Step three is the one people skip. Without confirming that a soft rejection actually happens, you are running on the assumption that "the fix landed, so we must be fine." That is where I discovered my own allow rules were written far more broadly than I intended.

One related thing worth checking: a token accounting bug that made conversations hit their limit earlier than expected was fixed in the 2026-07-21 update. If you orchestrate long agent runs, re-measure your consumption afterward. Otherwise it is easy to confuse "stopped because of the limit" with "held by the approval gate."

Later CLI releases made that confusion harder to fall into. CLI 1.2.6 removed the five-minute default timeout on headless -p runs and, on failure, now prints a single structured AGY_ERROR: {...} line to stderr and exits with code 3. CLI 1.2.9 stops the daemon that used to linger after -p finished, and waits for background work up to --print-timeout (capped at 30 minutes).

I rewrote my nightly pass/fail rule around that: exit code 0, and no AGY_ERROR on stderr. A run in which the gate returned applied: false is, from the agent's side, a clean exit — the only trace is the pending notification. Keeping that out of the "failed" bucket is what lets the morning check take five minutes instead of thirty.

Approval waits outside the run; the run itself never waits. When the gate holds a write, the run ends right there, and a different process — me, the next morning — does the approving. Even with --print-timeout stretched to 30 minutes, I refuse to park approval inside it, because a timeout and a hold should never share a log line. The input side of the same problem — rejecting malformed commands before they reach the agent — is in Guarding the Turn Boundary in Non-Interactive Runs: A Command Table and a Fail-Closed Gate.

Three operational rules I refuse to break

A few rules I hold to, drawn from keeping agents running day after day.

1. Always put either a 1-second delay or an approval step in front of canonical writes. Recovering from a runaway canonical write averages half a day, sometimes two. A 5-second confirmation buffer is free. My AdMob revenue rollup agent uses that exact pattern.

2. When in doubt, give journal a 30-day TTL. Extending later is trivial; capping an untimed journal after the fact is the storage equivalent of memory loss. Every journal scope in my Background Agents is locked to 30 days.

3. Never silently drop ephemeral. Provide an explicit dispose() and call it. That single rule wiped out my Isolate-reuse and memory-leak issues. After one painful incident where a Browser Sub-agent ballooned in memory for three days and crashed, I refuse to ship an ephemeral store without it.

All three are about pre-committing to where agent failures are allowed to live — and that is the underlying claim of this whole piece. Agents will misbehave; the design job is to keep their failures inside the smallest tier possible.

The next time you stand up an Antigravity Background Agent, write a one-line comment at the top: "this agent touches ephemeral / journal / canonical." Half of your design review is already done. Keeping failures inside the smallest tier is the one rule I hold onto even on the nights I am in a hurry.