Cy Workflow Memory

Workflow Memory

Maintain the workflow memory files provided by the caller.

Required Inputs

• Workflow memory directory path.
• Shared workflow memory file path.
• Current task memory file path.
• Optional caller signal indicating whether either file must be compacted before proceeding.

Workflow

1. Load the memory state before editing code.

• Read the shared workflow memory file and the current task memory file before making any code change.
• Treat these files as mandatory context for the run, not optional notes.
• If the caller marks either file for compaction, read references/memory-guidelines.md and compact that file before proceeding with implementation.

2. Keep memory current while the task runs.

• Update the current task memory whenever the objective changes, a non-obvious decision is made, an important learning appears, or an error changes the plan.
• Promote only durable cross-task context into the shared workflow memory.
• Keep task-local execution details in the current task memory file.

3. Close out the run cleanly.

• Update memory before any completion claim, handoff, or commit.
• Record only facts that help the next run start faster and with fewer mistakes.
• Re-read references/memory-guidelines.md before compacting if the file has grown noisy or repetitive.

Critical Rules

• Do not invent history, decisions, or status that did not happen.
• Do not copy large code blocks, stack traces, or task specs into memory files.
• Do not duplicate facts that are obvious from the repository, git diff, task file, or PRD documents.
• Do not read unrelated task memory files unless the shared workflow memory or the caller explicitly points to them.
• Keep shared memory durable and cross-task. Keep task memory local and operational.

Promotion Decision Test

Before promoting an item from task memory to shared workflow memory, ask:

1. Will another task need this information to avoid a mistake or rediscovery? 2. Is this fact durable across multiple runs, not just the current execution? 3. Is this information NOT already obvious from the PRD, techspec, task files, or the repository itself?

All three must be "yes" to promote. If any is "no," the item stays in task memory.

Examples that belong in shared workflow memory:

• A discovered constraint that affects multiple tasks (e.g., "the API rate limits to 100 req/s, batch operations must respect this")
• A cross-cutting architectural decision made during implementation (e.g., "chose channel-based coordination over mutex for the pipeline")
• An open risk that future tasks must account for (e.g., "migration depends on schema v3 which is not yet deployed to staging")

Examples that stay in task memory:

• Files touched during this task's implementation
• Debugging steps taken to resolve a task-specific error
• The current task's objective and acceptance criteria snapshot
• A workaround applied only to the current task's scope

Compaction Rules

When the caller flags a memory file for compaction, apply these rules inline. Read references/memory-guidelines.md for full detail, but these rules are sufficient for most compaction passes:

1. If both files need compaction, compact the shared workflow memory first, then compact the task memory. The shared file sets the cross-task context that the task file should not duplicate. 2. Preserve: current state, durable decisions, reusable learnings, open risks, and handoff notes. 3. Remove: repetition, stale notes, long command transcripts, and facts already derivable from the repository, PRD, or task files. 4. Rewrite retained items as short factual bullets. Do not preserve narrative logs or chronological play-by-play. 5. Keep the default section headings from the template intact. Remove empty sections only if they are truly unused.

When To Read the Reference

Read references/memory-guidelines.md when any of these apply:

• the caller requests compaction and the inline rules above do not cover the situation
• it is unclear what belongs in shared memory versus task memory
• the current memory file has drifted into noisy notes or redundant detail

Error Handling

• If any caller-provided memory path is missing, stop and report the mismatch instead of guessing another path.
• If memory content conflicts with the repository or task specification, trust the repository and task documents, then correct the memory file.
• If compaction would remove active risks, decisions, or handoff context, keep those items and remove lower-value repetition first.

Workflow Memory Guidelines

Use these rules to keep Compozy workflow memory useful across repeated PRD task runs.

File Roles

Shared workflow memory: MEMORY.md

Use the shared workflow memory for context that should survive across multiple tasks and multiple runs.

Keep:

• current workflow state that affects more than one task
• durable technical or product decisions
• reusable learnings that will matter again
• open risks or handoff notes that change future execution

Avoid:

• step-by-step scratch notes
• large code excerpts
• facts that are already explicit in _prd.md, _techspec.md, _tasks.md, or the repo itself

Current task memory: memory/<task filename>

Use the task memory for context that is specific to the current task.

Keep:

• the current objective snapshot
• important task-local decisions
• local learnings and corrections
• touched files or surfaces worth remembering next run
• ready-for-next-run notes

Avoid:

• cross-task summaries that belong in MEMORY.md
• repeated restatements of the task spec
• low-signal command transcripts

Promotion Rules

Promote an item from task memory into shared workflow memory only when it is:

• durable across runs
• useful to another task
• likely to prevent repeated mistakes or rediscovery

Leave information in task memory when it is:

• operational only for the current task
• temporary
• too detailed for workflow-wide reuse

Compaction Rules

When compaction is required:

• preserve current state, durable decisions, reusable learnings, open risks, and handoffs
• remove repetition, stale notes, long transcripts, and derivable facts
• rewrite for clarity, not for completeness
• prefer short factual bullets over narrative logs

Default Section Boundaries

MEMORY.md

• ## Current State
• ## Shared Decisions
• ## Shared Learnings
• ## Open Risks
• ## Handoffs

memory/<task filename>

• ## Objective Snapshot
• ## Important Decisions
• ## Learnings
• ## Files / Surfaces
• ## Errors / Corrections
• ## Ready for Next Run