---
name: memory-compounding
description: "(Meta-level skill: spans all tasks, **must not be bound to any domain**.) Move memory out of the conversation into a readable/writable memory/ directory — **before starting any non-trivial task, run `memory_check.py --brief` to read memory out**, write as you go during the task, stop to verify and tidy, and get compounding smarter through the loop rather than through prompts. Use for lessons capture across conversations and tasks, long-running projects, and 'do you still remember what you learned last time' scenarios. Not for one-off Q&A (when there is nothing to carry across sessions)."
---

> Original skill · commissioned by the user · English edition, 2026-11-12

# Memory Compounding

**Thesis**: prompts are one-shot; **a loop executes continuously**. The gap is not whether you can ask — it is **whether, a day later, you still remember what you learned yesterday and the day before**.

**Why it must be externalized**: memory kept inside a conversation rots — attention gets split, patterns get buried, and **old notes keep being applied confidently on wrong premises**.
A conversation has a lifespan; a directory does not.

> Data supplied by the user (**not measured by this skill, reproduction is not guaranteed**): after externalizing memory into a directory and running this loop,
> errors on a single task dropped by 97%, acceptance got 30% faster, and the person went back to looking at the product instead of staring at prompts.

## 0. First solve "how will it ever be triggered" (otherwise everything below is void)

> ⚠️ **A meta-level skill may not be bound to a domain (rule established after a past review)**: both this skill and `flexible-handling` are **meta-level** — they apply to **all** tasks,
> therefore they **must not be deeply bound to any domain**. Domain content may appear only as "illustrations" inside `references/`, and **may not be a premise of a rule**.

⚠️ **Measured in a past run**: this skill went **11 hours without being used once** after it was built,
including later sessions where I myself never read it — **because it committed the very mistake it recorded: "a rule written only in a document does not exist"**.
"Read before you start" was a **rule with no attach point**, the same disease as the earlier gate-3 case.

**Three attach points, ranked by reliability:**

| Attach point | Why it is reliable |
|---|---|
| ① **Put it in the `description`** | The skill description **enters the context every turn** — that is the only position that is "guaranteed to be read", so the trigger conditions must live here |
| ② **Bind it to an inevitable step in the global layer** | Write it as the first item of `$CODEX_HOME/AGENTS.md`, or make it a session-start hook — **every session is guaranteed to read it**, no matter what the task is |
| ③ **Make it a command** | `memory_check.py --brief` reduces "read four files" to "run one command" — it lowers friction, but still relies on discipline |

**Criterion**: **if a session never reads `memory/`, that round is pure consumption and earns no compounding.**

⛔ **Negative example (measured, do not repeat)**: attach point ② was once bound to the "question 0 at start of work" of **one specific production-line skill** (which one is recorded in `memory/decisions.md`). Three sessions later
(a skill download / a system troubleshooting / a Q&A) **read it zero times** — they simply never took that path. **Binding to a single production line = covering one class of task only**,
which is a downgrade for a meta-level skill.

```powershell
python $CODEX_HOME/skills/memory-compounding/scripts/memory_check.py --dir $CODEX_HOME/memory --brief
```
⚠️ **Measured again (three card-video productions in one evening)**: later the same day, three consecutive video sessions
(each 1–2 hours, multiple rounds of rework, a dozen or so tool calls) **also read `memory/` zero times**.
Those tasks were exactly "long task + repeated rework" — theoretically the class that should read memory most — and they still did not.

**What the two measurements together show**: attach point ① (write it into the description) only enters the context when the skill is matched;
attach point ③ (make it a command) depends on discipline — **neither is sufficient to make a meta-level skill actually fire**.
The only untried one is attach point ②: put "read before you start" into a position that **every session is guaranteed to read**, such as `$CODEX_HOME/AGENTS.md`.

> **To do (needs the user's consent, because that is the user's own global instruction)**: add a section at the top of `$CODEX_HOME/AGENTS.md`
> called "first step of work", turning "before starting any non-trivial task, run `memory_check.py --brief`" into a mandatory instruction.
> ⚠️ Do not add it to the start-of-work checklist of one production-line skill again — that was tried and covered only that class of task (see the negative example above).


## 1. Where memory lives: `$CODEX_HOME/memory/`

**A readable/writable directory, not one big file** — a big file replays "attention split" exactly as it was.

```
memory/
├── index.md        entry: read it first, know what exists and where
├── progress.md     progress: what is being worked on, how far, where it is stuck
├── lessons.md      lessons: pitfalls hit + status (observing / verified / retired)
├── decisions.md    decisions: what was decided, why, how to roll back
├── glossary.md     glossary: what XX means in this project / in this system
└── archive/        expired content (moved, not deleted)
```

**The directory may grow**: split into files when entries pile up, split a file when it exceeds one screen.
**Structure serves "can actually be read", not tidiness.**

## 2. The three-step loop (this is all of it)

| Step | When | What to do |
|---|---|---|
| ① **Write as you go** | During the task | When something is worth keeping, **write it immediately** — do not wait to "summarise at the end" (you forget by the end) |
| ② **Stop and tidy** | End of task / end of day | **Verify / tidy / complete**: does it still hold, does it conflict, should it be merged |
| ③ **Read before you start** | Start of a new task | Read `index.md` first, then the relevant entries as needed — **do not start from impression** |

**Step ② is the watershed**: writing without tidying turns the directory into a dump — as rotten as memory inside a conversation, only relocated.

> ⚠️ **Mandatory action before appending an entry** (hit in a past run): first confirm the file **ends with a newline**.
> Otherwise `Add-Content` **glues the new entry onto the end of the previous line**, merging two records into one line —
> the health check misses it (that line still starts with a valid format), and you only find out at the next tidy-up.

## 3. Four anti-rot rules (each one checkable)

| Rule | Why |
|---|---|
| **Carry a date** | A note with no date gives you no way to judge whether it still holds today |
| **Carry a source** | Which task / which conversation it came from — **a conclusion whose origin you cannot state may not enter memory** |
| **Carry a status** | `observing` / `verified` / `retired` — stops a guess that appeared once from being used as a rule |
| **Archive regularly** | Expired, contradictory or overturned entries move into `archive/`, **never deleted** (keep "why it was overturned") |

## 4. Fix gate (**mandatory before acting**)

> ⚠️ **The same disease, third recurrence**: §0 of this skill has recorded twice that "a rule written only in a document does not exist",
> and the third recurrence happened **somewhere else** — "fix only the spot in front of you, do not check what it pulls on" **was already written
> in another meta-level skill's anti-pattern table**, yet it was committed **4 times in a row inside one delivery project**, where the root cause of each round
> was **the previous round's fix**.
> **So the fix this time is not to write the rule again, but to attach it to a point.**

Any "fix one spot" action must, before acting, write down two sentences; **if you cannot write them, you may not act**:

1. **"What will this fix make worse?"** — unable to answer = you have not seen the coupling it pulls on
2. **"How will you measure it?"** — attach a **testable criterion** to that sentence (not "take a look")

After the fix, **run both criteria together**: ① the reported symptom (proof it is fixed) ② the reverse self-check (proof nothing else broke).

**Forbidden**: running only ① and declaring completion.

## 5. Distinguishability of criteria ("looks like" is not a criterion)

**An acceptance metric must be able to distinguish "pass" from "fail".**

Measured: for "is the motion smooth or jittery", the **mean frame-to-frame difference** could not tell them apart — smooth and jittery were the same order of magnitude (0.45 vs 0.88);
switching to the **coefficient of variation** (dispersion / shape of distribution) separated them immediately: **0.04 vs 0.80, a 20× difference**.

**Action**: after writing a criterion, ask yourself **"if it were broken, what would this number become?"**
- Cannot state an order-of-magnitude difference → the criterion is invalid; switch to a dispersion / distribution-shape metric
- **Totals, means and counts are the three metric types that commit this error most often**

## 6. The health check must cover "the input", not only "your own processing"

The acceptance checklist may not list only "each step I performed"; it must include check items on **the input artifact itself**.

Measured: the input footage carried a fixed overlay badge and **no step from start to delivery ever checked it**, until the user found it after delivery.
**What I checked was "did my processing go wrong"; what I never checked was "is what came in clean".**

**Action**: split the acceptance checklist into two columns — ① **input check** ② **processing check** — both with testable criteria.

## 7. Self-imposed constraints must be audited first

**Constraints you add yourself (that the user never asked for) are a high-yield breeding ground for defects.**

Measured: to make two versions of an artifact "frame-for-frame equal in length" — something **I added myself for "a nicer comparison"**, never requested by the user —
each segment had to be given its own rate change, which produced a new defect the user could feel immediately.

**Action**: during tidy-up, ask of every self-added constraint **"is this a requirement or my preference?"**
- Preference → write it into the decision log and mark it "revocable at any time"
- Requirement → keep it, but it must also pass the **fix gate** (§4)

## 8. Three questions when tidying

1. **Does this still hold?** (has the premise changed)
2. **Does it conflict with a new entry?** (contradictions must be resolved on the spot; two entries may not coexist)
3. **Is anything mergeable?** (the same thing written three times = should be one entry)

## 9. Relationship to existing mechanisms (do not mix them up)

- Each skill's `LESSONS.md` is a **layered ledger** (each skill accumulates its own lessons); `memory/` is **the cross-skill layer**.
  A lesson that **belongs to one skill** → write it in that skill's `LESSONS.md`; **cross-skill** → write it here.
- `project-retro` owns "how to run a retrospective on a project"; this skill owns "**where** retrospective output goes and **how to find it again** next time".
- `skill-asset-management` owns the audit of skills themselves; this skill owns the audit of **knowledge**.

## 10. Self-check

```powershell
python scripts/memory_check.py --dir "$CODEX_HOME/memory"
```

Checks for entries with no date / no source / missing status / long unchanged, and outputs a **tidy-up list**.