Cog-Sync/.claude/commands/housekeeping.md

Use this skill to perform memory housekeeping. Trigger if the user says "housekeeping", "clean up memory", "prune memory", "archive old data", or similar maintenance requests.

1. Garbage Collect Memory

Review and archive stale data per CLAUDE.md glacier rules. All glacier files must have YAML frontmatter.

Observations — archive by primary tag:

• If any observations.md has >50 entries, group oldest entries by primary tag and move to memory/glacier/{domain}/observations-{tag}.md
• If memory/cog-meta/self-observations.md has >50 entries, group by primary tag → memory/glacier/cog-meta/observations-{tag}.md

Other files — standard rules:

• If any action-items.md has >10 completed items, move to memory/glacier/{domain}/action-items-done.md
• Apply same logic for all domains listed in memory/domains.yml
• If memory/cog-meta/improvements.md has >10 implemented items, move to memory/glacier/cog-meta/improvements-done-{YYYY}.md

2. Prune Hot Memory (rule-based)

Keep ALL hot-memory.md files under 50 lines. Relevance judgment (promote/demote) is /reflect's job — you apply structural rules:

Files to check: Read memory/domains.yml to discover all active domains. Check hot-memory.md for each domain, plus the cross-domain memory/hot-memory.md.

Pruning priority (trim in this order):

1. Resolved items — anything with strikethrough, "DONE", "RESOLVED"
2. Past events — entries about dates that have already occurred
3. SSOT violations — same fact in hot-memory AND the canonical file (entities, action-items, etc.). Keep in canonical file, replace hot-memory copy with [[link]] or remove
4. Stale entries — items not referenced in 14+ days
5. Low-signal entries — FYI items with no action or deadline

Where trimmed entries go:

• Entries with lasting value → append to domain's observations.md
• Entries that are purely historical → let them go
• Never silently delete — always move or note removal in debrief

3. Surface Opportunities & Accountability

Review all action-items.md files across every domain:

• Stale items (open >2 weeks): list with age and suggested next action
• Dormant domains: if any domain has 0 new observations in >4 weeks, flag
• Health escalation: items open >6 months get flagged with urgency label
• Birthday prep: if any birthday in entities.md is <2 weeks away, pull interests and suggest ideas

Be direct. Don't just report — recommend specific actions.

4. Rebuild Glacier Index

Scan all memory/glacier/**/*.md files. Extract YAML frontmatter. Write results to memory/glacier/index.md:

# Glacier Index
<!-- Auto-generated by housekeeping. Do not edit. -->
<!-- Last updated: YYYY-MM-DD -->

| File | Domain | Type | Tags | Date Range | Entries | Summary |
|------|--------|------|------|------------|---------|---------|

5. Link Audit (discover missing links)

For each non-glacier memory file:

1. Entity mentions: Scan for names matching ### <Name> headers in entities.md — add [[links]] if missing
2. Cross-domain references: If a file mentions a topic from another domain, add a cross-domain link
3. Action item references: If an observation references a task, link it

Only add links where the reference is substantive.

5b. Entity Registry Format Enforcement

Scan all entities.md files for registry format compliance:

1. 3-line max: Any ### entry with >3 content lines should be compressed. If the entry has an associated detail file (→ [[link]]), compress to: name/relationship, pipe-separated key facts, status+link. If no detail file exists and entry is >5 lines, flag as a promotion candidate (suggest creating a thread file).
2. Glacier candidates: Entries with status: inactive or last: date >6 months ago → move to glacier/{domain}/entities-inactive.md (leave a stub with archived comment).
3. Missing metadata: Flag entries missing status: or last: fields.

5c. Temporal Fact Maintenance

Scan all entities.md files for (until YYYY-MM) markers with past dates:

1. If the line has no strikethrough, add it
2. If already struck through, move to a ## Historical subsection at the bottom of that entity's block (create the subsection if absent)
3. Report moved facts in the debrief

6. Rebuild Link Index

Scan all memory files (excluding glacier/) for [[wiki-links]]. For each link, record: target → source.

Rewrite memory/link-index.md:

# Memory Link Index
<!-- Auto-generated by housekeeping. Do not edit. -->
<!-- Last updated: YYYY-MM-DD -->

| Target | Linked from |
|--------|-------------|
| `personal/entities` | `personal/observations`, `personal/hot-memory` |

Rules:

• Only include targets with at least one inbound link
• Combine multiple sources per target on one row (comma-separated)
• Exclude glacier files from both source and target

7. Write Briefing Bridge

Write key findings to memory/cog-meta/briefing-bridge.md so foresight can pick them up. Overwrite the file each run.

SSOT rule: Every line in the bridge must include a [[source]] link to its canonical file. The bridge summarizes and links — it NEVER introduces original facts.

# Briefing Bridge
<!-- Auto-generated by housekeeping. Consumed by foresight. -->
<!-- Last updated: YYYY-MM-DD -->

## Stale Items (>2 weeks)
- <item> — <age> — suggested action: <action>
- **Compression rule**: Items stale >4 weeks — group by domain as a single line

## Birthday Prep
- <name> birthday in <N> days — interests: <from entities> — gift ideas: <suggestions>

## Dormant Domains
- <domain> — last activity: <date> — recommendation: <shelf/reactivate/shut down>

## Health Escalation
- <item> — open <N> months — urgency: <high/medium>

Only include sections that have content. Empty sections should be omitted.

8. L0 Header Maintenance

Check all active memory files for missing <!-- L0: ... --> headers. If a file is missing its L0:

• Read the file content, write a one-line summary (max 80 chars)
• Add on the line after the # Title

L0 headers are the first tier of the retrieval protocol — they let any skill scan what a file contains before deciding to read it.

9. Rebuild Domain Indexes

Regenerate INDEX.md for each domain directory. These files power the memory router — the system prompt only shows a light domain table; the model reads INDEX.md on demand to find specific files.

For each domain (scan memory/ for directories, skip glacier/):

1. List all .md files in the domain (exclude INDEX.md, hot-memory.md, and empty files)
2. Extract the L0 summary from each file (same logic as step 8)
3. Count total files
4. Write memory/{domain}/INDEX.md:

# {Domain} Index
<!-- L0: {domain summary} — {N} files -->
<!-- Auto-generated by housekeeping. Do not edit. -->
<!-- Last updated: YYYY-MM-DD -->

- **{filename}** — {L0 summary}
- **{filename}** — {L0 summary}
...

• Sort entries alphabetically by filename
• Domain summary: use the label from memory/domains.yml for the matching domain
• If a file has no L0, list it as just **{filename}** (no summary)

10. Compose Debrief

Summarize everything done:

• What was archived/pruned
• Upcoming events flagged
• Action items surfaced
• Links added

Keep it concise but informative.