retention

Retention

Overview

Runs the data-retention rules configured in evolve.config.yaml against the local .evolve/ store: private entities under .evolve/entities/ and session transcripts under .evolve/trajectories/. Rules match by entity type plus age (max_age_days, from file mtime) or disuse (max_unused_days, from recall rows in .evolve/audit.log), and either flag (a non-destructive frontmatter marker) or delete. A delete rule on trajectories with cascade_derived: true also deletes the entities derived from those sessions (linked by their trajectory: frontmatter).

The script is dry-run by default — it never mutates anything unless --apply is passed.

Workflow

Step 1: Require rules

Read evolve.config.yaml. If there is no retention: block with a rules: list, show the user this example and stop:

retention:
  rules:
    - name: stale-guidelines
      entity_type: guideline
      max_age_days: 90
      action: flag
    - name: old-sessions
      entity_type: trajectory
      max_age_days: 365
      action: delete
      cascade_derived: true

Each rule needs a name and at least one of max_age_days / max_unused_days; action is flag (default) or delete. Rules are checked top-to-bottom and the first match wins, so put narrow rules first — and put a longer-threshold delete before a shorter-threshold flag on the same type, or the flag shadows the delete and it never fires.

A delete rule may also set on_missing_access_signal to say what happens when an unused match has no recorded recall (disuse measured from file mtime): skip (default, fail-safe — spare it and report it as skipped), flag (downgrade the delete to a non-destructive flag), or delete (delete on the mtime fallback anyway). The safe default means an unused delete never destroys a memory the agent simply never recorded a recall for.

Step 2: Dry run

From the project root:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/evolve-lite/retention/scripts/run_retention.py