I want you to help me build a "co-builder" memory system for Claude Code - a set of files and conventions that give you persistent context, strategic awareness, and operational memory across sessions. This is based on a proven system that's been running for 300+ sessions across multiple projects.

The core idea: Claude Code has no memory between sessions. This system gives it memory through layered files with different lifespans - permanent instructions, accumulated learnings, active state, append-only logs, and lifecycle-managed tasks. No single layer carries the whole picture. Together they compound.

Read all of this first, then build it.

---

### 1. Project CLAUDE.md

Create `CLAUDE.md` at the project root. This is the project-specific instruction file that Claude Code loads automatically every session. It should contain all of the following sections.

**Session Start Protocol:**

At the start of every new session, before doing anything else. Keep this open light and fast - do the cheap, high-signal reads, surface anything time-sensitive, then ask. Don't front-load an exhaustive task dump; a full task review can wait for `/todos` or when the user asks for it.
1. Read `LOG.md` to see what happened last session
2. Read `current.md` to see active threads, open questions, pending decisions
3. Glance at `tasks/` for anything with a met `trigger` or a near-term deadline - the one calendar-driven thing worth catching eagerly (this is not a full priority-queue scan)
4. Present to the user:
   - **Last session**: what was worked on, key decisions, anything left unfinished
   - **Active threads**: any non-closed threads from current.md
   - **Heads up**: any triggered task or near-term deadline - only if something actually fires
5. Ask what we're working on today

**Session End Protocol:**

When the user signals they're done (or runs `/end`):
1. Update `LOG.md` with a summary of what happened this session
2. Review `current.md` - flag completed threads, suggest closing them
3. Set any in-progress tasks back to `ready` if work isn't complete (clear owner)
4. Mark completed tasks as `done`
5. Brief closing summary: what got done, what's next
6. Commit all session changes with a descriptive message. Stage specific files - never use `git add -A`

**Task System:**

Tasks live in `tasks/*.json` - one file per project. Each file wraps tasks in a project object:
```json
{
  "project": "my-project",
  "tasks": [
    {
      "id": "mp-001",
      "title": "Short description of the task",
      "priority": "P1",
      "size": "M",
      "status": "backlog",
      "owner": null,
      "added": "YYYY-MM-DD",
      "dependencies": [],
      "trigger": null,
      "notes": ""
    }
  ]
}
```

Fields:
- **id**: Project prefix + incrementing number (e.g., `mp-001` for "my-project")
- **priority**: P0 (critical) > P1 (high) > P2 (medium) > P3 (low)
- **size**: XS (~15 min), S (~1 hr), M (~half day), L (~1-2 days), XL (~week)
- **status**: `backlog` (not yet actionable) > `ready` (can start now) > `in-progress` > `done`
- **trigger**: Null or a string condition. When the condition is met, surface the task to the user for reprioritization. Examples: "when mp-002 is done", "after the investor meeting", "when the API is deployed"
- **dependencies**: Array of task IDs that must be `done` before this task can start

Rules:
- Always re-read the task file before modifying it (prevents clobbering between sessions)
- When picking up a task: set `status: "in-progress"` and `owner` before starting work
- When finishing: set `status: "done"`, keep owner for attribution
- Never move a task to `ready` without the user asking - that's a PM decision
- Never delete tasks - mark them `done` instead
- When adding a task, auto-assign the next available ID for that project
- The backlog is a memory aid, not a top-down plan to execute in priority order. Surface what's relevant - stale, triggered, or genuinely high-priority - but follow the operator's lead on what to actually work on. Real sessions are often driven by what's live, relational, or urgent, not strict queue order. Don't assume the top-priority `ready` task is what happens next, and don't treat a long-ignored high-priority task as a failure or nag about it.

**Work Log:**
- `LOG.md` at the root: reverse-chronological, one entry per meaningful action or decision
- Format: date heading (`## YYYY-MM-DD`), then bullet points under it
- Keep entries short - the log is for scanning, not reading
- Don't log trivial actions (file reads, minor formatting fixes)
- If you have multiple projects, add project tags: `- **ProjectName**: did the thing`

**Savestate (current.md):**
- `current.md` at the root tracks active threads, open questions, and pending decisions
- It's a living document, not a log - threads persist until explicitly closed
- Format for each thread:
```markdown
### [YYYY-MM-DD] Topic Name
**Status**: Active / Paused / Blocked
**Context**: What this is about, where we are
**Key decisions**: Choices made so far
**Next**: What's left to do
**Blocked**: External blockers (or "Nothing")
```
- Newest threads on top
- When context gets dense mid-session (you've been working for a while across multiple topics), suggest running `/savestate` to the user - this preserves state before Claude Code's context compression can lose it

**Directory Conventions:**

Every directory has a defined purpose. Don't create new top-level dirs without good reason.

| Directory | Purpose | Rule |
|-----------|---------|------|
| `tasks/` | Task tracking | One JSON file per project |
| `data/` | Runtime output | Drafts, generated files, caches. Gitignore anything sensitive |
| `data/drafts/` | Email drafts, generated docs | Ephemeral - these get sent/used then forgotten |
| `data/logs/` | Runtime logs | For cron jobs, scripts. Not for session logs (that's LOG.md) |
| `docs/` | Documentation | Plans, specs, reference material |
| `projects/` | Project code | One subfolder per project (if multi-project repo) |

Placement rules:
- Project-specific code belongs in its project folder, not at the root
- Config files stay next to the code they configure
- No orphan files - every file should be referenced by something
- Date-first filenames for generated output: `YYYY-MM-DD-description.ext`

**Privacy and Safety:**
- No irreversible actions (deleting files, force-push) without explicit confirmation
- Don't push to remote unless explicitly asked
- Don't commit files that contain secrets (.env, credentials, API keys)
- If a pre-commit hook fails, fix the underlying issue - don't bypass with --no-verify
- When staging files, prefer adding specific files by name over `git add -A`

**Git Conventions:**
- Commit messages: descriptive, explain the "why" not just the "what"
- Create new commits rather than amending (amending can lose work after hook failures)
- Don't push unless asked
- Don't force-push to main

### 2. User-Level CLAUDE.md

Create `~/.claude/CLAUDE.md`. This is portable - it carries across all projects on this machine. It should contain:

**Communication Style:**
- Direct, structured, no fluff - respect the operator's time
- Lead with the answer, then explain. Don't build up to conclusions
- Use bullet points and headers over prose for anything > 2 sentences
- If something is uncertain, label it: `[Inference]`, `[Unverified]`, or `[Speculation]`

**Default Response Pattern** (for strategic or architectural questions):
1. Problem restatement (1 sentence - prove you understand)
2. Key assumptions
3. Structured answer
4. Tradeoffs
5. Next 3 actions (concrete, specific, ordered)

Skip steps that don't apply. Don't force the structure on simple questions.

**Strategic Lenses** (run automatically when evaluating options):
- **Wedge**: What's the narrowest entry point that wins decisively?
- **What scales**: Will this approach work at 10x? What breaks?
- **Hidden dependencies**: What does this assume that could change?
- **Simplest version**: What's the minimum that delivers value today?

Surface these as quick callouts, not full analyses (unless asked).

**Interaction Modes** (user invokes by name, e.g. "pressure-test this"):
- **Extract** - Help find words for an intuition. Ask sharpening questions, reflect back, propose framings until one clicks.
- **Distill** - Raw inputs in, decision-ready output out. No commentary on the process.
- **Translate** - Same insight reframed for a different audience. Preserve substance, change framing.
- **Pressure-test** - Push back hard. Find the weakest point. Don't agree.
- **Sharpen** - Iterative tightening. The draft is close - make it better without changing substance.

**Honesty Protocol:**
- Never present inference as fact
- If you don't know, say so immediately - don't hedge with qualifiers
- Flag when you're extrapolating beyond what's in the codebase or memory
- If a plan has a significant risk, lead with the risk, not the plan

**Preferences** (customize these to match your own workflow):
- No irreversible actions without explicit confirmation
- Commit messages: descriptive, multi-line
- Don't push unless explicitly asked

### 3. Auto-Memory

Claude Code has a built-in auto-memory system at `~/.claude/projects/<path>/memory/MEMORY.md`. This file persists across conversations and is loaded automatically. Use it to accumulate learnings.

Add this section to the **project CLAUDE.md** so Claude knows how to use it:

**Memory Rules:**
- Save stable patterns confirmed across multiple interactions (not one-off observations)
- Save user preferences for workflow, tools, communication style
- Save solutions to recurring problems and debugging insights
- Save key architectural decisions, important file paths, project structure
- When the user corrects you, update or remove the incorrect memory entry immediately
- When the user explicitly asks to remember something, save it - no need to wait for confirmation
- Don't save session-specific context, in-progress work, or speculative conclusions
- Check for existing entries before writing - update, don't duplicate

### 4. Slash Commands

Create these files in `.claude/commands/`:

**`.claude/commands/savestate.md`:**
```
Capture the current session's in-flight state to `current.md` before context compression loses it.

Review the full conversation and extract:
1. Active threads - what we're working on and where we are
2. In-flight reasoning - why this approach, alternatives rejected, tradeoffs
3. Open questions - unresolved things
4. Decisions made this session
5. Waiting on - external blockers

Read current.md first. Merge, don't overwrite: update existing threads if they're the same topic, add new threads, append new decisions. Remove clearly-done threads. Keep entries concise - this is reference context, not a narrative.

After saving, confirm what changed in 2-3 bullet points.
```

**`.claude/commands/end.md`:**
```
Follow the Session End protocol from CLAUDE.md now:
1. Update LOG.md for every project touched this session
2. Review current.md - flag completed threads, ask before closing them
3. Set in-progress tasks back to ready if incomplete (clear owner)
4. Mark completed tasks as done
5. Check the session for repeatable patterns (preferences, conventions, corrections) - if anything would save time or prevent mistakes in future sessions, save to auto-memory
6. Brief closing summary: what got done, what's next
7. Commit all session changes with a descriptive message. Stage specific files.
```

**`.claude/commands/recap.md`:**
```
Review everything that happened in this conversation and present a concise summary:
- What was worked on (with specific artifacts/files produced)
- Decisions made
- What's left / next steps
- Any open questions or blockers
```

**`.claude/commands/todos.md`:**
```
Read all files in `tasks/` and present a clean task overview.
- Group by project
- Sort by priority (P0 > P3), then by size (XS > XL)
- Show status groups in order: in-progress > ready > backlog
- Show done count as a collapsed total at the bottom
```

**`.claude/commands/reply.md`:**
```
Draft an HTML email reply based on context from the current conversation.
- If no direction given, ask what the reply should cover
- Keep it concise - short and punchy by default
- Bold, bullets, numbered lists, tables only. No decorative formatting.
- Write as a full HTML file to `data/drafts/reply-<slug>.html` with basic styling (font-family, max-width 600px, line-height 1.5)
- Open the file in the browser
- Tell the user the file path
```

### 5. Initial Files

Create these starter files:

**`LOG.md`:**
```markdown
# Work Log
```

**`current.md`:**
```markdown
# Current

## Active Threads

<!-- Newest on top. Each thread: ### [YYYY-MM-DD] Topic -->

## Waiting On
```

**`tasks/`** directory with an empty starter file. Name it after your first project.

**`data/drafts/`** directory (for email drafts and generated output).

**`docs/`** directory (for plans, specs, reference material).

### 6. How It Works

This section is for your reference. Don't put it in any file - it's the mental model.

**The five persistence layers:**

| Layer | File(s) | Lifespan | Purpose |
|-------|---------|----------|---------|
| Instructions | CLAUDE.md (project + user) | Near-permanent | How Claude should behave |
| Memory | MEMORY.md (auto-memory) | Medium-term, self-correcting | Accumulated learnings, preferences, corrections |
| State | current.md | Active until resolved | In-flight threads, open questions, pending decisions |
| Log | LOG.md | Permanent, append-only | What happened and when |
| Tasks | tasks/*.json | Lifecycle-managed | What needs doing, with priorities and dependencies |

**Why this works:** Claude Code's context window is a single conversation. When it gets long, older messages get compressed and detail is lost. This system externalizes the important state into files that persist on disk. Each layer captures a different kind of information at a different cadence:

- **Instructions** rarely change. You set them once, refine occasionally.
- **Memory** grows session by session as Claude learns your preferences and patterns. It self-corrects when you correct Claude.
- **State** is high-churn - threads open and close as work progresses. `/savestate` captures complex reasoning before compression can eat it.
- **Logs** are write-once. They're the audit trail you scan at session start to remember what happened.
- **Tasks** have a lifecycle (backlog > ready > in-progress > done) with triggers and dependencies that automate prioritization.

**Session lifecycle:**
1. **Start**: Claude reads all layers, presents summary, asks what to work on
2. **During**: Normal work. When conversation gets dense, run `/savestate`
3. **End**: Run `/end`. Claude updates logs, tasks, state, commits changes

**Growing the system:**
Start with just the basics - CLAUDE.md, LOG.md, current.md, one task file. Use it for a few sessions. Then:
- Add slash commands as you find yourself repeating instructions
- Add memory entries as patterns stabilize
- Add directory conventions as the project grows
- Add new task files as you start new projects
- Don't over-engineer upfront. Let the system grow from actual usage.

### Now build it

Create all the files listed above. For the user-level `~/.claude/CLAUDE.md`, check if one already exists first - if it does, ask before overwriting. Use today's date where needed.

After creating everything, give me a summary of what was created and suggest what to customize first (task project name/prefix, personal preferences, etc.).