Memory Compounding

---
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.