# Brain Cache Manager

[Features](Features.md) / 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:

```text
~/.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.