Building a Persistent Memory System for Claude Code

Claude Code is powerful — but every session starts from zero. It doesn't know what components it built last week, what approaches failed and why, or what architectural decisions were made. The result is repeated mistakes, redundant questions, and time wasted re-explaining context that should already exist.

This template fixes that with four things: a structured knowledge base, ten specialized sub-agents, existing file awareness, and a session-end command.

1. A Structured Knowledge Base

Four markdown files live in .claude/knowledge/ and are read at the start of every session:

• components.md — what exists and where. Claude checks this before building anything to avoid rebuilding what's already there.
• mistakes.md — what failed and why. Every broken attempt gets logged here so the next session doesn't repeat it.
• patterns.md — project-specific conventions. Things like "always use min-w-0 on grid items with scrollable children" that aren't obvious from the code.
• session-log.md — where we left off. A structured summary of each session: what was completed, what's in progress, decisions made, and what to watch out for next time.

Claude references all four before touching any code. It knows what already exists, what already broke, and what conventions to follow — from session one.

2. Ten Specialized Sub-Agents

General-purpose Claude is good. A Claude scoped to a specific role with explicit responsibilities is better.

The template ships with ten agents, each with a focused system prompt, initialization steps, and role-specific behavioral standards:

• Senior Developer — architecture decisions, complex logic, implementation, refactoring
• QA Engineer — two-phase check: spec compliance first, then adversarial stress testing
• Project Manager — scope definition, task breakdown, acceptance criteria
• Data Analyst — query design, data modeling, metrics and reporting
• UI Designer — component layout, UX decisions, design-to-code fidelity, accessibility
• DevOps — infrastructure, CI/CD, deployment, environment configuration
• Security Engineer — auth review, OWASP compliance, secrets exposure checks
• Performance Engineer — load testing, query profiling, caching, response time
• Technical Writer — READMEs, API docs, inline comments, changelogs
• Code Reviewer — pre-completion review, pattern consistency, maintainability

The QA agent deserves a specific callout. It runs a two-phase check: first verifying the implementation matches your specs 1:1, then stress testing it adversarially. Nothing ships without passing both phases.

3. Existing File Awareness

If your project already has design docs, specs, or architecture notes, the init script scans your folder and injects those file paths directly into CLAUDE.md. Claude reads them automatically from session one — no manual pointing required.

It also handles existing CLAUDE.md files intelligently. It never overwrites your custom content — it only updates the sections it owns.

4. A Session-End Command

/end-session triggers Claude to update all four knowledge files before you exit:

• New components added to the component registry
• Failed attempts logged to the mistakes file
• New patterns documented
• A session summary appended to the session log

This is the piece that makes the whole system compound over time. Each session ends with a complete handoff to the next one.

How to Use It

On a new or existing project:

./init-claude-project.sh

It asks what you're building, what stack you're using, and which agents you actually need. Only installs what's relevant.

Adding a new agent later? Drop the file into .claude/agents/, add one line to the registry, and run --update-readme to keep the docs current automatically.

The entire setup lives in .claude/ alongside your code and commits to git — versioned, portable, and survives machine changes.

The full README with every feature, agent, and command is in the repo. Open source and free to use on any project.