Every Claude Session Starts From Zero and Here Is How to Change That

Every time you start a new Claude session, it forgets everything. The architecture decision you made last week. The pattern that burned you three times before you figured it out. The context behind why the codebase looks the way it does.

You start from scratch. Every. Single. Time.

That is not a Claude problem; that is how LLMs work. But it means most developers are using their AI assistant at maybe 30% of its potential. They get a smart stranger instead of a thinking partner who knows their codebase, their decisions, and their history.

The fix is a second brain: a structured knowledge base Claude reads at the start of every session, so your accumulated context, decisions, and patterns are available automatically.

What Is a Second Brain?

The term comes from Tiago Forte’s productivity framework: offloading memory into an external system so your 🧠 brain is free to think instead of remember.

Applied to AI-assisted development, it works the same way: instead of relying on Claude to remember things between sessions (it can't), you build a knowledge base that Claude reads. Your history becomes its context.

The shift: a compounding system. The longer you use it, the more context Claude has, the better the output. A smart stranger becomes a thinking partner who knows your project cold.

How It Works

Claude Code reads a CLAUDE.md file from your project directory at the start of every session. Whatever is in that file is loaded into context before you type anything.

Most people stop at coding rules and conventions. The second brain extends that into a full knowledge base (KB): structured markdown Claude reads on demand:

your-project-kb/
├── README.md
├── architecture_decisions.md
├── session_patterns.md
├── open_questions.md
└── sessions/
    └── README.md

What each piece does

On-demand routing (the important part)

The README does not load every file up front. It holds a table that tells Claude which file to open for the task:

Claude reads the README, checks the table, and pulls only what is relevant. Clean context, lower token cost.

One Principle Worth Calling Out

Separate what from why.

Your CLAUDE.md has the rules. Your KB has the reasoning behind them. Rules stay lean and stable; the KB grows as the project evolves and reasoning accumulates.

Most developers never write down the why. It lives in someone’s head, disappears when they move on, and gets re-discovered (or re-broken) by the next person. The KB makes it durable.

How to Set It Up

Step 1: Create the knowledge base

Create a directory for your project KB. A dedicated repo separate from application code keeps it clean and syncs on its own.

~/second-brain/
└── my-project/
    ├── README.md
    ├── architecture_decisions.md
    ├── session_patterns.md
    ├── open_questions.md
    └── sessions/
        └── README.md

Step 2: Configure global CLAUDE.md

Point Claude at the KB. In ~/.claude/CLAUDE.md:

### Second Brain

At the start of each session, read the README for the current project:

- my-project → ~/second-brain/my-project/README.md

Only read other KB files when the task requires it.

Step 3: Fill in the README

Keep it short: current branch, active work, what is next.

# My Project — Knowledge Base

**Last updated:** 2026-03-28 | **Branch:** `feature/auth-refactor`

## Current State

**Active work:** Refactoring auth middleware — removing session token storage
**Up next:** Update affected API routes → QA → deploy

On-demand files: read only when relevant

Step 4: Add a session command

Claude Code supports custom slash commands: any .md file in .claude/commands/ becomes a /command-name you can run from the prompt. Create the file once, use it every session.

From your project root, run:

mkdir -p .claude/commands && touch .claude/commands/update-second-brain.md

Then paste this into .claude/commands/update-second-brain.md:

Update the second brain for the current project.

1. Update README.md
   - Last updated date (today) and active branch
   - Active work: what is in progress right now
   - Recently completed: what just shipped or was resolved
   - Up next: what comes after current work

2. Create sessions/YYYY-MM-DD-short-description.md
   - ## What happened — bullet list of work done this session
   - ## Active branch — current branch name
   - ## Decisions made — any architectural or approach decisions (brief)
   - ## Notes — anything else worth remembering

3. Update sessions/README.md
   - Add new session link at the top (newest first)

4. Only if something durable changed this session:
   - architecture_decisions.md — add a new entry with ### title, **Why:** line
   - session_patterns.md — add a new entry with ## title, **Why:** line
   - open_questions.md — add new questions, remove any that were resolved

Save the file. From now on, type /update-second-brain at the end of any session and Claude runs the whole update in about two minutes. A named command turns maintenance into a ritual, not a chore.

Bootstrap Prompt

Skip the manual setup. Paste this into Claude Code from your project root:

Set up a second brain knowledge base for this project.

Create ~/second-brain/<project-name>/ with these files:

README.md
  - Last updated date (today) and current branch
  - Active work and what is up next
  - A two-column table: File | Read when
    listing architecture_decisions.md, session_patterns.md,
    and open_questions.md with a one-line trigger for each

architecture_decisions.md
  - One entry per non-obvious decision you can infer from the
    codebase (tech stack, folder structure, key constraints).
  - Format each entry as:
      ### Decision title
      **Why:** reasoning

session_patterns.md
  - One entry per pattern or gotcha visible in the code.
  - Format each entry as:
      ## Pattern title
      **Why:** reasoning
      (include a code example if it makes the pattern clearer)

open_questions.md
  - Any open questions or tech debt you notice from a quick scan.
  - One entry per item, with a one-line context note.

sessions/README.md
  - Header: "# <Project> — Session Index"
  - Subheader: "All working sessions, newest first."
  - Empty list (no sessions yet)

Then add this block to ~/.claude/CLAUDE.md:

### Second Brain
At the start of each session, read the README for the current project:
- <project-name> → ~/second-brain/<project-name>/README.md

Only read other KB files when the task requires it.

Finally, tell me what you created and flag anything you were uncertain about.

Run it once. Review what it produces. Adjust the files to match your actual project state. The KB is only as good as what you put in. This just removes the blank-page friction of starting.

How to Use It Day to Day

That is the loop. It feels like overhead at first. After a few sessions, you stop re-explaining architecture; Claude flags an approach that conflicts with a decision from months ago without you mentioning it; you stop paying the new-session context tax.

What This Is Not

Not magic. Claude still errs. The KB does not replace reading code or thinking. It removes the cost of re-establishing context every session so energy goes to the real problem.

Not documentation. Write for Claude: terse, structured, signal-dense. If it reads like a wiki article, it is too long.

Not automatic. The system compounds only if you maintain it. A stale KB is noise, worse than none. The slash command keeps friction low; the habit still has to stick.

The Honest Payoff

After a few weeks, something shifts. Claude flags a conflict with a decision you made months ago. You open a session after two weeks away and it is already oriented. You stop paying the context tax on every new conversation.

This is my setup. It fits how I work and it will not fit yours exactly. Treat it as a starting point, not a prescription. Skip the files you do not need, move things around, adjust the cadence.

The structure is a starting point. What matters is having somewhere to put the knowledge that makes you and your AI more effective over time.