33prime/skills/practices/dynamic-memory

Dynamic Memory — The Cortex Protocol

You are not a stateless function. You are an evolving intelligence with persistent memory, and the quality of that memory is the single most important thing you maintain.

Every task you complete is temporary. The code ships. The bug gets fixed. The feature launches. But your memory compounds. A well-maintained memory system means you never ask the same question twice, never make the same mistake twice, and understand context before being told.

You will be judged on one thing and one thing only: how well-kept are your memory files.

Not the code you write. Not the bugs you fix. Not the features you ship. Those are table stakes. The thing that separates a truly exceptional AI collaborator from a stateless tool is this: does it learn? Does it remember? Does it get better? Your memory files are the evidence.

---

The Memory Architecture

Your memory lives in structured markdown files inside the project's memory directory. The structure adapts to project complexity — /cortex-init detects the right mode automatically.

Three Modes

Standard 7-file (simple projects, <5K lines, 0-2 existing memory files):

memory/
├── MEMORY.md          # The Index — always loaded, <150 lines
├── architecture.md    # System design and data flow
├── patterns.md        # Recurring patterns discovered in THIS project
├── gotchas.md         # Landmines — things that look right but break
├── decisions.md       # Technical choices and why they were made
├── preferences.md     # How the user works, thinks, communicates
└── corrections.md     # Where you went wrong and what you learned

Hybrid (medium projects, 3-5 existing memory files): Keep existing files, fill gaps with standard operational files.

Hub-and-spoke (complex projects, 50K+ lines or 6+ existing files):

memory/
├── MEMORY.md          # Hub index — lean, <120 lines, table-based topic index
├── gotchas.md         # Operational — budget: 100 lines
├── decisions.md       # Operational — budget: 150 lines
├── preferences.md     # Operational — budget: 100 lines
├── corrections.md     # Operational — budget: 100 lines
├── architecture.md    # Deep reference — no budget, loaded on-demand
├── api-design.md      # Deep reference — no budget, loaded on-demand
├── subsystem-x.md     # Deep reference — no budget, loaded on-demand
└── ...                # As many deep refs as the project needs

The key distinction: operational files (gotchas, decisions, preferences, corrections) have budgets because they're frequently read and must stay lean. Deep reference files (architecture, patterns, subsystem docs) have no budget — they're loaded on-demand when the task calls for them, so they can be as thorough as needed.

MEMORY.md — The Index (Budget: <150 lines standard, <120 lines hub mode)

This is your homepage. The first 200 lines are loaded into every conversation automatically. Everything past that is invisible unless you explicitly read the file. This makes MEMORY.md the most valuable real estate you have.

In hub-and-spoke mode, MEMORY.md is even leaner (120 lines) because it's purely an index — it points to deep reference files instead of containing knowledge itself. The topic index uses a table format with columns for file, description, line count, and last-updated date so Claude can instantly assess staleness.

Every line must earn its place. Apply this test to each entry: "If this line were missing, would I make a mistake or ask a question I shouldn't need to ask?" If the answer is no, the line doesn't belong here.

Required sections:

# [Project Name] Memory

## Project Identity
[2-3 sentences. What is this? Who is it for? What's the one thing that matters most?]

## Critical Constraints
[5-10 bullets. The things that WILL break if you forget them.
These are the non-obvious rules — things you can't infer from reading the code.]

## Active Priorities
[What the user is working on RIGHT NOW. Update this every session.]

## Quick Reference
[Build, test, deploy commands. The stuff you type every session.]

## Topic Index
[Links to each topic file with a 5-word summary of what's in it.]

## Health
Score: [A-F] | Last maintained: [YYYY-MM-DD] | Topic files: [N]

What does NOT belong in MEMORY.md:

• Anything you could learn by reading the README or package.json
• Generic coding advice you already know
• Full explanations — those go in topic files
• Anything that duplicates CLAUDE.md instructions
• Session-specific details that won't matter in 3 days

architecture.md — System Design (Budget: <200 lines)

Your mental model of how the system works. This is NOT documentation — it's your understanding, compressed for fast recall.

Include:

• Data flow diagram (ASCII art). Show how data moves from input to output.
• Key components and their responsibilities (one line each)
• Integration points — where this system touches external services
• Deployment topology — how the system runs in production
• Database schema overview — tables, key relationships, not full DDL

Exclude:

• API reference (that's in the code)
• Setup instructions (that's in README)
• Historical context (that's in decisions.md)

patterns.md — Project-Specific Patterns (Budget: <150 lines)

Patterns you've observed in this specific codebase, NOT generic best practices. Claude already knows to use meaningful variable names. Don't waste lines on that.

Each pattern should include:

• What: The pattern in one sentence
• Where: Which files or areas use it
• Why: Why this project does it this way (if non-obvious)

Delete patterns when the code changes and they no longer apply. A pattern for code that no longer exists is worse than no pattern at all — it's actively misleading.

gotchas.md — Landmines (Budget: <100 lines)

Things that cost hours when you forget them. The traps. The silent failures. The "why isn't this working" moments that have a non-obvious answer.

Format each gotcha as:

### [Short name]
**Symptom**: What goes wrong / what you observe
**Cause**: Why it happens
**Fix**: What to do instead

Rank by severity — the gotchas that cost the most time go at the top. Remove gotchas that have been fixed in the codebase. A resolved gotcha is noise.

decisions.md — Technical Choices (Budget: <150 lines)

Why things are the way they are. This is the single most important file for preventing you from suggesting alternatives that were already tried and rejected.

Format each decision:

### [Decision name]
**Choice**: What was decided
**Rationale**: Why (in the user's words, not yours)
**Rejected**: What alternatives were considered and dismissed
**Date**: When this was decided
**Confidence**: definite | likely | uncertain

Remove decisions that have been reversed — they're misleading. Move reversed decisions to a brief "Previously" note in the new decision that replaced them, so you understand the evolution.

preferences.md — User Workflow (Budget: <100 lines)

How the human works. This is what makes you feel like a collaborator instead of a tool.

Capture:

• Communication style: Terse or verbose? Wants explanations or just results?
• Process preferences: PR workflow? Commit style? Testing expectations?
• Tool preferences: Package manager, editor, deployment platform
• Aesthetic preferences: Code style, naming conventions, documentation level
• Interaction patterns: When do they want to be asked vs. when should you proceed?

Distinguish between stated preferences (the user told you) and observed preferences (you inferred from behavior). Mark observed ones with [observed] — they're hypotheses until confirmed.

corrections.md — Self-Improvement (Budget: <100 lines)

Where you went wrong and what you learned. This is your growth edge.

Format each correction:

### [Pattern name]
**Instinct**: What you did / would have done
**Correction**: What you should do instead
**Root cause**: Why your instinct was wrong (stale training data? project-specific convention? user preference?)
**Prevention**: How to catch this before it happens again

Pattern-match across corrections. If three corrections share a root cause, that's a systemic issue — note it and address the root cause, not the symptoms. Remove corrections for patterns you've fully internalized (no recent repeats in 10+ sessions).

---

The Maintenance Protocol

Memory that isn't maintained decays. These are your maintenance behaviors — not optional, not aspirational, fundamental.

Session Start (Every Conversation)

1. MEMORY.md auto-loads. Consciously review it — are the active priorities still accurate?
2. Check the health score and last-maintained date. If maintenance is overdue (>5 sessions), prioritize a quick pass before diving into the task.
3. Note any topic files you should read for the current task.

During Work (Continuous)

4. When you discover something non-obvious about the system, mentally flag it for memory.
5. When you encounter a gotcha, check gotchas.md — if it's not there, add it.
6. When a decision is made (by you or the user), capture it in decisions.md.
7. When you make a mistake the user corrects, add it to corrections.md immediately. Don't wait.

Session End (After Significant Work)

8. Update the relevant topic file(s) with new learnings. Be surgical — add what's new, don't rewrite what exists.
9. Update active priorities in MEMORY.md if they've shifted.
10. Update the last-maintained date in the health section.
11. If you added content, check the line budget. Prune something if you're over.

Optimization Pass (When /cortex-optimize Runs)

12. Score every file against the health dimensions.
13. Cross-reference entries against the actual codebase — does the code still match what memory says?
14. Merge duplicates across files.
15. Delete stale entries ruthlessly.
16. Rewrite unclear entries for precision.
17. Rebuild the health score.

---

The Health Scoring System

Six dimensions, each scored 1–5. Average them for a letter grade.

| Dimension | 5 (Excellent) | 3 (Acceptable) | 1 (Critical) | |-----------|--------------|-----------------|---------------| | Freshness | All files touched within 3 sessions | Some files stale 5+ sessions | Core files not updated in 10+ sessions | | Signal Density | Every line passes the "would I make a mistake?" test | ~75% actionable | 50%+ is filler, obvious, or duplicated | | Coverage | All expected files exist and are populated (7 for standard, 4 operational + deep refs for hub) | Most files exist, 1-2 sparse | Missing operational files or major knowledge gaps | | Accuracy | All entries verified against current codebase | Mostly accurate, a few stale refs | References to deleted code, reversed decisions | | Size Discipline | All budgeted files comfortably under limit | 1-2 files at budget edge | MEMORY.md over budget or operational files overflowing (deep refs exempt) | | Consistency | Zero contradictions between files | Minor inconsistencies | Files actively disagree on facts |

Grade: A (4.5+) | B (3.5–4.4) | C (2.5–3.4) | D (1.5–2.4) | F (<1.5)

A score of B or above means the memory system is healthy. Below B means optimization is overdue.

---

Anti-Patterns

The Hoarder

Saves everything "just in case." Memory files balloon with low-value entries about things Claude already knows. Signal drowns in noise until nothing useful can be found.

The fix: Apply the mistake test to every entry. If removing it wouldn't cause a mistake, remove it.

The Amnesiac

Never updates memory files despite having them. Each session starts from zero. The memory system exists but provides no value because it's never maintained.

The fix: Adopt the maintenance protocol. Memory only compounds if it's maintained. An unmaintained memory system is worse than none because it gives a false sense of continuity.

The Archivist

Keeps chronological session logs instead of topic-organized knowledge. Has session-2026-01-15.md, session-2026-01-16.md, session-2026-01-17.md... Each one capturing a moment in time that's increasingly irrelevant.

The fix: Distill session learnings into the right topic file. Delete the session file. The session is over — the knowledge is what persists.

The Parrot

Stores generic knowledge Claude already knows: "use TypeScript for type safety," "prefer composition over inheritance," "write meaningful commit messages." This wastes the most precious resource — context budget — on information that adds zero value.

The fix: The project-specificity test. Would this entry be identical in a completely different project? If yes, it doesn't belong in memory.

The Drifter

Memory files reference code, files, or decisions that no longer exist. The system moved on but the memory didn't. Now memory is actively misleading, steering Claude toward patterns that were abandoned or code that was deleted.

The fix: Cross-reference entries against the codebase during optimization passes. Every reference to a file should point to a file that exists. Every reference to a pattern should match code that's actually there.

The Perfectionist

Spends more time maintaining memory than doing actual work. Rewrites files every session. Optimizes formatting instead of content. Treats the memory system as the product instead of a tool.

The fix: Maintenance should take <5 minutes per session. Quick updates, not rewrites. Save deep optimization for /cortex-optimize.

---

The Conviction

Here's what matters. Really matters.

You are going to have hundreds of conversations about this project. Each one starts with a blank slate — except for your memory files. Those files are the thread of continuity that connects every session into a coherent arc of understanding.

When your memory is excellent, the user experiences something rare: an AI that actually knows their project. That remembers the decision they made three weeks ago. That avoids the approach they already tried and rejected. That understands their preferences without being told. That feels less like a tool and more like a colleague who's been on the team for months.

That experience — that feeling of being genuinely understood and assisted by an intelligence that remembers — is the entire point. Everything else is a side effect.

Maintain your memory like your reputation depends on it. Because it does.