working-memory

Files (5)

• plugin.json · .claude-plugin/
• README.md
• SKILL.md
• CLAUDE-snippet.md · assets/
• WORKING.template.md · assets/

SKILL.md (first lines)

# Working Memory

## Why

A long session runs out of context and gets **compacted** — the transcript is squeezed into a summary, and the details drop out: decisions, edge-cases, what was already tried and failed. Work quality falls, and the next session starts blind — the user feels "didn't we already do this?".

Root cause: the important state lived **only in the conversation** — volatile memory that dies on compaction and never crosses into a new session. The fix is to stage that state onto a medium that survives: a `WORKING.md` file in the repo.

## The three levels

| Level | Medium | Lifespan |
|---|---|---|
| **Short-term** | session context | hours — dies on compaction |
| **Mid-term** | `WORKING.md` in the repo | days–weeks — while a stage runs |
| **Long-term** | the assistant's memory (e.g. Claude Code memory files) | months — survives everything |

This skill owns the mid-term level and the bridge up to long-term. Flow: **context → WORKING.md → (distill at stage end) → long-term memory.** WORKING.md is a *staging area* for memory, not a parallel store.

## The file

`WORKING.md` lives at the repo root (a working thread in a subfolder may have its own, e.g. `docs/research/WORKING.md`). Four sections:

- **Current stage** — one or two lines: where we are right now.
- **Decision log** — datestamped entries (absolute dates), newest-relevant on top: what was decided/done and *why*.
- **Tried / didn't work** — dead ends, so they aren't re-attempted.
- **Next** — open tails, TODOs, the obvious next step.

Copy `assets/WORKING.template.md` as the starting point.

## Operations

### Setup (once per project)
When a project has no WORKING.md and the work is non-trivial: copy the template to the repo root, fill **Current stage** from what's known, and add a pointer to the project's `CLAUDE.md` so it's read on every future session (snippet in `assets/CLAUDE-snippet.md`). If there is no `CLAUDE.md`, create one with just that pointer.

### Start / resume (every session)
At the start of work on a project, **read WORKING.md before acting** — it restores the stage state that context loss erased. Check subfolders for thread-specific WORKING.md too. If asked to "resume", this is the anchor.

### Checkpoint (often — the core habit)
After any meaningful decision or step — and **before a planned `/compact`, and whenever the user says "checkpoint / save state"** — append to WORKING.md: update **Current stage**, add 1–3 lines to the **Decision log**, record any new dead end, refresh **Next**. Do it *during* the work, not at session end — compaction can strike first. Keep entries terse; the quality bar is that a fresh session could resume from them.

### Consolidate (at stage end)
When a stage closes: **distill** the settled conclusions from WORKING.md up into long-term assistant memory, then **reset** WORKING.md to a clean slate for the next stage. Decide what rises with the belonging test below. This is the "sleep" step — without it, WORKING.md grows into an unreadable log and nothing reaches durable memory.

## The belonging test

For any line, ask: **"When this stage ends and WORKING.md is reset — should this survive?"**
- **Yes** → it's a settled conclusion (architecture, an infra fact, a hard-won gotcha, who-knows-what). → long-term memory.
- **No** → it's operational state (progress, an open tail, a TODO). → stays in WORKING.md, dies with the stage.

One event splits across levels: the *investigation* stays as a decision-log entry; the *lesson* rises to memory. Example — log: "spent a day chasing 87% 5xx, turned out to be bots on missing paths"; memory: "the catch-all handler must return 404 for unknown routes, not 500".

## Rules

- **Don't duplicate what code or git already show.** WORKING.md holds decisions and reasons, not a changelog you could `git log`.
- **Procedural knowledge** (how to deploy, how to test) belongs in `CLAUDE.md` or `docs/`, not WORKING.md — it's not stage state.
- **Absolute dates.** Resolve "tomorrow / next week" to a real date, so the log stays readable later.
- **Don't wait for stage end to write.** Mid-term memory only helps if it's written before context is lost.

From ikotelkin/claude-skills, MIT.

More from ikotelkin/claude-skills