---

name: session-memory description: "Internal skill. Use cc10x-router for all development tasks." allowed-tools: Read, Write, Edit, Bash

Session Memory (MANDATORY)

The Iron Law

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

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.

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) - they ASK PERMISSION. ALWAYS use Read tool for reading files - it's PERMISSION-FREE.

Copy# 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') - they ASK PERMISSION. Use Write for NEW files, Edit for EXISTING files.

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

Copy.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

Memory Efficiency (Token-Aware Loading)

Quick Index Pattern (OPTIONAL)

When a memory file exceeds ~200 lines, add a Quick Index at the top for faster scanning:

Copy## Quick Index
| Section | Summary | Lines |
|---------|---------|-------|
| Current Focus | [1-line summary of active work] | 5-15 |
| Recent Changes | [count] changes recorded | 20-50 |
| Active Decisions | [count] decisions | 10-30 |
| Learnings | [count] insights | 15-25 |
| Blockers | [None / count active] | 5-10 |

---
[Rest of file content below...]

When to add Quick Index:

• File exceeds 200 lines
• Multiple distinct sections with significant content
• Frequent partial reads needed

When NOT needed:

• File under 200 lines (most projects)
• Simple, focused content
• File rarely referenced

Selective Loading

For large memory files (200+ lines), agents MAY load selectively:

Copy# Step 1: Load first 50 lines (Quick Index + Current Focus)
Read(file_path=".claude/cc10x/activeContext.md", limit=50)

# Step 2: Decide which sections are relevant to current task
# - Building new feature → Load "Active Decisions", "Patterns"
# - Debugging → Load "Learnings", "Recent Changes"
# - Continuing work → Load "Current Focus", "Next Steps"

# Step 3: Load specific sections using offset/limit
Read(file_path=".claude/cc10x/activeContext.md", offset=100, limit=50)

Selective Loading Decision Matrix:

DEFAULT: For files under 200 lines, load the entire file. Selective loading adds complexity—only use when needed.

Pruning Guidelines

Keep memory files trim for token efficiency:

When to prune (any file exceeding 200 lines):

Pruning Rules:

1. Recent Changes: Keep last 10 entries. Older changes move to git history.
2. Active Decisions: Archive decisions older than 2 workflows if no longer referenced.
3. Learnings: Promote repeated learnings to patterns.md, then remove from activeContext.
4. Completed Tasks: Summarize completed workflows into a single line after verification.

Pruning is a READ operation first:

Copy# Step 1: Read and assess size
Read(file_path=".claude/cc10x/activeContext.md")

# Step 2: If > 200 lines, identify prunable content
# Step 3: Move reusable content to appropriate file
# Step 4: Edit to remove old content

DO NOT prune:

• Active decisions still being referenced
• Recent learnings (< 2 sessions old)
• Unresolved blockers
• Current focus content

Pre-Compaction Memory Safety

Context Length Awareness

Conversations auto-compact when they get too long. If memory isn't updated before compaction, context is lost forever.

The Risk:

CopyLong session → Auto-compact → Memory NOT updated → Context LOST

Proactive Update Triggers

Update memory IMMEDIATELY when you notice:

• Extended debugging sessions (5+ error cycles)
• Long planning discussions
• Multi-file refactoring
• Any session with 30+ tool calls
• User says "we've been at this a while"

The Rule

When in doubt, update memory NOW.

Don't wait for workflow end. It's better to have duplicate entries than lost context.

Checkpoint Pattern

During long sessions, periodically checkpoint:

Copy# After significant progress, even mid-task:
Edit(file_path=".claude/cc10x/activeContext.md",
     old_string="## Current Focus",
     new_string="## Current Focus

[Updated focus with recent progress]

### Checkpoint (mid-session)
- [Key decision made]
- [Important learning]
- [Current state]")

Red Flags - Update Memory NOW

Context Tiers (Reference Pattern)

Optimize context for relevance, not completeness:

Quick Context (< 500 tokens)

Use for simple tasks and handoffs:

• Current task and immediate goals
• Recent decisions affecting current work
• Active blockers or dependencies

Full Context (< 2000 tokens)

Use for complex tasks and session starts:

• Project architecture overview
• Key design decisions
• Integration points and APIs
• Active work streams

Archived Context (stored in memory files)

Reference when needed:

• Historical decisions with rationale
• Resolved issues and solutions
• Pattern library
• Performance benchmarks

Good context accelerates work; bad context creates confusion.

Context Management Functions (Reference Pattern)

Context Capture (at workflow end)

1. Extract key decisions and rationale from outputs
2. Identify reusable patterns and solutions
3. Document integration points between components
4. Track unresolved issues and TODOs

Context Distribution (at workflow start)

1. Prepare minimal, relevant context for the task
2. Maintain a context index for quick retrieval
3. Prune outdated or irrelevant information

Memory Management (ongoing)

• Store critical project decisions in memory
• Maintain a rolling summary of recent changes
• Create context checkpoints at major milestones

File Purposes

activeContext.md (Read/Write EVERY session)

Current state of work - ALWAYS check this first:

Copy# Active Context

## Current Focus
[What we're actively working on RIGHT NOW]

## Recent Changes
- [Change 1] - [file:line]
- [Change 2] - [file:line]

## Next Steps
1. [Immediate next action]
2. [Following action]
3. [After that]

## Active Decisions
| Decision | Choice | Why |
|----------|--------|-----|
| [Decision 1] | [What we chose] | [Reasoning] |
| [Decision 2] | [What we chose] | [Reasoning] |

## Learnings This Session
- [Insight 1]: [What we learned]
- [Insight 2]: [What we learned]

## Blockers / Issues
- [Blocker 1]: [Status]

## User Preferences Discovered
- [Preference]: [Details]

## Last Updated
[timestamp]

patterns.md (Accumulates over time)

Project-specific knowledge that persists:

Copy# Project Patterns

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

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

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

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

progress.md (Tracks completion)

What's done, what's not:

Copy# Progress Tracking

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

## Completed
- [x] [Task 1] - [verification evidence]
- [x] [Task 2] - [verification evidence]

## In Progress
- [ ] [Task 3] - [current status]

## Remaining
- [ ] [Task 4]
- [ ] [Task 5]

## Verification Evidence
| Check | Command | Result |
|-------|---------|--------|
| Tests | `npm test` | exit 0 (34/34) |
| Build | `npm run build` | exit 0 |

## Known Issues
- [Issue 1]: [Status]

## Evolution of Decisions
- [Date]: [Decision changed from X to Y because Z]

## Implementation Results (append-only after build)
| Planned | Actual | Deviation Reason |
|---------|--------|------------------|
| [What was planned] | [What happened] | [Why it differed] |

READ Triggers - When to Load Memory

ALWAYS Read (Non-Negotiable)

Read BEFORE These Actions

Read WHEN You Notice

File Selection Matrix

CopyWhat do I need?              → Which file?
─────────────────────────────────────────
Current state / focus        → activeContext.md
Prior decisions + reasoning  → activeContext.md (Active 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

Decision Integration

Before ANY decision, ask:

1. Did we decide this before? → Check activeContext.md Active Decisions table
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):

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

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

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

# Then use Edit to replace (matches first line, replaces entire content)
Edit(file_path=".claude/cc10x/activeContext.md",
     old_string="# Active Context",
     new_string="# Active Context

## Current Focus
[What we just finished / what's next]

## Recent Changes
- [Changes made this session]

## Next Steps
1. [What to do next]

## Active Decisions
| Decision | Choice | Why |
|----------|--------|-----|
| [Decisions made] | [Choice] | [Reason] |

## Learnings This Session
- [What we learned]

## Last Updated
[current date/time]")

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:

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

# Append by matching end of file and adding new content
Edit(file_path=".claude/cc10x/patterns.md",
     old_string="[last section heading]",
     new_string="[last section heading]

## [New Category]
- [Pattern]: [Details learned]")

When Completing Tasks (UPDATE)

Copy# Read progress.md, find the task, mark it complete using Edit
Read(file_path=".claude/cc10x/progress.md")

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

Failure to update memory = incomplete work.

Red Flags - STOP IMMEDIATELY

If you catch yourself:

• Starting work WITHOUT loading memory
• Making decisions WITHOUT checking Active Decisions table
• 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.

The Bottom Line

CopySTART → Load Memory → Do Work → Update Memory → END
         ↑               ↑              ↑
      MANDATORY    Check before    MANDATORY
                   decisions

The Full Cycle:

Copy1. LOAD all memory (START)
2. CHECK memory before decisions (DURING)
3. UPDATE memory with learnings (END)

Memory persistence is not a feature. It's a requirement.

Your effectiveness depends entirely on memory accuracy. Treat it with the same importance as the code itself.

READ without WRITE = Stale memory. WRITE without READ = Contradictory decisions. Both are equally critical.