| name | memory-compounding |
| description | Review and sharpen persistent memory so it compounds instead of accumulating. Use when pruning pi-hermes-memory entries, doing monthly memory hygiene, or when the same lesson has been recorded multiple times. |
Memory Compounding
Memory is an index, not a transcript. Without review it accumulates stale entries that mislead future work. This skill is the discipline for keeping memory sharp, not just large.
When to use
- Monthly memory hygiene (AGENTS.md: "review both, prune stale entries").
- You notice the same gotcha recorded 3+ times.
- A memory entry contradicts the current code (trust the code).
- After a non-trivial debug/build cycle that produced a reusable learning.
The 5-outcome review rubric
For each entry in ~/.pi/agent/pi-hermes-memory/MEMORY.md, USER.md, failures.md, and the SQLite memories table (via memory_search), apply exactly one outcome:
| Outcome | When | Action |
|---|
| Keep | Accurate + useful | Leave as-is |
| Update | Correct but incomplete | Add the missing detail |
| Consolidate | Same lesson appears multiple times | Merge into one entry, remove duplicates |
| Replace | Outdated or superseded by current code | Replace with the current truth |
| Delete | No longer applies (framework changed, code removed) | Remove |
The promotion rule
When the same gotcha appears 3+ times in failures.md or across memory entries, promote it: write a dedicated reference file or a new skill section. A lesson that keeps recurring is a pattern, not a one-off — it earns a permanent home.
Solution docs (durable cross-project learnings)
After any non-trivial debug/build cycle, evaluate whether to write a solution doc to docs/solutions/:
- Write if: the problem took 3+ hypotheses to solve, OR the bug pattern appears in 3+ files, OR the solution contradicts a common assumption.
- Skip if: the fix was mechanical (typo, import error, one-line change).
Solution doc format:
# [Problem Title]
Category: debugging | architecture | testing | workflow | conventions
Tags: [comma-separated]
Date: YYYY-MM-DD
## Problem
[symptoms, not just the error message]
## What Didn't Work
[failed hypotheses and why]
## Solution
[what worked — with code example]
## Why
[the underlying principle]
## Prevention
[how to prevent this class of problem]
Ensure AGENTS.md or CLAUDE.md points to docs/solutions/ so agents can find it. This closes the loop: every solved problem makes the next one easier.
Don't
- Don't persist: whole diffs, verbose logs, celebratory narration, "looked correct" without evidence, duplicate notes, raw secrets/PII.
- Don't delete a memory just because it's old — delete it because it's wrong now.
- Don't skip the review when memory contradicts the code — trust the code, fix the memory.
