Agent Memory Designer

---
name: agent-memory-designer
description: Design an AI agent's memory — the registries, logs and decision files that let it know what it has already done and start smarter each run. Use when asked to give an agent memory, stop an agent redoing finished work, track what an agent has published or produced, build a registry or work log, make lessons persist between sessions, or someone says 'the agent forgot what it did last week'. For the always-loaded decisions, see claude-md-writer. For the folder these files live in, see agent-folder-scaffold.
metadata:
  version: 1.0.0
---

# Agent memory designer

An agent has no memory between sessions unless you build it files. The course's
model case is the blog registry: *"a running log of every post the agent has
published: ID, URL, slug, pillar or cluster, publish date… Without a registry,
the agent has to re-crawl your sitemap on every run and it will still miss the
newest posts. **Treat it as the agent's memory of your site.**"*

Three kinds of memory, three homes. Most "the agent forgot" problems are a file
missing from one of the three.

## Before you start

| Input | Why |
| --- | --- |
| What the agent produces | Each output type earns a registry column set |
| What it keeps re-doing or re-asking | Points at which memory kind is missing |
| What downstream steps need to look up | Registries exist to be read by the next run, not archived |

## Step 1 — Route each remembering job to its home

| Kind | Home | Holds |
| --- | --- | --- |
| **Decisions & rules** | CLAUDE.md | Stable choices, thresholds, voice pointers — "save decisions, not conversations" |
| **Work done** | `output/<name>-registry.md` | Every artifact produced: ID, URL/path, type, date, status |
| **Domain reference** | Helper files next to skills | Voice rules, brand facts, lookup tables — loaded on demand |

The test: *who needs this, when?* Every session → driver. Next run of this
pipeline → registry. Only when a specific job runs → helper file.

## Step 2 — Design the registry as a table the agent reads

Columns from the model case, generalised:

```
| id | slug/path | type (pillar/cluster/...) | date | status | key facts |
```

- **One row per artifact, appended at completion** — writing the row is a
  pipeline step, not a favour.
- Columns exist because a later step reads them: internal linking reads
  pillar/cluster; refresh reads dates; dedup reads slugs. A column nobody reads
  is clutter.
- Plain markdown table in `output/` — greppable, diffable, human-auditable.

## Step 3 — Wire reads and writes into the skills

Memory that isn't in the procedure doesn't exist:

- The producing skill's **last step writes the row** (the bulk pipeline's
  `persona_angle_variant` naming is this same discipline for files).
- Consuming skills' **first steps read it** — the linking skill checks the
  registry before inventing URLs; the refresh skill sorts it by date; the
  planner checks it before proposing a topic that exists.
- CLAUDE.md names the registry path so every session knows where memory lives.

## Step 4 — Feed lessons upward

Registries record *what happened*; the driver records *what was decided about
it*. After a run: results and artifacts → registry rows; a rule learned ("this
category always needs the long variant") → CLAUDE.md, per save-decisions-not-
conversations. That upward feed is why "the next post starts smarter than the
last one."

## Output

```
# Memory design: <agent>

| Remembering job | Kind | Home | Written by | Read by |
| what's published | work log | output/blog-registry.md | publish skill (last step) | linker, refresher, planner |
| voice | reference | voice-rules.md | voice-file-builder | writer (first load) |
| "always draft first" | decision | CLAUDE.md | operator after run | every session |

Registry schema: | id | slug | type | date | status | key facts |
Wiring: every producer writes ✓ · every consumer reads first ✓ · driver names paths ✓
```

## When it breaks

| What you see | What it means | The fix |
| --- | --- | --- |
| Agent redoes finished work | No work registry, or producer never writes it | The row-write becomes the pipeline's last step |
| Agent invents URLs/links | Consumer doesn't read the registry first | Check-registry becomes the consumer's first step |
| Same lesson relearned weekly | Results logged but decisions never promoted | Step 4: the rule moves to CLAUDE.md |
| Registry exists, always stale | Updating it is a manual favour | It is a step in the skill, not a habit of the human |
| Driver bloated with run history | Work log living in CLAUDE.md | Rows to the registry; only decisions stay |
| Registry unreadable at 500 rows | Columns nobody reads accumulated | Keep the columns consumers read; archive closed rows |
| New team member can't find memory | Paths known only by the agent's author | CLAUDE.md names every memory file and its job |

Never bolt memory on after the agent misbehaves twice. Design the three homes at
scaffold time — a registry started on day one costs one row per run; started in
month three it costs an archaeology project.

## Rules

- **Producers write, consumers read, both inside the procedure**, because memory
  that depends on human diligence is memory that is already stale.
- **Rows to registries, decisions to the driver**, because mixing them either
  bloats every session or buries the rules.
- **A column exists because a consumer reads it**, because registries drift into
  clutter one "useful someday" column at a time.
- **Plain markdown tables in output/**, because memory a human cannot audit is
  memory nobody trusts when the agent misbehaves.
- **Day-one design**, because retrofitting memory means reconstructing history
  the agent never recorded.

## Related skills

- **agent-folder-scaffold** — creates the empty registry at setup; this skill
  designs its schema and wiring.
- **claude-md-writer** — the decisions home; save decisions, not conversations.
- **skill-writer** — where the read/write steps get added to procedures.
- **voice-file-builder** — the reference-memory example done fully.