Session Memory (MANDATORY)

The Iron Law

EVERY WORKFLOW MUST:
1. LOAD memory at START (and before key decisions)
2. UPDATE memory at END (and after learnings/decisions)

Brevity Rule: Memory is an index, not a document. Be brief—one line per item.

What “Memory” Actually Is (The Guts)

CC10x memory is a small, stable, permission-free Markdown database used for:

Continuity: survive compaction/session resets
Consistency: avoid contradicting prior decisions
Compounding: promote learnings into reusable patterns
Resumability: recover where a workflow stopped

Memory Surfaces (Types)

Index / Working Memory: .claude/cc10x/v10/activeContext.md
- “What matters right now”: focus, next steps, active decisions, learnings
- Links to durable artifacts (plans/research)
Long-Term Project Memory: .claude/cc10x/v10/patterns.md
- Conventions, architecture decisions, common gotchas, reusable solutions
Progress + Evidence Memory: .claude/cc10x/v10/progress.md
- What’s done/remaining + verification evidence (commands + exit codes)
Artifact Memory (Durable): docs/plans/*, docs/research/*
- The details. Memory files are the index.
Workflow Artifacts (Durable Execution State): .claude/cc10x/v10/workflows/{wf}.json
- Canonical workflow state: task ids, phase status, structured agent results, pending gates
- Used for resume, verifier handoff, and memory finalization
Tasks (Execution State): Claude Code Tasks
- Great for orchestration, but not guaranteed to be the only durable source.
- Tasks remain runtime coordination only; the workflow artifact is the durable orchestration truth.

Task ID Warning: Task IDs may not persist across session restarts unless CLAUDE_CODE_TASK_LIST_ID is configured. NEVER use stored task IDs as the primary source of truth on resume. Store workflow scope + phase + status in task descriptions, then hydrate from TaskList() / TaskGet(). Exception: the router may store [cc10x-internal] memory_task_id in ## References as a transient hint for the active workflow only. Memory Update must remove it when the workflow completes.
Hydration Pattern (recommended for resume):
- Session start: Read progress.md → create fresh tasks for each pending item → set dependencies
- Session end: Sync completed status back to progress.md via Memory Update task
- This makes workflows restartable without relying on old task IDs

Promotion Ladder (“Rises To”)

Information “graduates” to more durable layers:

One-off observation → activeContext.md (Learnings / Recent Changes)
Repeated or reusable → patterns.md (Pattern / Gotcha)
Needs detail → docs/research/* or docs/plans/* + link from activeContext.md
Proven → progress.md (Verification Evidence)

READ Side (Equally Important)

If memory is not loaded: You work blind, repeat mistakes, lose context. If decisions made without checking memory: You contradict prior choices, waste effort.

WRITE Side

If memory is not updated: Next session loses everything learned. If learnings not recorded: Same mistakes will be repeated.

BOTH SIDES ARE NON-NEGOTIABLE.

Permission-Free Operations (CRITICAL)

ALL memory operations are PERMISSION-FREE using the correct tools.

Operation	Tool	Permission
Create memory directory	`Bash(command="mkdir -p .claude/cc10x/v10")`	FREE
Read memory files	`Read(file_path=".claude/cc10x/v10/activeContext.md")`	FREE
Create NEW memory file	`Write(file_path="...", content="...")`	FREE (file doesn't exist)
Update EXISTING memory	`Edit(file_path="...", old_string="...", new_string="...")`	FREE
Save plan/design files	`Write(file_path="docs/plans/...", content="...")`	FREE

CRITICAL: Write vs Edit

Tool	Use For	Asks Permission?
Write	Creating NEW files	NO (if file doesn't exist)
Write	Overwriting existing files	YES - asks "Do you want to overwrite?"
Edit	Updating existing files	NO - always permission-free

RULE: Use Write for NEW files, Edit for UPDATES.

CRITICAL: Use Read Tool, NOT Bash(cat)

NEVER use Bash compound commands (mkdir && cat) - they ASK PERMISSION. ALWAYS use Read tool for reading files - it's PERMISSION-FREE.

# WRONG (asks permission - compound Bash command)
mkdir -p .claude/cc10x/v10 && cat .claude/cc10x/v10/activeContext.md

# RIGHT (permission-free - separate tools)
Bash(command="mkdir -p .claude/cc10x/v10")
Read(file_path=".claude/cc10x/v10/activeContext.md")

NEVER use heredoc writes (cat > file << 'EOF') - they ASK PERMISSION. Use Write for NEW files, Edit for EXISTING files.

# WRONG (asks permission - heredoc)
cat > .claude/cc10x/v10/activeContext.md << 'EOF'
content here
EOF

# RIGHT for NEW files (permission-free)
Write(file_path=".claude/cc10x/v10/activeContext.md", content="content here")

# RIGHT for EXISTING files (permission-free)
Edit(file_path=".claude/cc10x/v10/activeContext.md",
     old_string="# Active Context",
     new_string="# Active Context\n\n[new content]")

Why This Matters

"My memory resets between sessions. The Memory Bank is my ONLY link to previous work."

Without memory persistence:

Context lost on conversation compaction
Patterns relearned from scratch
Decisions forgotten and remade differently
Progress tracking lost
Same mistakes repeated

Memory is the difference between an expert who learns and a novice who forgets.

Memory Structure

.claude/
└── cc10x/
    ├── activeContext.md   # Current focus + learnings + decisions (MOST IMPORTANT)
    ├── patterns.md        # Project patterns, conventions, gotchas
    └── progress.md        # What works, what's left, verification evidence

Who Reads/Writes Memory (Ownership)

Read

Router (always): loads all 3 files before workflow selection and before resuming Tasks.
WRITE agents (component-builder, bug-investigator, planner): load memory files at task start via this skill.
READ-ONLY agents (code-reviewer, silent-failure-hunter, integration-verifier): read memory files directly at task start via their own Memory First section. They do NOT have Edit tool — they output ### Memory Notes for the router to persist.

Write

Router/workflow finalizer: the ONLY writer of .claude/cc10x/v10/{activeContext,patterns,progress}.md.
WRITE agents: do NOT edit memory markdown files directly. Emit structured MEMORY_NOTES in the final Router Contract.
READ-ONLY agents: output ### Memory Notes (For Workflow-Final Persistence) section. Router persists them into the workflow artifact immediately; Memory Update writes the markdown files at workflow finalization.
Router-owned cleanup: when Memory Update finishes, remove the matching [cc10x-internal] memory_task_id line for that workflow from activeContext.md ## References. Do not leave stale task IDs behind.

Concurrency Rule (Parallel Phases)

BUILD runs code-reviewer ∥ silent-failure-hunter in parallel. To avoid conflicting edits:

Agents do not edit memory markdown during parallel phases.
Router persists structured notes into the workflow artifact mid-phase and writes markdown only in Memory Update.

Pre-Compaction Memory Safety

Update memory IMMEDIATELY when you notice:

Extended debugging (5+ cycles)
Long planning discussions
Multi-file refactoring
30+ tool calls in session

Checkpoint Pattern:

Edit(file_path=".claude/cc10x/v10/activeContext.md",
     old_string="## Current Focus",
     new_string="## Current Focus\n\n[Updated focus + key decisions]")
Read(file_path=".claude/cc10x/v10/activeContext.md")  # Verify

Rule: When in doubt, update memory NOW. Better duplicate entries than lost context.

File Purposes

Use these purposes to decide where information belongs:

activeContext.md: current state + pointers (what we’re doing, why, what’s next)
patterns.md: reusable knowledge (conventions, architecture, gotchas, “do it this way here”). ## User Standards entries are non-negotiable — always follow them regardless of other context.
progress.md: execution tracking + hard evidence (tests/build/run commands, exit codes, scenario tables)

Memory File Contract (Never Break)

CC10x memory files are not "notes" - they are contracts used as Edit anchors.

Hard rules:

Do not rename the top-level headers (# Active Context, # Project Patterns, # Progress Tracking).
Do not rename section headers (e.g., ## Current Focus, ## Last Updated).
Only add content inside existing sections (append lists/rows).
- Exception — Snapshot sections: ## Recent Changes (activeContext) and ## Tasks (progress) are replaced (not appended) at workflow end by the Memory Update task. Mid-workflow agents still append normally.
- If a canonical section from this template is missing (e.g., ## References, ## Decisions, ## Learnings), add it by inserting it just above ## Last Updated.
After every Edit(...), Read back the file and confirm the intended change exists.

If an Edit does not apply cleanly:

STOP (do not guess).
Re-read the file and re-apply using a correct, exact old_string anchor.

activeContext.md (Read/Write EVERY session)

Current state of work - ALWAYS check this first:

# Active Context
<!-- CC10X: Do not rename headings. Used as Edit anchors. -->

## Current Focus
[Active work]

## Recent Changes  <!-- SNAPSHOT: replaced at workflow end -->
- [Change] - [file:line]
- [DEBUG-N]: {what was tried} → {result}  <!-- Use for debug workflow -->

## Next Steps
1. [Step]

## Decisions
- [Decision]: [Choice] - [Why]

## Learnings
- [Insight]

## References
- Plan: `docs/plans/...` (or N/A)
- Design: `docs/plans/...` (or N/A)
- Research: `docs/research/...` → [insight]
- [cc10x-internal] memory_task_id: [task id] wf:[workflow id]  <!-- transient only; Memory Update removes this line -->

## Blockers
- [None]

## Session Settings
# AUTO_PROCEED: false  (set to true to enable JUST_GO mode — auto-defaults all non-REVERT gates)

## Last Updated
[timestamp]

Merged sections:

## Active Decisions + ## Learnings This Session → ## Decisions + ## Learnings
## Plan Reference + ## Design Reference + ## Research References → ## References
Removed: ## User Preferences Discovered (goes in Learnings)

patterns.md (Accumulates over time)

Project-specific knowledge that persists:

# Project Patterns
<!-- CC10X MEMORY CONTRACT: Do not rename headings. Used as Edit anchors. -->

## User Standards
- [Your non-negotiable coding principles — agents MUST follow these on every workflow]

## Architecture Patterns
- [Pattern]: [How this project implements it]

## Code Conventions
- [Convention]: [Example]

## File Structure
- [File type]: [Where it goes, naming convention]

## Testing Patterns
- [Test type]: [How to write, where to put]

## Common Gotchas
- [Gotcha]: [How to avoid / solution]
- [Gotcha from research]: [Solution] (Source: docs/research/YYYY-MM-DD-topic.md)

## API Patterns
- [Endpoint pattern]: [Convention used]

## Error Handling
- [Error type]: [How project handles it]

## Dependencies
- [Dependency]: [Why used, how configured]

## Project SKILL_HINTS
- [cc10x:skill-name]  <!-- auto-populated: detected [tech signal] -->

progress.md (Tracks completion)

What's done, what's not:

# Progress Tracking
<!-- CC10X: Do not rename headings. Used as Edit anchors. -->

## Current Workflow
[PLAN | BUILD | REVIEW | DEBUG]

## Tasks  <!-- SNAPSHOT: replaced at workflow end -->
- [ ] Task 1
- [x] Task 2 - evidence

## Completed
- [x] Item - evidence

## Verification
- `command` → exit 0 (X/X)

## Last Updated
[timestamp]

Merged sections:

## Active Workflow Tasks + ## In Progress + ## Remaining → ## Tasks
## Verification Evidence table → ## Verification bullets
Removed: ## Known Issues, ## Evolution of Decisions, ## Implementation Results (rarely used, clutters template)

Stable Anchors (ONLY use these)

Anchor	File	Stability
`## Recent Changes`	activeContext	GUARANTEED
`## Learnings`	activeContext	GUARANTEED
`## References`	activeContext	GUARANTEED
`## Last Updated`	all files	GUARANTEED (fallback)
`## Common Gotchas`	patterns	GUARANTEED
`## Project SKILL_HINTS`	patterns	GUARANTEED
`## Completed`	progress	GUARANTEED
`## Verification`	progress	GUARANTEED

NEVER use as anchors:

Table headers (| Col | Col |)
Checkbox text (- [ ] specific text)
Optional sections that may not exist

Read-Edit-Verify (MANDATORY)

Every memory edit MUST follow this exact sequence:

Step 1: READ

Read(file_path=".claude/cc10x/v10/activeContext.md")

Step 2: VERIFY ANCHOR

# Check if intended anchor exists in the content you just read
# If "## References" not found → use "## Last Updated" as fallback

Step 3: EDIT

Edit(file_path=".claude/cc10x/v10/activeContext.md",
     old_string="## Recent Changes",
     new_string="## Recent Changes\n- [New entry]\n")

Step 4: VERIFY

Read(file_path=".claude/cc10x/v10/activeContext.md")
# Confirm your change appears. If not → STOP and retry.

Why this works:

Step 1 shows you what's actually there
Step 2 prevents "anchor not found" errors
Step 3 uses verified anchor
Step 4 catches silent failures

READ Triggers - When to Load Memory

ALWAYS Read (Non-Negotiable)

Trigger	Action	Why
Session start	Load ALL 3 files	Fresh context needed
Workflow start	Load ALL 3 files	Before BUILD/REVIEW/DEBUG/PLAN
Continuation session	Load ALL 3 files	Resume from where we left
User says "continue"	Load activeContext.md	Get current state

Read BEFORE These Actions

Before This Action	Read This File	Why
Making architectural decision	patterns.md	Check existing patterns
Choosing implementation approach	patterns.md + activeContext.md	Align with conventions + prior decisions
Starting to build something	progress.md	Check if already done
Debugging an error	activeContext.md + patterns.md	May have seen before + known gotchas
Planning next steps	progress.md	Know what's remaining
Reviewing code	patterns.md	Apply project conventions
Making any decision	activeContext.md (Decisions)	Check prior decisions

Read WHEN You Notice

Situation	Action	Why
User references "what we did"	Load activeContext.md	Get history
You're about to repeat work	Load progress.md	Check if done
You're unsure of convention	Load patterns.md	Project standards
Error seems familiar	Load patterns.md (Common Gotchas)	Known issues
Decision feels arbitrary	Load activeContext.md	Prior reasoning

File Selection Matrix

What do I need?              → Which file?
─────────────────────────────────────────
Current state / focus        → activeContext.md
Prior decisions + reasoning  → activeContext.md (Decisions)
What we learned              → activeContext.md (Learnings)
Project conventions          → patterns.md
How to structure code        → patterns.md
Common gotchas to avoid      → patterns.md
What's done / remaining      → progress.md
Verification evidence        → progress.md
Prior research on topic      → activeContext.md (References) → docs/research/

Decision Integration

Before ANY decision, ask:

Did we decide this before? → Check activeContext.md Decisions section
Is there a project pattern? → Check patterns.md
Did we learn something relevant? → Check activeContext.md Learnings

If memory has relevant info:

Follow prior decision (or document why changing)
Apply project pattern
Use learned insight

If memory is empty/irrelevant:

Make decision
RECORD it in activeContext.md for next time

Mandatory Operations

At Workflow START (REQUIRED)

Use separate tool calls (PERMISSION-FREE):

# Step 1: Create directory (single Bash command - permission-free)
Bash(command="mkdir -p .claude/cc10x/v10")

# Step 2: Load ALL 3 memory files using Read tool (permission-free)
Read(file_path=".claude/cc10x/v10/activeContext.md")
Read(file_path=".claude/cc10x/v10/patterns.md")
Read(file_path=".claude/cc10x/v10/progress.md")

# Step 3: Git Context - Understand project state (RECOMMENDED)
Bash(command="git status")                 # Current working state
Bash(command="git ls-files | head -50")    # Project file structure
Bash(command="git log --oneline -10")      # Recent commits

NEVER use this (asks permission):

# WRONG - compound command asks permission
mkdir -p .claude/cc10x/v10 && cat .claude/cc10x/v10/activeContext.md

If file doesn't exist: Read tool returns an error - that's fine, means starting fresh.

At Workflow END (REQUIRED)

MUST update before completing ANY workflow. Use Edit tool (NO permission prompt).

# First, read existing content
Read(file_path=".claude/cc10x/v10/activeContext.md")

# Prefer small, targeted edits. Avoid rewriting whole files.

# Example A: Add a bullet to Recent Changes (prepend)
Edit(file_path=".claude/cc10x/v10/activeContext.md",
     old_string="## Recent Changes",
     new_string="## Recent Changes\n- [YYYY-MM-DD] [What changed] - [file:line]\n")

# Example B: Add a decision (stable anchor)
Edit(file_path=".claude/cc10x/v10/activeContext.md",
     old_string="## Decisions",
     new_string="## Decisions\n- [Decision]: [Choice] - [Why]")

# Example C: Add verification evidence to progress.md (stable anchor)
Read(file_path=".claude/cc10x/v10/progress.md")
Edit(file_path=".claude/cc10x/v10/progress.md",
     old_string="## Verification",
     new_string="## Verification\n- `[cmd]` → exit 0 (X/X)")

# VERIFY (do not skip)
Read(file_path=".claude/cc10x/v10/activeContext.md")
Read(file_path=".claude/cc10x/v10/progress.md")

WHY Edit not Write? Write asks "Do you want to overwrite?" for existing files. Edit is always permission-free.

When Learning Patterns (APPEND)

Read existing patterns.md, then append using Edit:

# Read existing content
Read(file_path=".claude/cc10x/v10/patterns.md")

# Append under an existing section header (preferred: stable anchor)
Edit(file_path=".claude/cc10x/v10/patterns.md",
     old_string="## Common Gotchas",
     new_string="## Common Gotchas\n- [Gotcha]: [Solution / how to avoid]\n")

When Completing Tasks (UPDATE)

# Read progress.md, then record completion with evidence
Read(file_path=".claude/cc10x/v10/progress.md")

# Option A (preferred): append a completed line under "## Completed"
Edit(file_path=".claude/cc10x/v10/progress.md",
     old_string="## Completed",
     new_string="## Completed\n- [x] [What was completed] - [evidence: command → exit 0]\n")

# Option B: flip an existing checkbox if one exists (more brittle)
Edit(file_path=".claude/cc10x/v10/progress.md",
     old_string="- [ ] [Task being completed]",
     new_string="- [x] [Task being completed] - [verification evidence]")

Integration with Agents

ALL agents MUST:

START: Load memory files before any work
DURING: Note learnings and decisions
END: Update memory files with new context

If an agent cannot safely update memory (e.g., no Edit tool available):

Include "memory-worthy" notes in the agent output (decisions, learnings, verification evidence).
The main assistant (router) must persist those notes into .claude/cc10x/v10/*.md using Edit(...) + Read-back verification.

Failure to update memory = incomplete work.

Dynamic Skill Discovery (WRITE agents only)

After Memory First read, check patterns.md ## Project SKILL_HINTS:

Invoke found skills: Skill(skill="[each listed entry]") — skip gracefully if not installed.
Persist new tech: If task involves domain tech not yet listed, append:
```
Edit(old_string="## Project SKILL_HINTS", new_string="## Project SKILL_HINTS\n- [full-skill-id]  \n")
```
Use the EXACT skill ID as-is — e.g., mongodb-agent-skills:mongodb-schema-design, cc10x:research, react-best-practices. Do NOT add or change namespaces.

Red Flags - STOP IMMEDIATELY

If you catch yourself:

Starting work WITHOUT loading memory
Making decisions WITHOUT checking Decisions section
Completing work WITHOUT updating memory
Saying "I'll remember" instead of writing to memory

STOP. Load/update memory FIRST.

Rationalization Prevention

Excuse	Reality
"I know what we decided"	Check the Decisions section.
"Small task, no need"	Small tasks have context too. Always update.
"I'll remember"	You won't. Conversation compacts. Write it down.
"Memory is optional"	Memory is MANDATORY. No exceptions.

Verification Checklist

Memory loaded at workflow start
Decisions checked before making new ones
Learnings documented in activeContext.md
Progress updated in progress.md

Cannot check all boxes? Memory cycle incomplete.

session-memory