Memory And Handoff

Memory & Handoff

Reference Files

Read only what's needed:

• references/memory-model-and-ownership.md — memory surfaces, ownership, promotion, workflow markers; load when deciding which surface holds a piece of state or who may write it
• references/memory-operations.md — permission-free operations, router-only persistence, edit patterns; load when actually reading or writing .cc10x/ files
• references/memory-file-contracts.md — required headings, stable anchors, templates, auto-heal rules; load when creating a memory file or healing a malformed one
• references/context-budget-and-checkpointing.md — context-budget rules, warning signs, checkpoint triggers; load when context is getting heavy or before a compaction/checkpoint decision

Mode: SESSION MEMORY

Memory is an index, not a transcript. Distill decisions, learnings, references, and verification evidence into durable, reusable notes.

Memory Surfaces

Ownership

• Router loads and auto-heals memory files before routing or resume
• WRITE agents read memory but do NOT edit .cc10x/*.md (sole carve-out: bug-investigator's [DEBUG-N] lines)
• WRITE agents emit structured MEMORY_NOTES in their Router Contract
• READ-ONLY agents emit ### Memory Notes (For Workflow-Final Persistence)
• Router-owned memory-finalize task is the only final writer of memory markdown files
• Router-owned markers ([DEBUG-RESET: wf:{...}], [cc10x-internal] memory_task_id) are read and respected; agents do not invent replacements

Load (MANDATORY at workflow start)

Read all three: activeContext.md, patterns.md, progress.md.

Re-read before: architectural decisions (patterns.md + activeContext.md ## Decisions), implementation choices (patterns.md + activeContext.md), debugging (all three), planning next steps (progress.md + activeContext.md), claiming completion (progress.md + plan/design/research refs), user says "continue" (all three).

Persist

Emit MEMORY_NOTES in Router Contract:

MEMORY_NOTES:
  learnings: ["Key causal insight"]
  patterns: ["Reusable gotcha or convention"]
  verification: ["`npm test` -> exit 0"]
  deferred: ["Non-blocking follow-up or risk"]

Keep each entry one line — memory reloads every session; each extra line is a recurring tax. Prefer stable nouns over temporary wording. Put verification truth in verification, not prose. Put non-blocking work in deferred, not ad-hoc tasks.

Persist only memory-worthy items: decisions that change direction, learnings that prevent mistakes, verification evidence with commands and exit truth, deferred non-blocking issues, plan/design/research references, clarified user standards.

Do not persist: whole diffs, verbose logs, celebratory narration, "looked correct" without evidence, duplicate notes, raw secrets/PII in outward artifacts.

Secret Redaction (OUTWARD artifacts only)

Before router persists cc10x-authored content into outward artifacts (docs/plans/*, docs/research/*, design docs, persisted memory notes): redact pasted tokens, API keys, connection-strings, credentials, PII. Replace with <redacted:secret> (PII: <redacted:pii>). Keep surrounding constraint intact. When unsure, redact. Does NOT apply to internal machine-owned .cc10x/ orchestration state — that stays verbatim for resume/dedupe keys.

Compaction KEEP / SUMMARIZE / DROP Rubric

Persist user PROHIBITIONS verbatim into workflow artifact's intent field as soon as stated — compaction may fire before router's normal persist.

Project Skill Hints

After loading memory, check patterns.md ## Project SKILL_HINTS. Invoke listed skills when relevant and installed. Treat missing skills as non-fatal. Do not invent skill IDs. Do not edit ## Project SKILL_HINTS directly — surface recommendations in planner output or memory notes.

Mode: HANDOFF PACKAGE

A portable, human-readable export for when the next reader is NOT this cc10x session — a coworker, a different tool, or a clean session with no cc10x router.

cc10x's own resume is structural (.cc10x/ + router rehydrates). The handoff package is the bridge OUT to a reader who cannot read .cc10x/ orchestration state.

Rules

1. Write to OS temp dir, never into the repo — a repo-committed handoff becomes a stale doc the next reader mistakes for current truth. HANDOFF="${TMPDIR:-/tmp}/handoff-$(date +%Y%m%d-%H%M%S).md". Print the absolute path.
2. Reference artifacts by path/URL, never paste contents. The next reader has the repo. They need a map, not a copy. Prefer behavioral descriptions over file:line where code may still drift.
3. Redact secrets and PII before writing. Redact per ### Secret Redaction above.

Contents

The "suggested skills/tools" pointer is load-bearing: tell the next agent how to continue. If cc10x is present: invoke cc10x-router. If not: name domain skills and point at plan/research docs.

Knowledge Compounding Loop

Memory is not just for context survival — it's for system self-improvement. After every BUILD or DEBUG cycle, structured learnings should compound into reusable knowledge. Memory files (activeContext.md, patterns.md, progress.md) hold session-scoped context; durable, structured learnings that survive across projects and sessions go to docs/solutions/.

The Loop

1. Capture — During workflow-finalize, the router writes structured learnings from agent MEMORY_NOTES into activeContext.md ## Learnings and patterns.md ## Common Gotchas; learnings that cross the solution-doc threshold (below) are written to docs/solutions/.
2. Ground — Before starting new work, agents read patterns.md, activeContext.md, and docs/solutions/ to avoid repeating solved problems.
3. Consolidate — When the same gotcha appears 3+ times in patterns.md, promote it to a solution doc under docs/solutions/.
4. Refresh — Periodically audit learnings and solution docs with the five-outcome model (below).
5. Discover — Ensure CLAUDE.md or AGENTS.md points to docs/solutions/ so agents can find it.

When to Write a Solution Doc

After any non-trivial debug or build cycle, the router (during memory-finalize) evaluates whether to write a solution doc:

• Write if: the problem took 3+ hypotheses (debug attempts) to solve, OR the same defect pattern appears in 3+ files, OR the solution contradicts a documented assumption in patterns.md
• Skip if: the fix was mechanical (typo, import error, one-line change)
• Offer neutrally if: the lesson is one sentence (mention in memory notes instead)

Compounding Outcomes

When reviewing prior learnings during memory-finalize (or auditing solution docs), apply one of five outcomes:

Why this matters: Without consolidation, memory accumulates stale entries that mislead future work. The compounding loop ensures memory gets sharper over time, not just larger.

Solution Doc Format

# [Problem Title]
Category: [debugging | architecture | testing | workflow | conventions]
Tags: [comma-separated]
Date: YYYY-MM-DD

## Problem
[What went wrong — symptoms, not just the error message]

## What Didn't Work
[Hypotheses that failed and why]

## Solution
[What actually worked — with code example if applicable]

## Why
[Why the solution works — the underlying principle]

## Prevention
[How to prevent this class of problem in the future]