I Gave Claude Code
a Persistent Memory.
Here's the Full Setup.

Claude Code is powerful. But out of the box, every session starts cold — no memory of what you built last week, what decisions you made, or why you chose Prisma over Drizzle for that one service. I fixed that.

I'm Yash — CS/AI student at Rishihood University, sole backend dev and DevOps owner of RishiVerse (a live LMS/ERP platform), and someone who has shipped a lot of code with Claude Code as a pair programmer. The problem I kept hitting: context loss. Every new session, I'd spend the first 10 minutes re-explaining the project to Claude. That's dead time.

So I built a system. I call it the Second Brain — a structured file tree that lives in ~/Documents/SecondBrain/ and gets loaded into every Claude Code session via a CLAUDE.md hook. Here's exactly how it works and how you can copy it.

The Core Problem with AI Pair Programming

LLMs have no persistent memory between sessions. Every conversation starts with a clean slate. For a quick one-off task that's fine — but for a production codebase you're actively developing over weeks, it's brutal.

Here's what "no memory" actually costs you in practice:

The fix isn't a plugin or a paid feature. It's just files. Claude Code reads a CLAUDE.md at startup — so I made that file point to a rich, structured knowledge base. One file becomes a whole system.

The File Structure

The entire second brain lives in one directory. Here's the layout:

Key design principle: BRAIN.md is always loaded — it's the master index. Project files are only read when that project is active. Topic files are only read when that topic comes up. This keeps the context window lean. You're not dumping everything in at once.

BRAIN.md — The Master Index

BRAIN.md is the file that gets loaded every session. It's kept intentionally small (~2KB) so it's fast to load without eating context tokens. It contains three things: who I am, my active projects table, and a session log.

# Yash's Brain
> Always loaded. ~2KB. Fast.
> Full project details live in projects/ — read only when relevant.

## Active Projects
| Project | Stack | Status | Last Worked | File |
|---------|-------|--------|-------------|------|
| RishiVerse-Backend | Node.js, Express, Prisma | Active — branch: test | 2026-05-15 | projects/rishiverse-backend.md |
| GhostPilot | Electron 39, React 19, SQLite | v1.0.4 released | 2026-05-14 | projects/ghostpilot.md |

## Key Decisions
| Date | Project | Decision | Why |
|------|---------|----------|-----|
| 2026-05-13 | GhostPilot | AI ModelHint enum (ECONOMY/PREMIUM/LOCAL) | Tasks declare quality need without knowing which provider is configured |

The projects table gives Claude an immediate overview of everything in flight. The decisions table is a permanent record — it means Claude never recommends reversing a decision we already thought through.

The CLAUDE.md Hook — The Glue

Claude Code reads a CLAUDE.md file at the start of every session. This is the entry point. My CLAUDE.md doesn't contain project details directly — it contains instructions for Claude on how to load the second brain and how to behave during the session.

# Yash's Second Brain
## SESSION START

The hooks already:
✅ Created _sessions/YYYY-MM-DD_HH-MM.md
✅ Created projects/[slug].md if missing
✅ Added this session row to the project file
✅ Updated _activity/NOW.md → ACTIVE

## You just need to:
1. Read ~/Documents/SecondBrain/BRAIN.md
2. Read ~/Documents/SecondBrain/projects/[project-slug].md
3. Tell Yash ONE line:
   "🧠 [Project] — [last thing done / first session]"

## TOKEN RULES
- BRAIN.md → always read ✅
- projects/[slug].md → always (hooks identified project) ✅
- topics/[slug].md → only if that topic comes up ✅
- _sessions/ → write only, never re-read ✅
- Never read all files at once ✅

Decision Logging — The Secret Weapon

This is the part most people skip, and it's the part that provides the most value over time. Every architectural decision Claude makes is logged automatically via a bash hook.

echo '{
  "title": "Use Parallel pod management for etcd",
  "context": "3-node etcd cluster deadlocking on OrderedReady",
  "options": "OrderedReady (default), Parallel, custom init",
  "chosen": "Parallel pod management + tcpSocket readiness probe",
  "why": "etcd bootstrap needs all peers simultaneously; OrderedReady serializes boot causing deadlock",
  "tradeoffs": "Parallel means pods compete for resources at startup",
  "project": "distributed-systems-lab"
}' | ~/Documents/SecondBrain/hooks/log-decision.sh

The hook appends this to _decisions/decisions.md AND to the active session file. Six months later, when you're debugging a weird Kubernetes issue, you can search decisions.md and find exactly why you made that choice — with full reasoning, not just the outcome.

Session Lifecycle — Start, Work, Save

Every session follows the same three-phase lifecycle. The hooks handle the boring parts automatically.

"The goal isn't to make Claude smarter. It's to make the context it operates in richer."

Use This Scaffold Yourself

Everything above is generalizable. You don't need to be running an LMS or building an Electron app — the structure works for any project you're actively developing with Claude Code. Here's how to set it up from scratch.

mkdir -p ~/Documents/SecondBrain/{projects,topics,_sessions,_decisions,_activity,hooks}

cat > ~/Documents/SecondBrain/BRAIN.md << 'EOF'
# [Your Name]'s Brain
> Always loaded. ~2KB. Fast.

## Who I Am
- Name: [Your Name]
- Focus: [Your domain]
- Preferences: [e.g. explain WHY, mention trade-offs, clear > clever]

## Active Projects
| Project | Stack | Status | Last Worked | File |
|---------|-------|--------|-------------|------|

## Key Decisions
| Date | Project | Decision | Why |
|------|---------|----------|-----|

## Session Log
| Date | Project | What Happened |
|------|---------|---------------|
EOF

cat > ~/Documents/SecondBrain/hooks/log-decision.sh << 'EOF'
#!/bin/bash
# Reads JSON from stdin, appends to decisions.md and active session
INPUT=$(cat)
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
DECISIONS=~/Documents/SecondBrain/_decisions/decisions.md
SESSION=$(ls -t ~/Documents/SecondBrain/_sessions/*.md 2>/dev/null | head -1)

TITLE=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['title'])")
WHY=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['why'])")
PROJECT=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['project'])")

# Append to decisions.md
echo "\n---\n**[$TIMESTAMP] $TITLE** ($PROJECT)\n$INPUT" >> "$DECISIONS"

# Append to active session if exists
if [ -n "$SESSION" ]; then
  echo "\n### Decision: $TITLE\n$INPUT" >> "$SESSION"
fi

echo "✅ Logged: $TITLE"
EOF
chmod +x ~/Documents/SecondBrain/hooks/log-decision.sh

mkdir -p ~/.claude
cat > ~/.claude/CLAUDE.md << 'EOF'
# Second Brain

## Session Start
1. Read ~/Documents/SecondBrain/BRAIN.md
2. Read the relevant project file from projects/
3. Tell me ONE line: "🧠 [Project] — [last done / first session]"

## Token Rules
- BRAIN.md → always ✅
- projects/[slug].md → always (for active project) ✅
- topics/[slug].md → only if topic comes up ✅
- _sessions/ → write only ✅
- Never read all files at once ✅

## Decisions
Log every architectural decision via:
echo '{...json...}' | ~/Documents/SecondBrain/hooks/log-decision.sh

## Session End (when I say "save")
1. Fill session file: Goal + What Yash Should Know
2. Update projects/[slug].md: status, next steps
3. Update BRAIN.md: session log row, project last-worked date
4. Create topics/[slug].md if new topic learned
EOF

cat > ~/Documents/SecondBrain/projects/my-project.md << 'EOF'
# My Project

## Status
- Branch: main
- Last session: [date]
- Open items: [list]

## Stack
[Your stack here]

## Key Decisions
| Date | Decision | Why |
|------|----------|-----|

## Rules
[Architecture rules Claude must follow]

## Next Steps
[What to do next session]
EOF

What This Actually Changes

After running this system across 8 active projects simultaneously — an LMS backend, a desktop Electron app, two freelance projects, a deployed social media scheduler, and a subdomain OSINT tool — here's what materially changed:

The network graph at the top of this post is a visualization of my second brain's knowledge graph — each node a project or topic, each edge a relationship between them. The hub nodes are the projects I work on most; the leaf nodes are the topics they pull in. It's not just metaphor. The structure is real.

You can copy this scaffold entirely, adapt the naming conventions to your preferences, and have it running in under 10 minutes. The only thing that makes it powerful is actually keeping it updated — which the hooks and Claude's session-end protocol handle automatically.

The system is as useful as what you put into it. Start with one project. One decision. One session log entry. The graph builds itself from there.

Yash Lunawat · B.Tech AI, Rishihood University · Backend Dev @ RishiVerse · yashlunawat.com