| name | notes-decision-tree |
| description | WHAT: Choose between the three notes-ish tools - `scratchpad` (turn-to-turn free-form carry-over), `todo` (a typed multi-step plan), and `memory` (durable cross-session facts) - by scope and content kind. WHEN: You are about to jot something down to remember and are unsure which tool holds it. DO-NOT: Persist ephemeral task state into `memory`, use `scratchpad` for a multi-step plan, or hand-edit any of their backing files. |
Notes decision tree
Pi has three places to write things down, and they are easy to confuse. scratchpad is free-form carry-over for the
current line of work. todo is a typed, status-tracked plan for a multi-step task. memory is durable storage that
survives session shutdown and new projects. Picking wrong means either losing context you needed (too ephemeral) or
polluting future sessions with stale junk (too durable). This skill is the decision tree.
When to use this skill
Use it the moment you are about to record something to remember and more than one of these tools could plausibly hold
it. The two axes that decide it:
- Scope - how long must this outlive the moment? This turn / this session vs. this multi-step task vs. every future
session.
- Content kind - free-form prose, a tracked step with a status, or a durable fact about the user / project / world.
Decision tree
- Is it a step in a multi-step task you will work through? ->
todo. Anything with "first do X, then Y, then
verify Z", where you need a status (pending / in_progress / review / completed / blocked / cancelled) and
a guardrail against claiming done while items are open.
- Is it a durable fact that should survive this session and apply to future ones? ->
memory. A user preference, a
correction you were given, a project decision, a pointer to an external system. See
memory-first for the four types and, critically, what NOT to save.
- Otherwise - free-form context you keep rediscovering this turn or this session? ->
scratchpad. File paths, the
test / lint command, a decision you made, a subagent handle, the user's answer to a clarifying question.
When two seem to fit, prefer the less durable tool. A misplaced memory pollutes every future session; a misplaced
scratchpad note just goes quiet when the work ends.
The three tools
scratchpad - turn-to-turn, free-form, branch-local
Unstructured working notes auto-injected every turn (as an ephemeral <system-reminder>) under ## Working Notes.
Survives /compact and is branch-aware (/fork, /tree show the right notes), but does NOT persist past the session
or leak across branches. Actions: append (with optional heading), update, remove, list, clear.
Reach for it when:
- You keep re-deriving the same path, command, or fact and want it in front of you next turn.
- You need to park a subagent handle or a background job id so you can re-attach after compaction.
- You captured the user's answer to a clarifying question and the next few turns need it.
todo - the typed multi-step plan
A status-tracked plan, also auto-injected every turn, with hard invariants (at most one in_progress, at most one
review) and a completion-claim guardrail. Branch-aware and compaction-resilient. See
plan-first for when to plan and the block-vs-cancel distinction.
Reach for it when:
- The task has more than one or two steps and you want it to survive compaction as a checklist.
- You need to track progress and not lose the thread of what is done vs. open.
memory - durable, cross-session
Single markdown files with name / description / type frontmatter (user / feedback / project / reference),
plus a session-scoped note layer. Indices are injected every turn; bodies fetched on demand. Survives session
shutdown, compaction, and new projects (global types) or returns when you re-enter the workspace (project types).
Reach for it when:
- The fact should still matter next week or in a different session: a stable preference, a blessed approach, a project
decision, an external-system pointer.
- Read
memory-first before saving - most utterances are transient task context, not
durable knowledge, and code / git history / CLAUDE.md must NOT be copied into memory.
Quick reference
| You want to remember... | Tool | Scope |
|---|
| The lint command you keep re-typing | scratchpad | This session, free-form |
| A background job id / subagent handle to re-attach | scratchpad | This session, free-form |
| The user's answer to a clarifying question (for now) | scratchpad | This session, free-form |
| The 5 steps of the refactor you are working through | todo | This task, typed + tracked |
| Which step is in progress vs. done | todo | This task, typed + tracked |
| "User prefers terse replies" / a correction you got | memory | Cross-session (feedback) |
| "We're ripping out auth middleware for compliance" | memory | This project, durable |
| "Pipeline bugs live in Linear project INGEST" | memory | This project (reference) |
Context that must survive /compact but not the session | memory | note (session-scoped) |
Common pitfalls
- Persisting ephemeral task state into
memory. Use scratchpad / todo - they are branch-aware and do not
outlive the work. Saving "the failing test is X" as a durable memory rots immediately.
- Using
scratchpad for a real plan. No status tracking, no done-guardrail. A multi-step task is a todo.
- Copying code / git history / CLAUDE.md into
memory. It lives in the repo - read it. Memory copies go stale the
moment the source changes.
- Hand-editing the backing files.
MEMORY.md is one-line-per-memory; scratchpad and todo reconstruct from
branch entries. Let the tools manage their own state.
- Defaulting to durable. When unsure between session and cross-session, prefer the session tool - a stray global
memory pollutes every future session.
Related docs
scratchpad.md - free-form working-notes tool reference.todo.md - typed plan tool reference (states, transitions, guardrail).memory.md - durable memory tool reference.memory-first - when to save durable memory and what NOT to save.plan-first - when to plan multi-step work with todo.
