---
name: vault-janitor
description: >-
  Weekly and monthly vault hygiene for personal knowledge bases. Indexes notes,
  flags duplicates, stale projects, and archive candidates, writes a janitor
  report, and executes only explicitly approved moves. Use when the user says
  vault janitor, weekly review, compress vault, archive candidates, or
  /vault-janitor.
---

# Vault Janitor

Memory consolidation for a knowledge vault. The vault should get cleaner over time, not noisier.

## Hard rules

1. **Never delete** notes. Archive to a graveyard folder with an `archived_reason`.
2. **Never move or merge** without explicit user approval in the same session (for example `approve 1,3,5`).
3. **Read an index first**: do not scan the entire vault. Prefer a machine-built index plus targeted file reads.
4. **Protect link hubs**: notes with many inbound links are not archive candidates unless the user insists.
5. **Draft writes** go in a report or staging folder unless the user approves direct writes.

## Suggested vault layers

| Layer | Typical path |
|-------|--------------|
| Inbox | a capture folder for unfiled notes |
| Working memory | active projects / efforts |
| Long-term memory | reference / atlas notes |
| Graveyard | archived notes with reason metadata |
| Reports | dated janitor reports |

Adapt names to the vault you are cleaning. The pattern matters more than the folder labels.

## Step 1: Index

Build or refresh an index of titles, paths, frontmatter status, link counts, and hygiene flags. Review flags before deep reads.

## Step 2: Weekly mode (default)

1. Refresh the index.
2. Inspect flags and a small set of candidates only.
3. For semantic checks, read titles plus short excerpts for:
   - near-duplicate title clusters
   - meeting or log notes ready to compress
   - projects whose status no longer matches activity
4. Write a dated report with numbered suggested actions and an approval checklist.
5. Stop. Wait for approval before mutating files.

### Report sections (required)

```markdown
## Summary counts
## Duplicate / merge candidates (with survivor)
## Stale / abandoned projects
## Decisions that supersede older notes
## Compression candidates
## Archive candidates (orphan / unreferenced / expired)
## Inbox triage
## Suggested actions
## Approval checklist
```

## Step 3: Monthly compression

Run the weekly pass, then:

- Pick a few topic clusters from recent activity.
- Draft enduring reference notes that supersede scattered sources.
- Refresh one-paragraph current-state summaries on active project pages.

## Step 4: Execute approvals

When the user approves numbered actions:

1. Execute only the listed actions.
2. On archive: move to graveyard, set status and reason, update any index lists.
3. On merge: consolidate into the survivor, link superseded sources, archive leftovers.
4. Re-index after mutations and summarise what changed.

## Quality bar

Propose specific, evidenced actions. Prefer compression and clearer retrieval over collecting more notes. Leave link hubs alone unless asked.