---
name: vault-stats
description: Report how the owner's vault is growing — total note count, word/character volume, size on disk, a per-area breakdown, and what's been added recently (new notes this week / since the last run, and the fastest-growing areas). Wraps the engine's `vault_stats` module (installed `alexandria-vault` package). Use when the owner says "vault stats", "how big is the vault", "how much has the vault grown", "how many notes do I have", "vault growth", "which areas are growing", or wants a size/growth read on the vault. Read-only against the vault; it persists a small daily history so run-over-run trends survive. NOT the digest/todo content, and NOT a git-history audit.
served: true
---

# Vault stats

A thin trigger over a **read-only** growth-metrics tool. It reports the vault's size and how it's changing over time; it never writes to the vault (only its own `history.json` snapshot next to the script).

When this skill fires:

1. **Run the tool.** If you hold the brain's own tools — the default when you're connected to a running brain, and answered by whether `capabilities()` resolves — call **`vault_stats`** and skip the shell entirely; it runs the same engine and returns the same read. Otherwise, from a vault checkout:
   ```sh
   "${ALEXANDRIA_PYTHON:-python3}" -m alexandria_vault.engine.vault_stats --vault .            # human summary + save today's snapshot
   "${ALEXANDRIA_PYTHON:-python3}" -m alexandria_vault.engine.vault_stats --vault . --json     # machine-readable
   "${ALEXANDRIA_PYTHON:-python3}" -m alexandria_vault.engine.vault_stats --vault . --since 30d --top 12
   "${ALEXANDRIA_PYTHON:-python3}" -m alexandria_vault.engine.vault_stats --vault . --no-save  # compute without touching history.json

   (The engine lives in the installed `alexandria-vault` package, not in the vault.
   `ALEXANDRIA_PYTHON` — the app venv's python — is the interpreter that has it; plain
   `python3` works wherever the package is pip-installed.)
   ```
2. **Report the read** — total notes · words · size on disk, the growth since the last snapshot and the git "new notes" window, the biggest areas, and the fastest-growing areas. Lead with the headline (size + recent growth); keep it skimmable per `Agent/Working Style.md`.
3. **Read-only.** Don't file the output as a note unless the owner asks; the tool's `history.json` already persists the trend.

The tool finds the vault root itself (`$VAULT_DIR`, else walks up to `Areas/` + `AGENTS.md`) and buckets notes by top-level folder / `Areas/<Area>`, so its per-area breakdown tracks the PEAK layout automatically.
