/gaia-memory-hygiene

user-facing
Category:
Getting Started
Lifecycle phase:
Any
Arguments:
[--dry-run]

What it does

/gaia-memory-hygiene scans GAIA's internal agent memory files for stale, contradicted, and orphaned decisions. It cross-references each decision against current project artifacts, classifies each entry, reports token budget usage per agent, recommends archival actions, and -- with your explicit confirmation per entry -- archives or removes outdated content.

When to use it

  • After several sprints, when agent memory may contain decisions that no longer reflect the current architecture or PRD.
  • When agents seem to reference outdated information during workflows.
  • As periodic maintenance -- once per sprint is a good cadence.

Prerequisites

  • Memory directory must exist. The _memory/ directory must be present. If it does not exist, the command exits with "no sidecars discovered."

How to invoke

/gaia-memory-hygiene

Full scan with interactive archival prompts.

/gaia-memory-hygiene --dry-run

Scan and report only -- no files are modified.

What it does step by step

  1. Discover sidecars Finds all agent memory directories under _memory/*-sidecar/, classifies each by tier (Tier 1/2/3), and identifies empty or legacy-format sidecars.
  2. Scan each sidecar Reads decision logs, ground truth, and context files. Builds a content inventory with file sizes for budget calculations.
  3. Load reference artifacts Reads current versions of the PRD, architecture, epics, test plan, and sprint status to use as comparison baselines.
  4. Cross-reference validation Checks each decision's references against other agents' decisions and against the filesystem. Identifies orphaned references and superseded cross-agent pointers.
  5. Classify entries Assigns each entry one of five statuses: ACTIVE (consistent), STALE (referenced artifact changed), CONTRADICTED (current artifact says the opposite), ORPHANED (referenced entity removed), or UNVERIFIABLE-FORMAT (cannot parse).
  6. Token budget reporting Calculates token usage per agent and flags agents that are near or over their memory budget.
  7. Generate recommendations Recommends archival for entries under budget pressure, with stale status, or older than 3 sprints. Each recommendation includes the estimated token recovery.
  8. Present report Writes a hygiene report with summary, token budget table, detailed findings, archival recommendations, and ground-truth refresh suggestions.
  9. User action (interactive mode only) For each flagged entry, asks you to choose: Keep, Archive, or Delete. No changes are made without your per-entry confirmation.
  10. Optional checkpoint pruning Offers to clean up old completed checkpoints from _memory/checkpoints/completed/.

Inputs

Input Source Description
--dry-run Command argument (optional) Run the scan and report without modifying any files.
Agent sidecar files _memory/*-sidecar/ Decision logs, ground truth, and context files for each agent.
Reference artifacts docs/ directories Current PRD, architecture, epics, test plan, sprint status.

Outputs

Output Location Description
Hygiene report .gaia/artifacts/implementation-artifacts/memory-hygiene-report-{date}.md Full findings report with seven sections: summary, token budget, findings, archival recommendations, ground-truth refresh, untiered agents, and skipped sidecars.
Modified sidecars _memory/*-sidecar/ Only if you confirm per-entry actions in interactive mode.

Example session

> /gaia-memory-hygiene --dry-run

6 sidecars discovered (2 Tier 1, 2 Tier 2, 1 Tier 3, 1 untiered).
0 empty. 1 legacy filename detected.

Token Budget Table:
| Agent     | Tier | Token Usage | Budget  | % Used | Status  |
|-----------|------|-------------|---------|--------|---------|
| architect | T1   | 12,400      | 150,000 | 8%     | OK      |
| pm        | T1   | 8,200       | 100,000 | 8%     | OK      |
| security  | T2   | 45,000      | 50,000  | 90%    | warning |
| devops    | T2   | 3,100       | 50,000  | 6%     | OK      |
| sm        | T3   | 1,200       | --      | --     | OK      |

Findings:
  3 STALE (referenced artifacts changed)
  1 CONTRADICTED (architecture decision superseded)
  2 ORPHANED (story keys removed from epics)
  1 UNVERIFIABLE-FORMAT

Archival Recommendations:
  1. security / 2026-03-15 auth decision -- STALE (~800 tokens)
  2. security / 2026-02-28 api key rotation -- STALE (~600 tokens)

Ground Truth Refresh:
  architect -- last refresh: Sprint 8, current: Sprint 11 (3 behind)
    Recommended: /gaia-refresh-ground-truth --agent architect

Report written to:
  .gaia/artifacts/implementation-artifacts/memory-hygiene-report-2026-05-07.md

(Dry-run mode -- no files were modified.)

What to run next

  • Run again without --dry-run to act on the recommendations.
  • /gaia-refresh-ground-truth -- if the report flagged stale ground truth for any agent.

Troubleshooting

"No sidecars discovered"

The _memory/ directory does not exist. This is normal for new projects that have not yet run workflows that produce agent memory.

"All sidecars are empty"

Sidecar directories exist but contain no decision content yet. Run a few GAIA workflows first -- agents write decisions as they work.