Skip to content

Brain Cache Manager

Jump to bottom
ChillingWombat edited this page Oct 11, 2026 · 1 revision

Brain Cache Manager

Features / Brain Cache Manager

The Brain Cache Manager inspects disk consumption, categorizes cache artifacts, and enforces retention limits across Antigravity's local session directories.

1. Storage Footprint & Cache Structure

Antigravity executes autonomous tasks, code modifications, and subagent runs locally, accumulating high-volume transient data on disk. Unchecked sessions can consume tens of gigabytes within weeks.

The cache engine monitors five core storage zones:

~/.gemini/antigravity/
├── brain/
│   └── <conversation-uuid>/
│       ├── .system_generated/tasks/   (subagent logs and background task traces)
│       ├── scratch/                   (temporary scripts, test runs, test binaries)
│       └── artifacts/                 (generated markdown documents, plans, diffs)
├── conversations/                     (SQLite WAL databases and conversation summaries)
├── code_execution/                    (sandboxed execution scratch workspaces)
└── screenshots/                       (browser automation and visual diff captures)

2. Disk Usage Categorization

The Brain Cache Manager performs fast filesystem walks using concurrent Go routines, reporting storage consumption broken down by:

  • Task Logs & Process Traces: Raw output files, stdout/stderr streams, and execution telemetry generated by background subagents.
  • Scratchpads & Binaries: Ephemeral Go, Python, and Node.js scripts executed during tool use.
  • Visual Artifacts & Screenshots: High-resolution PNG captures from browser automation and UI testing tools.
  • Conversation Databases: Historical SQLite databases containing chat records, search indexes, and message embeddings.

3. Pruning Rules & Automated Cleanup

Developers can trigger one-click cleanups or configure automated background pruning policies:

Retention Age Limits

The pruner evaluates file modification timestamps ($mtime$) against configured thresholds:

  • Supported retention presets: 3 Days, 7 Days, 14 Days, 30 Days, 3 Months, 6 Months, 1 Year, or Unlimited.
  • Files older than the selected horizon are marked as prune candidates during cache scans.

Maximum Storage Ceilings

  • A configurable gigabyte limit (e.g., 5 GB, 10 GB, 25 GB, or 0 for unlimited).
  • When total cache volume exceeds the ceiling, the cleaner purges candidates starting from the oldest inactive task directories using LRU (least recently used) sorting.

Automated Daemon Pruning

When enabled via the Auto-Prune toggle, the Swiss Knife background daemon executes a lightweight cache pass every 24 hours, keeping storage within bounds without requiring manual intervention.

4. Operational Safety Guards

The pruner enforces four invariant guards before removing any file:

  1. Active Process Protection: Never purges scratchpads belonging to active PIDs or open conversation sessions indexed in SingletonLock.
  2. Pinned Artifact Preservation: Artifacts explicitly tagged as persistent or pinned in the project panel are excluded from deletion.
  3. Database Integrity: SQLite WAL files (state.vscdb-wal) and uncommitted transaction logs are never removed while database handles remain open.
  4. Deterministic Dry-Run Scans: Clicking "Scan Cache" provides a detailed breakdown of candidates, estimated reclaimable gigabytes, and file counts before any irreversible deletion occurs.

Clone this wiki locally