Antigravity Brain Architecture

Internal Trajectory Storage, Transcripts & Execution Specification

Skill Spec Code Walkthrough v1.0 • Specification

The Antigravity Brain Directory Specification

Google Antigravity stores conversation histories, agentic chain-of-thought trajectories, tool calls, execution outputs, and persistent artifacts in structured "brain" directories under ~/.gemini/. This guide documents the filesystem hierarchy, dual-mode JSONL transcripts, step execution lifecycle, metadata parsing rules, and cross-session discovery algorithms.

~/.gemini ROOT STORAGE
JSONL TRANSCRIPT FORMAT
2 TRANSCRIPT TIERS
UUIDv4 SESSION KEYS
v1.0.0 SPECIFICATION
Storage Architecture

1. Overview & Multi-Brain Root Locations

In Google Antigravity, every conversation session between a human developer and the AI agent is recorded as a durable, stateful trajectory in a Brain Directory. Rather than storing records in an opaque SQLite database or a remote cloud cluster, Antigravity structures sessions as standard filesystem trees composed of human-readable JSON Lines (JSONL) files, plain-text command outputs, and Markdown artifacts.

Depending on which Antigravity tool or interface initiated the agent, session directories are partitioned into specific brain storage roots located in the user's home directory under ~/.gemini/:

Brain Storage Root Environment / Product Typical Content & Workflows
~/.gemini/antigravity/brain/ Antigravity IDE & Desktop App Full-featured desktop pair-programming sessions, multimodal interactions, generative UI views, and project refactors.
~/.gemini/antigravity-cli/brain/ Antigravity CLI (agy) Terminal-based coding sessions, autonomous background tasks, quick fixes, and slash command pipelines.
~/.gemini/antigravity-acp/brain/ Agent Client Protocol (ACP) Headless agent integrations, CI/CD automated test generation, and subagent orchestration runs.
💡
Universal Discovery: The companion exploration tool agy-brain-explorer.py automatically scans all subdirectories under ~/.gemini/ matching the pattern */brain/, dynamically aggregating and indexing sessions across all environments without manual configuration.
Filesystem Layout

2. Session Directory Hierarchy

Each Antigravity session directory is keyed by a canonical UUIDv4 (e.g., 74126ecc-9639-4ff3-9dcb-7ac2d9400986). Inside this directory, files are partitioned into system-generated telemetry, agent scratchpads, user-uploaded data, and persistent user-facing artifacts:

Session Filesystem Tree Structure 
<brain_root>/<session_uuid>/
├── .system_generated/
│   ├── logs/
│   │   ├── transcript.jsonl            # Token-efficient compact JSONL transcript
│   │   ├── transcript_full.jsonl       # Complete, untruncated JSONL transcript
│   │   └── chunks/                     # (Optional) Incremental/rolling log chunks
│   │       ├── transcript/
│   │       │   └── 00000000.jsonl
│   │       └── transcript_full/
│   │           └── 00000000.jsonl
│   └── steps/
│       └── <step_index>/
│           └── output.txt              # Captured stdout/stderr or step execution log
├── scratch/                            # Persistent scratchpad for scripts & temp files
├── .user_uploaded/                     # Files uploaded into the session by the user
└── <artifact_name>.md                  # Persistent markdown artifacts (e.g. implementation_plan.md)

Directory Components & Operational Roles:

  • .system_generated/logs/: The core telemetry engine. Contains sequential execution logs stored in JSON Lines format, documenting every step from initial prompt to final response.
  • .system_generated/steps/<step_index>/output.txt: Stores raw command output, long tool returns, and build logs separated from the JSON transcript to prevent memory ballooning during LLM context feeding.
  • scratch/: A sandboxed, persistent workspace for temporary testing scripts (e.g. test_parse.py), benchmark outputs, or intermediate data files created by the agent.
  • .user_uploaded/: Preserves files, screenshots, logs, or sample datasets that the developer uploaded through the Antigravity user interface.
  • *.md (Root Artifacts): User-facing markdown documents such as implementation_plan.md and walkthrough.md, created via the write_to_file tool with formal artifact metadata.
Interactive Tool

3. Interactive Directory Tree Explorer

Click any node in the directory structure below to inspect its role, format specifications, lifecycle, and sample content:

📁 <session_uuid>/
📁 .system_generated/
📁 logs/
📄 transcript.jsonl
📄 transcript_full.jsonl
📁 chunks/
📁 steps/
📄 <idx>/output.txt
📁 scratch/
📁 .user_uploaded/
📄 *.md (Artifacts)
📁 <session_uuid>/
TYPE: Directory • REQUIRED: Yes • NAMING: UUIDv4
The top-level session root container. Represents an independent agentic run or pair-programming conversation. All conversation logs, artifacts, uploaded files, and scratch scripts are contained strictly within this directory.
Path Pattern 
~/.gemini/antigravity/brain/74126ecc-9639-4ff3-9dcb-7ac2d9400986/
Telemetry Engine

4. Dual-Mode JSONL Transcripts

Antigravity implements a high-performance, dual-tiered transcript logging architecture. Every interaction turn writes to two distinct JSON Lines files simultaneously:

File Name Truncation Policy Primary Consumer Key Operational Purpose
transcript.jsonl Truncated when large Agent Context & Rapid Scanners Token-efficient. Output texts or tool inputs exceeding thresholds are trimmed to keep agent context compact while preserving 1-to-1 line mapping.
transcript_full.jsonl Untruncated (Full fidelity) Auditing & Forensic Review Complete execution record. Contains unabridged model reasoning, long code payloads, and complete tool arguments without truncation.
ℹī¸
Strict 1-to-1 Step Invariant: Line N in transcript.jsonl corresponds exactly to line N in transcript_full.jsonl. When an agent detects a "truncated_fields": ["content"] array in the compact transcript, it can surgically fetch only line N from transcript_full.jsonl without parsing the entire file into memory.
Data Contracts

5. Trajectory Step Schema

Each line within a transcript file is a self-contained JSON object representing a discrete execution step (turn). The schema is strictly typed with the following structure:

Step Record JSON Schema (TypeScript Definition) 
interface TrajectoryStep {
  /** 0-indexed chronological execution step number */
  step_index: number;
  
  /** Actor that produced the step */
  source: "USER_EXPLICIT" | "MODEL" | "SYSTEM";
  
  /** Semantic type of the interaction step */
  type: "USER_INPUT" | "PLANNER_RESPONSE" | "GENERIC";
  
  /** Execution status */
  status: "DONE" | "ERROR" | "CANCELLED";
  
  /** ISO 8601 creation timestamp in UTC (e.g. 2026-09-14T10:41:53Z) */
  created_at: string;
  
  /** Body content (prompts, tool returns, system notices, or chat prose) */
  content?: string | null;
  
  /** Internal chain-of-thought reasoning from the model */
  thinking?: string | null;
  
  /** Tool invocations initiated by the model */
  tool_calls?: Array<{
    name: string;
    args: Record<string, any>;
  }>;
  
  /** Present only in transcript.jsonl when truncation occurred */
  truncated_fields?: Array<"content" | "thinking" | "tool_calls">;
}
Field Type Req Detailed Semantic Role
step_index integer Yes Sequential index starting at 0. Maps directly to step output folders (.system_generated/steps/<step_index>/).
source enum Yes USER_EXPLICIT (human inputs), MODEL (LLM responses & actions), or SYSTEM (environmental notifications).
type enum Yes USER_INPUT (user prompt), PLANNER_RESPONSE (model reasoning & tool dispatch), or GENERIC (tool execution feedback).
status enum Yes Lifecycle state. Almost universally "DONE" upon successful step completion.
created_at string Yes ISO 8601 timestamp with timezone offset or UTC Z suffix. Used for chronological sorting and duration calculation.
thinking string No Internal cognitive scratchpad where the model analyzes requirements and plans tool calls prior to execution.
tool_calls array No Contains the tool function name and input argument dictionary.
Agent Tooling

6. Tool Calls & Argument Structures

When a model produces a PLANNER_RESPONSE, it may dispatch one or more tool calls. Every tool call provides standard metadata arguments (toolAction and toolSummary) that allow user interfaces and CLI tools to render human-readable progress indicators.

Tool Name Core Parameters UX Metadata Description & Behavioral Guardrails
run_command CommandLine, Cwd, WaitMsBeforeAsync, BypassSandbox toolAction, toolSummary Executes shell commands in a sandbox or unsandboxed mode. Output is piped to output.txt.
view_file AbsolutePath, StartLine, EndLine toolAction, toolSummary Reads file contents slice-by-slice (up to 800 lines per call).
write_to_file TargetFile, CodeContent, Overwrite, ArtifactMetadata toolAction, toolSummary Creates new code files or persistent artifacts. Requires metadata when creating artifacts.
replace_file_content TargetFile, StartLine, EndLine, TargetContent, ReplacementContent toolAction, toolSummary Surgically replaces a contiguous block of text in an existing file.
list_dir DirectoryPath toolAction, toolSummary Lists directory contents with file sizes and directory child counts.
find_by_name SearchDirectory, Pattern, Extensions toolAction, toolSummary High-speed file name discovery powered by fd.
grep_search SearchPath, Query, IsRegex, MatchPerLine toolAction, toolSummary Regex and literal content searching powered by ripgrep.
call_mcp_tool ServerName, ToolName, Arguments toolAction, toolSummary Dispatches calls to Model Context Protocol (MCP) servers (e.g. Flutter, Firebase, Chrome).
invoke_subagent Subagents (array of { TypeName, Role, Prompt }) toolAction, toolSummary Spawns concurrent autonomous subagents with separate conversation trees.
Execution Logs

7. Execution Step Outputs (.system_generated/steps/)

Tools that generate extensive terminal output, compiler diagnostics, or large payloads (such as run_command or unit test runners) do not bloat the JSON transcript. Instead, Antigravity writes the raw output stream to an external file:

Step Output Location Pattern 
<session_dir>/.system_generated/steps/<step_index>/output.txt

Key Architectural Characteristics:

  • Correlation: The directory name <step_index> corresponds exactly to the step_index field of the triggering action step.
  • Format: Raw, unescaped UTF-8 plain text containing stdout, stderr, and terminal exit codes.
  • Deduplication Invariant: In `agy-brain-explorer.py`, the viewer checks if the text in `output.txt` is already present inside `step.content`. If identical, it avoids duplicate printing to keep audit timelines clean.
Persistence

8. Artifacts & Scratchpad

In addition to transcripts, an Antigravity brain directory maintains persistent workspace files that live across individual conversational turns:

Resource Path Purpose & Lifecycle
Implementation Plan <session_dir>/implementation_plan.md Architectural design document created prior to code modification. Requires user approval before execution.
Walkthrough <session_dir>/walkthrough.md Post-execution verification report summarizing code changes, test results, and visual artifacts.
Scratch Directory <session_dir>/scratch/ Persistent scratchpad where the agent creates one-off scripts (e.g. data verification, custom parsers) without polluting the user's git workspace.
User Uploads <session_dir>/.user_uploaded/ Contains files, screenshots, or datasets dragged and dropped into the Antigravity chat input box.
Algorithms & Heuristics

9. Metadata Extraction & Discovery Heuristics

Because Antigravity injects contextual metadata into USER_INPUT turns, exploration tools apply regular expression heuristics to extract environment information:

Metadata Field Parsing Pattern / Heuristic Example Match
User Request r"<USER_REQUEST>\s*(.*?)\s*</USER_REQUEST>" Please convert the python script into a HTML file
Active Model r"setting `Model Selection` from .*? to ([^\n\r]+?)\.\s*No need" Gemini 3.8 Flash (Medium)
Local Timestamp r"The current local time is:\s*([^\n\r.]+)" 2026-09-14T20:26:49+10:00
Mentioned Files r"@\[([^\]]+)\]" @[ptsav.dat], @[SKILL.md]
Workspace Root Tool args args.get("Cwd") or <user_information> mapping /Users/brett/Documents/GitHub/antigravity-brain-exploration

Chronological Sorting & Resolution Order:

  • Chronological Sorting: Sessions MUST NOT be sorted alphabetically by UUID. agy-brain-explorer.py parses created_at from step 0 (falling back to directory st_ctime) and sorts newest-first so the user always sees their most recent conversations.
  • Prefix Resolution: If a user specifies a short 8-character prefix (e.g. bb50bdc8), the discovery engine scans all brain roots and resolves the complete UUID automatically.
  • Multi-Brain Tiebreaking: If an identical session ID exists in multiple roots, the discovery algorithm selects the one with the latest modification timestamp (st_mtime).