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)

1. Index / Working Memory:

   .claude/cc10x/activeContext.md

   • “What matters right now”: focus, next steps, active decisions, learnings
   • Links to durable artifacts (plans/research)
2. Long-Term Project Memory:

   .claude/cc10x/patterns.md

   • Conventions, architecture decisions, common gotchas, reusable solutions
3. Progress + Evidence Memory:

   .claude/cc10x/progress.md

   • What’s done/remaining + verification evidence (commands + exit codes)
4. Artifact Memory (Durable):

   docs/plans/*

   ,

   docs/research/*

   • The details. Memory files are the index.
5. Tasks (Execution State): Claude Code Tasks
   • Great for orchestration, but not guaranteed to be the only durable source.
   • Mirror key task subjects/status into

     progress.md

     for backup/resume.

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.

Bash(command="mkdir -p .claude/cc10x")

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

Write(file_path="...", content="...")

Edit(file_path="...", old_string="...", new_string="...")

Write(file_path="docs/plans/...", content="...")

CRITICAL: Write vs Edit

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

CRITICAL: Use Read Tool, NOT Bash(cat)

NEVER use Bash compound commands (

mkdir && cat

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

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

NEVER use heredoc writes (

cat > file << 'EOF'

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

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

# RIGHT for EXISTING files (permission-free)
Edit(file_path=".claude/cc10x/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): receive memory summary in prompt, do NOT load this skill.

Write

• WRITE agents: update memory directly at task end using

  Edit(...)

  +

  Read(...)

  verify pattern.
• READ-ONLY agents: output

  ### Memory Notes (For Workflow-Final Persistence)

  section. The task-enforced "CC10X Memory Update" task ensures these are persisted.

Concurrency Rule (Parallel Phases)

BUILD runs

code-reviewer ∥ silent-failure-hunter

• Prefer no memory edits during parallel phases.
• If you must persist something mid-parallel, only the main assistant should do it, and only after both parallel tasks complete.

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/activeContext.md",
     old_string="## Current Focus",
     new_string="## Current Focus\n\n[Updated focus + key decisions]")
Read(file_path=".claude/cc10x/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]

## Blockers
- [None]

## 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)

## Recent Changes

## Learnings

## References

## Last Updated

## Common Gotchas

## Project SKILL_HINTS

## Completed

## Verification

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/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/activeContext.md",
     old_string="## Recent Changes",
     new_string="## Recent Changes\n- [New entry]\n")

Step 4: VERIFY

Read(file_path=".claude/cc10x/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)

Read BEFORE These Actions

Read WHEN You Notice

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:

1. Did we decide this before? → Check activeContext.md Decisions section
2. Is there a project pattern? → Check patterns.md
3. 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")

# Step 2: Load ALL 3 memory files using Read tool (permission-free)
Read(file_path=".claude/cc10x/activeContext.md")
Read(file_path=".claude/cc10x/patterns.md")
Read(file_path=".claude/cc10x/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 && cat .claude/cc10x/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/activeContext.md")

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

# Example A: Add a bullet to Recent Changes (prepend)
Edit(file_path=".claude/cc10x/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/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/progress.md")
Edit(file_path=".claude/cc10x/progress.md",
     old_string="## Verification",
     new_string="## Verification\n- `[cmd]` → exit 0 (X/X)")

# VERIFY (do not skip)
Read(file_path=".claude/cc10x/activeContext.md")
Read(file_path=".claude/cc10x/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/patterns.md")

# Append under an existing section header (preferred: stable anchor)
Edit(file_path=".claude/cc10x/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/progress.md")

# Option A (preferred): append a completed line under "## Completed"
Edit(file_path=".claude/cc10x/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/progress.md",
     old_string="- [ ] [Task being completed]",
     new_string="- [x] [Task being completed] - [verification evidence]")

Integration with Agents

ALL agents MUST:

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

If an agent cannot safely update memory (e.g., no

Edit

• Include "memory-worthy" notes in the agent output (decisions, learnings, verification evidence).
• The main assistant (router) must persist those notes into

  .claude/cc10x/*.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- cc10x:[skill]  <!-- [tech signal] -->\n")

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

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.