106 lines
5.0 KiB
Markdown
106 lines
5.0 KiB
Markdown
---
|
|
name: compact-memory
|
|
description: >
|
|
Audit and compact memory/MEMORY.md by removing superseded, duplicated, overly detailed,
|
|
or ephemeral entries, and merging related items within a subsection.
|
|
Runs interactively by default; use auto mode for unattended execution.
|
|
---
|
|
|
|
# compact-memory
|
|
|
|
Compact `memory/MEMORY.md` when it grows too large or stale. The skill reads `memory/MEMORY.md` plus `USER.md`, `SOUL.md`, and `keep.md` (all three in the workspace root) to detect duplicates and outdated context, but only edits `memory/MEMORY.md`.
|
|
|
|
## When to use
|
|
|
|
- User says "compact memory", "clean up MEMORY.md", "memory audit", or similar.
|
|
- `MEMORY.md` exceeds ~250 lines.
|
|
- There are obvious duplicates between `MEMORY.md` and other memory files.
|
|
- Old project notes, ephemeral debugging details, or superseded facts accumulate.
|
|
|
|
The line threshold is only a proactive trigger. When the user invokes the skill explicitly, run the full audit regardless of line count.
|
|
|
|
## Modes
|
|
|
|
### Interactive mode (default)
|
|
|
|
1. Read `memory/MEMORY.md`, and — for duplicate detection — also `USER.md`, `SOUL.md`, and `keep.md` (all three in the workspace root).
|
|
2. Count total lines (`wc -l memory/MEMORY.md`). If the skill was **not** invoked explicitly by the user, the file is ≤ 250 lines, and there is no obvious staleness, report "nothing to clean up" and stop. When invoked explicitly, always continue to the audit.
|
|
3. **Audit the WHOLE file in a single pass.** Walk every `##` section and every `###` subsection in order, top to bottom, and evaluate every bullet. Do not stop after the first few findings — the proposal in step 5 must cover the entire file at once. Re-running the skill should find nothing left, not "the next batch".
|
|
4. Identify candidates:
|
|
- **superseded** — replaced by newer facts, completed work, or no longer relevant.
|
|
- **detail** — concrete commands, flags, paths, measurements, or **code references** (e.g. `telegram.py:384`, script paths, DB paths) that belong in a skill, in code, or in a `results/` file.
|
|
- **duplicate** — same fact already present in `USER.md`, `SOUL.md`, or `keep.md`.
|
|
- **ephemeral** — one-off debugging, temporary state, resolved incidents, or transient build/run progress (counts, task-failure notes, in-flight status).
|
|
- **stale section** — an entire `##`/`###` section whose contents are all superseded or ephemeral (e.g. a finished project, a one-off task log, transient system state). Propose removing the whole block at once, not bullet by bullet.
|
|
5. Identify merge candidates within the same `###` subsection — related bullets that can be combined into one concise bullet.
|
|
6. Present a single numbered proposal in chat that covers the entire file:
|
|
- list each delete with reason and original text (use `[stale section]` and cite the heading for whole-section removals);
|
|
- list each merge with merged text.
|
|
- Kept items are not listed.
|
|
7. Wait for user approval. Accept commands like:
|
|
- `apply` / `ok` / `yes` — apply all proposed changes.
|
|
- `keep 3, 7, 12` — keep listed items, apply the rest.
|
|
- `delete 2, 5` — delete only listed items.
|
|
- `cancel` — abort.
|
|
8. Apply approved changes to `memory/MEMORY.md`.
|
|
9. Append deleted items to `log/memory-clean.log` with timestamp `YYYY-MM-DD HH:MM` (create the file if it does not exist).
|
|
10. Report summary.
|
|
|
|
### Auto mode
|
|
|
|
Triggered by the user saying "memory-compact auto" or an equivalent with explicit auto intent.
|
|
|
|
1. Perform the same audit as interactive mode.
|
|
2. Before deleting anything, write a full snapshot of `MEMORY.md` to `backup/<YYYY-MM-DD_HHMM>_memory.backup.md`.
|
|
3. Apply changes immediately without waiting for approval.
|
|
4. Print a detailed list of changes.
|
|
5. Append deleted items to `log/memory-clean.log` (create the file if it does not exist).
|
|
|
|
## Rules
|
|
|
|
- Only edit `memory/MEMORY.md`.
|
|
- Do not touch `SOUL.md`, `USER.md`, or `keep.md`.
|
|
- In interactive mode do not create backups of `MEMORY.md`; rely on `log/memory-clean.log` for traceability. Auto mode always writes a full snapshot to `backup/` before deleting.
|
|
- Merge only within the same `###` subsection (never across `##` sections or across different `###` subsections).
|
|
- Preserve active project context, user preferences, and durable infrastructure facts.
|
|
- Be exhaustive: propose every qualifying candidate in one pass, not a handful. The user prunes via `keep`/`delete`, so in interactive mode propose generously and flag borderline items rather than silently keeping them.
|
|
- In **auto mode** only, when in doubt keep it (no user is there to prune); list the borderline items you kept in the report.
|
|
|
|
## Output format
|
|
|
|
Interactive proposal:
|
|
|
|
```
|
|
Found X candidates to change in MEMORY.md:
|
|
|
|
Delete:
|
|
1. [superseded] <text>
|
|
2. [detail] <text>
|
|
3. [stale section] ## <heading> (N bullets) — <reason>
|
|
...
|
|
|
|
Merge:
|
|
5 + 6: <merged text>
|
|
...
|
|
|
|
Commands: apply | keep <numbers> | delete <numbers> | cancel
|
|
```
|
|
|
|
Auto mode report:
|
|
|
|
```
|
|
Memory compact (auto):
|
|
- deleted: X
|
|
- merged: Y
|
|
- unchanged: Z
|
|
|
|
Details:
|
|
...
|
|
```
|
|
|
|
## Example
|
|
|
|
User: `compact memory`
|
|
|
|
Agent: reads files, counts lines, proposes changes, waits for `apply`.
|