Mike Dolan

Posted on Apr 2

How I Built Persistent Memory for Claude Code

#ai #llm #productivity #showdev

Every Claude Code session starts from zero. Close the terminal and everything is gone. Decisions you locked last week, context from three projects, that debugging session where you finally figured out the root cause. All lost. You re-explain yourself every single time.

MEMORY.md is supposed to help. It is a flat file with a 200-line and 25KB cap, no search, and no structure. Worse, the AI decides what gets remembered and what gets thrown away. You have no control over what it keeps, what it summarizes, and what it silently drops. That is the core problem. claude-brain puts you in control of your data. Every word of every chat of every conversation across every project is auto-captured. Nothing is lost. You decide what matters.

I spent weeks building a real solution. It is called claude-brain. It is free, open source, and running right now on 1,321 sessions, 67,000+ messages, and 9 projects.

What Claude Knows With the Brain

Without it, Claude starts every session as a stranger. With it, Claude knows:

Who you are - name, preferences, working style, career goals
What you have discussed - every conversation, searchable by keyword, meaning, or fuzzy match
What you have decided - numbered, locked decisions that Claude will not re-ask
What is true about your projects - features, architecture, timelines, status
What happened recently - session summaries, project health, next steps
What connects your projects - cross-project search finds related work, shared patterns, decisions
What you should do today - proactive email briefings with per-project next steps and blockers

The Architecture

The system has three layers: capture, storage, and retrieval.

Capture: Six Hooks

Claude Code has a hook system that lets you run scripts at specific points in a session lifecycle. claude-brain uses all six:

session-start      → loads recent session notes, project context
user-prompt-submit → searches your full history, injects relevant matches
stop               → captures the conversation to the database
session-end        → triggers sync and backup
pre-compact        → saves all context before the context window resets
post-compact       → re-injects brain context after compaction

The pre-compact and post-compact hooks are critical. During long sessions, Claude Code compacts your conversation to fit the context window. Without these hooks, everything before compaction is gone. With them, the brain captures the full conversation before compaction and re-injects the most relevant context after. Nothing is lost.

You never manually save anything. The hooks handle everything automatically.

What Happens When You Start a Session

You navigate to a project folder and type claude. Four things happen behind the scenes:

CLAUDE.md loads - your project folder has a CLAUDE.md with project-specific instructions. Claude reads this automatically.
Session-start hook fires - loads your last session's notes, flags unfinished items, injects everything into Claude's context so it knows where you left off.
Memory search hook activates - on every message you send, a script searches your brain database for relevant past conversations and injects them into Claude's context. You do not see this happening, but Claude does.
MCP tools become available - Claude can search transcripts, look up decisions, check project facts, and query your profile on its own.

You do not configure anything per session. It just works.

Storage: Local SQLite

Everything goes into a single SQLite database on your machine. No cloud, no API keys, no external services. The database stores:

Every message from every conversation (lossless, no summarization)
Session metadata (timestamps, project, message counts)
Session notes (structured summaries written at end of each session)
Numbered decisions with rationale
Project-specific facts
Personal preferences and profile data
Session quality scores and tags

One database, all projects, fully local. Your data never leaves your machine.

Retrieval: Three Search Modes

Having a database full of conversations is useless if you cannot find what you need. claude-brain has three search modes:

Keyword search (FTS5): SQLite's full-text search engine with tokenization and ranking. Fast and precise. Search for "payment API" and it finds every message containing those words across all projects.

# Under the hood: FTS5 query with recency bias
SELECT content, rank
FROM transcripts_fts
WHERE transcripts_fts MATCH 'payment API'
ORDER BY rank
LIMIT 10

Semantic search: Sentence-transformer embeddings (27,000+ indexed) with cosine similarity. Search by meaning, not just words. "How users pay" finds payment discussions even when those exact words never appear.

Fuzzy search: Typo-tolerant matching. "sesion" auto-corrects to "session" before the query runs. Useful when you cannot remember the exact term.

All three work cross-project. No silos. Search your entire history from any session.

What You Can Actually Ask

The brain is not a passive archive. Here are real things you can type in Claude Code:

Simple searches:

"Search the brain for authentication"
"Find sessions about Docker"
"Look up the payment API"

Complex queries:

"What did we work on two days ago around 2pm?"
"Show me every decision we made about the database"
"Find conversations where I was frustrated - what went wrong?"
"Compare my most productive sessions to my worst ones"
"What's the full history of this project from the beginning?"

Meaning-based searches (finds related content even when words do not match):

"How do users pay for things?" → finds payment API discussions
"Sessions about server problems" → finds deployment errors, timeouts, Docker issues

Cross-project intelligence:

"Search all projects for anything about Docker"
"What decisions have we made about APIs across every project?"
"What patterns show up in my worst sessions across all projects?"

Post-mortem and lessons learned:

"Look at my worst-rated sessions and tell me what went wrong"
"What mistakes keep repeating across my projects?"
"Compare my best and worst sessions - what patterns do you see?"
"Find every time I had to redo something - what caused it?"

What Makes It Different

I looked at every memory tool out there before building this. Here is what I found and why I went a different direction.

Lossless Capture

Most memory tools extract "memories" from your conversations and throw away the raw transcript. They decide what matters and discard the rest. The problem is they are wrong often enough that it matters. When you need the exact thing you said three weeks ago, a summarized memory does not help.

claude-brain keeps every word. The raw conversation is the database. Search finds it. Nothing is summarized away, nothing is lost.

Cross-Platform Imports

No other memory tool does this. claude-brain imports your full conversation history from ChatGPT and Gemini into the same database:

ChatGPT: Export your data from OpenAI, run /brain-import, done
Gemini: Google Takeout export, run /brain-import, done
Claude.ai: Chrome extension export, run /brain-import, done

One database. Every AI conversation you have ever had. Fully searchable with all three search modes.

Email Digests

The brain reaches out to you. Schedule via cron and forget. Three built-in templates:

Daily standup: Per-project status with "Pick Up Here" notes, blockers, accomplishments
Weekly digest: Executive summary, week-over-week trends, health portfolio, dormant project alerts
Project deep dive: Full status for a single project

Here is what the daily standup looks like in your inbox:

Subject: [brain] Daily: 3 sessions, 892 msgs | Mar 12

Daily Standup - Wednesday, Mar 12

3 sessions across 2 projects yesterday (myapp, api-service) with 892 messages.

[ON TRACK] myapp
  Pick Up Here: Implement rate limiting on /api/upload endpoint
  In Progress: Auth refactor (80%), rate limiting (not started)
  Yesterday (2 sessions): Auth middleware refactor, API endpoint tests

[AT RISK] api-service
  Pick Up Here: Fix flaky CI tests blocking deploy
  Blockers: CI pipeline fails intermittently on integration tests
  Yesterday (1 session): Investigated CI timeout issue

No Activity Yesterday:
  docs - last session Mar 8

These are just starting points. Because the brain has full lossless context of every conversation across every project, what you can build on top of it is unlimited. Custom reports, cross-project analysis, pattern detection, decision audit trails. The complete history is there. How you use it is up to you.

Session Quality Scoring

Every session is automatically scored from -3 (worst) to +3 (best) based on content patterns, and tagged with labels like completions, decisions, debugging, corrections, rework, and frustrated.

This lets you do things no other tool supports:

"Show me sessions with the lowest quality scores"
"Which sessions had the most rework?"
"Compare my best and worst sessions - what patterns do you see?"
"What tags are most common in project A vs project B?"

The best sessions often have both positive and negative tags. "Frustrated + completions + decisions" means hard productive work. "Frustrated + rework + corrections" with no completions means a bad session. The brain tracks this automatically.

Human vs. Project Memory

Personal preferences (how you think, how you like to work, communication style) are stored globally and follow you across every project. Project-specific facts (this repo uses pytest, deploys through ArgoCD) are scoped to that project. You do not have to teach Claude who you are every time you switch repos.

Tags and Topic Discovery

Sessions are auto-tagged by topic during import (coding, finance, family, research, etc.). Browse your sessions by topic:

/brain-topics              # Show all tags with counts
/brain-topics finance      # Show all sessions tagged 'finance'

Edit tags anytime. Tell Claude "tag this session as finance, coding" and it updates directly. For bulk tagging, /brain-tag-review generates a spreadsheet you can edit and reimport.

Multi-Project Workflow

claude-brain works across multiple projects from a single database. Each project gets its own folder with a CLAUDE.md file. You can run multiple Claude Code sessions simultaneously in different projects, each with full brain access.

All sessions share the same database. If you make a decision in one project, Claude in the other project can find it via cross-project search.

To add a new project after initial setup:

cd ~/path/to/claude-brain
python3 scripts/add-project.py

The script creates the folder, CLAUDE.md, config entry, database registration, and MCP registration.

Multi-Machine Sync

claude-brain supports syncing between machines via Dropbox, OneDrive, Google Drive, or iCloud. Project files (scripts, hooks, config) sync via your cloud provider. The database stays on local disk (SQLite + cloud sync = corruption risk). Backups sync automatically. JSONL reconciliation at startup catches exchanges from other machines.

The setup script asks whether you want synced or local mode.

The MCP Server

claude-brain registers an MCP server with 11 read-only tools. Claude can query the brain directly mid-conversation without you doing anything:

Tool	What It Does
`search_transcripts`	Keyword search across all conversations
`search_semantic`	Meaning-based search using embeddings
`get_profile`	Your complete profile and preferences
`get_project_state`	Recent decisions and facts for a project
`lookup_decision`	Search locked decisions by keyword
`lookup_fact`	Project-specific facts by category
`get_session`	Full transcript of a specific session
`get_recent_summaries`	Recent session recaps
`get_status`	Database health check

14 Slash Commands

When you want direct control, type these in any Claude Code session:

Command	What It Does
`/brain-question`	Natural language question across the brain
`/brain-search`	Raw transcript search with timestamps
`/brain-history`	Session timeline, one line per session
`/brain-recap`	Progress report for a time range
`/brain-decide`	Decision lookup by number or keyword
`/brain-health`	Full 9-point diagnostic
`/brain-status`	Quick stats
`/brain-import`	Import conversations (Claude.ai, ChatGPT, Gemini)
`/brain-export`	Export brain data to text files
`/brain-topics`	Browse sessions by tag
`/brain-tag-review`	Batch tag review via spreadsheet
`/brain-questionnaire`	Fill out or update your profile
`/brain-setup`	Re-run setup to add projects
`/brain-consistency`	Automated consistency check

Auto-Update Notifications

The brain checks for updates automatically on every session start. When an update is available, you see:

Brain Update Available
To update: cd /your/install/path && git pull && pip3 install -r requirements.txt

Updates never happen automatically. You decide when to pull.

Real Numbers

This is not a prototype. It has been my primary development environment for over a month:

1,321 sessions
67,000+ messages
27,000+ semantic embeddings
9 projects
4 data sources (Claude Code, Claude.ai, ChatGPT, Gemini)
6 hooks, 11 MCP tools, 14 slash commands
CI green on macOS, Ubuntu, and Windows

Known Limitations

Limitation	Detail
Single-user	One person, one database. No multi-user support.
No auto-capture from claude.ai	Manual export + `/brain-import` required.
Semantic search cold-start	First query takes 4-5 seconds to load the model. Fast after that.
No cross-machine real-time DB sync	DB is local. Project files sync; database does not.

Install

One command:

curl -fsSL https://raw.githubusercontent.com/mikeadolan/claude-brain/main/install.sh | bash

The setup script walks you through everything: projects, database, hooks, MCP, email, health check.

Requirements: Python 3.10+, Claude Code 2.0+, pip3.

How I Built It

I have built websites, launched a venture-backed startup, and managed complex systems throughout my career. I was using Claude Code daily across multiple projects and the memory problem kept getting worse. Every session started from scratch. I was re-explaining the same context over and over. So I built the brain out of necessity.

It has been running for months. 67,000+ messages, every word from every conversation, every project, all in one local database. Been working great.

On this project I was the architect, project manager, code reviewer, and QA. Claude Code was my development partner. This is what building software looks like now.

DEV Community