Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .agents/memory/INBOX.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Lessons inbox

Raw notes from finished work. Append only; never read this file before a task. The
`review-memory` skill reads it, promotes what repeats into [LESSONS.md](LESSONS.md), drops the
rest, and empties it.
`review-memory` skill reads it weekly, promotes what repeats into [LESSONS.md](LESSONS.md),
keeps a lone note for one more review (marked `Seen:`), and drops the rest.

One note per PR that hit friction, four lines:

Expand Down
28 changes: 20 additions & 8 deletions .claude/skills/review-memory/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: review-memory
description: Curate agent memory - read the lessons inbox and the curated lessons file, promote what repeats, prune what is stale, open a memory-only PR and merge it. Use monthly, when the inbox has notes, when a lessons section is over its cap, or when asked to review, consolidate or dream over memory.
description: Curate agent memory - read the lessons inbox and the curated lessons file, promote what repeats, prune what is stale, open a memory-only PR and merge it. Use weekly, when the inbox has notes, when a lessons section is over its cap, or when asked to review, consolidate or dream over memory.
---

# Review memory
Expand All @@ -13,11 +13,20 @@ PR a human merges.
## 1. Read

```bash
git fetch origin && git switch -c "memory/$(date +%Y-%m-%d)" origin/main
git fetch origin && git switch --detach origin/main
cat .agents/memory/INBOX.md .agents/memory/LESSONS.md
git log --oneline --since="3 months ago" -- .agents/memory
gh pr list --state open --search "chore(memory): review in:title"
```

Stop without a branch or PR, and report why, when either holds:

- the inbox has no notes under its header and no section is over its cap;
- an earlier memory review PR is still open. Reviewing again would stack a second PR on
the same inbox.

Otherwise branch: `git switch -c "memory/$(date +%Y-%m-%d)"`.

## 2. Decide per inbox note

- **Promote to a skill section** when the same rule appears in two or more notes from
Expand All @@ -26,9 +35,12 @@ git log --oneline --since="3 months ago" -- .agents/memory
- **Promote to General** only when it applies to every skill. Expect this to be rare.
- **Mark for a mechanism** when the rule could be a lint rule or a test. Keep the entry
and add "mechanism: <what>" to it; file a `type:chore` issue via the `file-issue` skill
so a human can schedule it. Once the mechanism lands, the entry is deleted on the next review.
- **Drop** a note that has sat alone for two reviews, or whose code path no longer exists.
A dropped note leaves no trace; the inbox is emptied at the end regardless.
so a human can schedule it; skip its interview, the notes are the spec. Once the
mechanism lands, the entry is deleted on the next review.
- **Keep** a note that matches nothing yet and has no `Seen:` line. Add
`Seen: <today>` as its fifth line so the next review can pair it with a later note.
- **Drop** a note that already carries a `Seen:` line and still matches nothing, or whose
code path no longer exists. A dropped note leaves no trace.

## 3. Prune the curated file

Expand All @@ -44,12 +56,12 @@ the cap, drop the oldest entry with the weakest evidence and say so in the PR.

## 4. Ship

Empty the inbox down to its header. Then:
Empty the inbox down to its header plus the notes kept in step 2. Then:

```bash
git add .agents/memory && git commit -m "chore(memory): review $(date +%Y-%m-%d)"
git push -u origin HEAD
gh pr create --title "chore(memory): review $(date +%Y-%m-%d)" --body "<promoted: n, dropped: n, pruned: n, mechanisms filed: #...>"
gh pr create --title "chore(memory): review $(date +%Y-%m-%d)" --body "<promoted: n, kept: n, dropped: n, pruned: n, mechanisms filed: #...>"
gh pr view --json files -q '.files[].path' | grep -v '^\.agents/memory/' && exit 1 # memory only
gh pr merge --squash --delete-branch "memory/$(date +%Y-%m-%d)"
```
Expand All @@ -61,6 +73,6 @@ file check prints anything, stop and leave the PR for a human.

```
Memory review: <date> PR: #N (merged | left open: <why>)
Promoted: n Dropped: n Pruned: n Mechanisms filed: <issues or none>
Promoted: n Kept: n Dropped: n Pruned: n Mechanisms filed: <issues or none>
Sections over cap: <names or none>
```
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,6 @@ Load the skill before starting the matching task. They live in `.claude/skills/`
| Writing or editing anything an Appduct user reads: READMEs, `docs/`, website, the shipped skill, CLI help, error messages | `writing-user-docs` |
| Adding, amending or reviewing an entry in `CHANGELOG.md` | `writing-changelog` |
| Cutting a release | `cut-release` |
| Curating agent memory (monthly, or when the inbox has notes) | `review-memory` |
| Curating agent memory (weekly, or when the inbox has notes) | `review-memory` |
| Taking an issue from `status:ready` to a reviewed, tested PR | `work-issue` (orchestrator) |
| Driving an Appduct-enabled app as a user of Appduct | `appduct` (in `skills/`) |
Loading