Project Memory

CAP Pro maintains a project-specific memory at .cap/memory/. It complements your AI assistant's auto-memory (user preferences, feedback) with technical context that is specific to this project — what worked, what burned, what convention the codebase established.

What's in it

.cap/memory/
├── decisions.md     ← architectural decisions
├── pitfalls.md      ← gotchas, things that broke before
├── patterns.md      ← recurring conventions
└── hotspots.md      ← frequently edited files

The memory pipeline auto-generates these from:

1. Code tags — @cap-decision, @cap-pitfall, @cap-history
2. Session snapshots — cap-historian extracts decisions and pitfalls from each session
3. Git history — hotspot detection from churn analysis
4. Tag scanner — pattern detection from @cap-feature clustering

How agents use it

Every CAP Pro agent reads the relevant memory files before doing work:

• cap-prototyper reads pitfalls.md and patterns.md to avoid known issues and follow established conventions.
• cap-architect MODE: REFACTOR is required to consult pitfalls.md before suggesting splits — many refactors have failed because someone didn't know about a load-bearing implicit contract.
• cap-debugger reads pitfalls.md to check whether the current bug matches a known pattern.
• cap-curator MODE: STATUS summarises hotspots — files with > 3 sessions of edits in the last week.

Two layouts: V5 and V6

CAP Pro supports two memory layouts:

V5 (default, monolithic)

The four files (decisions.md, pitfalls.md, patterns.md, hotspots.md) contain all entries for the project. Simple, works fine up to ~200 entries per file.

V6 (per-feature, opt-in via .cap/config.json)

{
  "memory": { "layout": "v6" }
}

In V6:

• Top-level decisions.md and pitfalls.md become index tables (with the marker (V6 Index) in the title)
• Per-feature memory files live under features/F-XXX-<topic>.md
• Agents read the index plus only the relevant per-feature file — typically a 10–50× token reduction

Migrating to V6

/cap:migrate-memory --apply

Plan-diff-apply-verify pipeline with atomic backup and rollback.

Reading and writing memory

You don't usually write memory entries by hand. The pipeline does it for you. But you can pin entries you want to keep:

/cap:memory pin <id>

Pinned entries survive consolidation passes.

To browse:

/cap:memory status        # overview
/cap:memory show decisions # full content of one file

Memory and your AI assistant's auto-memory

CAP Pro's project memory and your AI assistant's auto-memory are different things:

	Project memory (CAP Pro)	Auto-memory (assistant)
Scope	One project	All your projects
Content	Technical: decisions, pitfalls, patterns, hotspots	Personal: role, preferences, feedback
Storage	.cap/memory/ (committed to git)	~/.claude/memory/ etc. (private)
Generated by	CAP Pro pipeline	The assistant, from your conversations

They complement each other. The assistant's auto-memory tells it who you are; CAP Pro's project memory tells it what this codebase has learned.

Best practices

• Don't manually edit decisions.md etc. — the pipeline regenerates them, your edits will be lost. To force a specific entry, use @cap-decision(learned:DATE) in the code instead.
• Pin important pitfalls. A pitfall the team learned the hard way deserves to survive consolidation.
• Trust hotspots over your gut. If hotspots.md says one file has 12 sessions of edits this month, that file deserves architecture attention more than the file you feel is the most-edited.
• Run /cap:memory init once when you adopt CAP Pro on an existing codebase. It bootstraps memory from existing tags, git history, and any existing session snapshots.