Note -- Persistent Working Memory

Notes are the cross-cutting memory layer. They persist across sessions, survive context resets, and -- for global memory -- are automatically injected into every worker prompt.

Core principle: If a future session needs this to avoid a mistake, capture it. If not, skip it.

Mental Model

Two-tier system mapped to the v2 memory architecture:

• Global Memory = pinned message in a channel. Every agent sees it, every time. Hard constraints that, if violated, produce wrong code. Workers cannot ask clarifying questions -- they need these upfront. Stored via maestro memory-write --global / maestro memory-write.
• Feature Memory = searchable thread history scoped to the active feature. Insights, learnings, and soft observations accumulated during implementation. Available on demand, pruned periodically. Stored via maestro memory-write / maestro memory-write (defaults to active feature).
• Promoted Memory = feature-scoped insights promoted to global after proving valuable. Use maestro memory-promote / maestro memory-promote to elevate.

When to Capture

Always:

• Decisions that constrain future work (API choice, library version, architecture direction)
• Constraints discovered mid-implementation (rate limits, API quirks, platform bugs)
• User decisions on blockers (the "why" behind the choice, so no one re-asks)
• Cross-feature dependencies ("feature X depends on auth refactor from feature Y")

Never:

• Status updates ("started task 3") -- use maestro task-done / maestro task-block
• Things already in spec or plan -- don't duplicate
• Temporary debugging notes ("tried X, didn't work") -- ephemeral, discard

Decision heuristic: "Will a future session need this to avoid a mistake?" Yes = capture. No = skip.

Global Memory vs Feature Memory

Promoting to Global: If a feature memory note keeps causing mistakes across sessions, promote it with maestro memory-promote / maestro memory-promote. If a global note no longer applies, delete it with maestro memory-delete.

Good Notes vs Bad Notes

See reference/note-patterns.md for more examples across decisions, constraints, discoveries, and dependencies.

Arguments

$ARGUMENTS

Execution

Step 1: Ensure Memory System Ready

Check that maestro is initialized (maestro status --json or maestro status). If .maestro/ does not exist: "Run maestro init first."

Step 2: Parse and Execute

Add (default or --global):

1. Determine scope: --global writes to .maestro/memory/, default writes to active feature memory
2. Generate a key from the content (kebab-case, descriptive, 2-4 words)
3. Call maestro memory-write --key <key> "<content>" (add --global for global scope)
4. Display confirmation with the key and scope

Show (--show):

1. Call maestro memory-list to show all memory entries
2. If no entries: "No memory entries found. Use maestro:note <content> to start."

Prune (--prune):

1. Call maestro memory-list for the active feature
2. Review each entry for staleness
3. Remove stale entries with maestro memory-delete --key <key>
4. Keep global memory intact
5. Show what was removed and what was kept
6. If uncertain about an item, ask the user

Clear (--clear <scope>):

1. Parse scope: global, feature, or all
2. If clearing global: confirm with user first
3. Delete all entries in the specified scope
4. Confirm deletion

Note Lifecycle

Create --> Review (session start) --> Update (constraint changes) --> Promote/Archive/Delete (resolved)

Anti-Patterns

Section Contracts

Relationship to Other Commands

• maestro init -- Initialize maestro for the project
• maestro feature-create -- Create a feature to work on
• maestro skill maestro:new-feature -- Create feature with spec and plan
• maestro skill maestro:implement -- Execute implementation (reads global memory at start)
• maestro skill maestro:review -- Verify implementation correctness
• maestro status --json -- Check progress across all features
• maestro skill maestro:note -- You are here. Capture decisions and context to persistent memory

Global memory is automatically loaded by maestro:implement at execution start and injected into worker prompts. Feature memory accumulates insights from both manual notes and auto-capture during implementation. Use --prune after each feature completion to keep memory relevant. Use maestro memory-promote to elevate high-value feature insights to global scope.