Persistent memory system for Claude Code - remembers context across sessions
npm install cc-brain
Persistent memory for Claude Code
Remember context across sessions
Installation -
How It Works -
Architecture -
Skills -
CLI
---
Claude Code sessions are ephemeral. When context fills up or you start a new session, everything is forgotten. Your preferences, project decisions, debugging history -- gone.
cc-brain creates a persistent memory layer that:
- Loads your profile and project context on every session
- Saves important learnings before context compaction
- Searches past sessions for decisions and context
---
bash
npx cc-brain install
`$3
`bash
npm install -g cc-brain
cc-brain install
`$3
`bash
bun install -g cc-brain
cc-brain install
`$3
`bash
npm install -g @tripzcodes/cc-brain --registry=https://npm.pkg.github.com
cc-brain install
`$3
`bash
npx cc-brain@latest install
`---
How It Works
`
~/.claude/brain/
├── user.md # Your profile (always loaded)
├── preferences.md # Code preferences (always loaded)
└── projects/{id}/
├── context.md # Current project state
└── archive/ # Session history
└── 2025-01-31-143052.md
`$3
| Tier | Content | Limit | Loaded |
|:----:|---------|:-----:|:------:|
| T1 | User identity & preferences | 80 lines | Always |
| T2 | Project context | 120 lines | Current project |
| T3 | Archive history | Unlimited | On-demand |
$3
`
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Session Start │────>│ Brain Loaded │────>│ You Work... │
└─────────────────┘ └─────────────────┘ └────────┬────────┘
│
┌─────────────────┐ ┌─────────────────┐ │
│ Next Session │<────│ Brain Saved │<─────────────┘
└─────────────────┘ └─────────────────┘
(before compaction)
`---
Architecture
`
┌──────────────────────────────────────────────────────┐
│ Claude Code │
│ │
│ SessionStart hook ──> loader.js ──> XML output │
│ │ │
│ ├── T1: │
│ ├── T1: │
│ ├── T2: │
│ └── T3: │
│ │
│ PreCompact hook ──> saver.js ──> atomic writes │
│ │ │
│ ├── validates input shape │
│ ├── enforces line limits │
│ ├── warns at 80% capacity │
│ └── safeWriteFileSync() │
│ │
│ /recall skill ──> recall.js ──> scored results │
│ │ │
│ ├── regex with safe fallback │
│ ├── header match scoring │
│ └── TTY-aware color output │
└──────────────────────────────────────────────────────┘
│
v
~/.claude/brain/ (persistent)
`$3
1. SessionStart -
loader.js loads T1 + T2 into XML-tagged sections, auto-prunes archives older than 90 days
2. PreCompact - Agent analyzes session, calls saver.js with structured JSON payload
3. Manual - /save skill triggers the saver, /recall searches the archive
4. Archive - Each save creates YYYY-MM-DD-HHMMSS.md (one file per session, no collisions)$3
- Atomic writes - All file writes use temp file + rename to prevent corruption
- Cross-runtime - Works in both Node (>=18) and Bun via
isMainModule() helper
- Hook preservation - Install/uninstall detect cc-brain hooks by content matching, never overwrite user's other hooks
- XML output - Loader wraps content in semantic tags (, , ) for reliable Claude parsing
- Input validation - Saver checks shape, key names, and types before writing---
Skills
Skills are installed to
~/.claude/skills/ and available in Claude Code:| Skill | Description |
|-------|-------------|
|
/save | Save session context to brain |
| /recall | Search archive for past context |
| /brain | View current brain state |Skills are automatically discovered by Claude Code after installation.
---
CLI
`bash
Setup
cc-brain install # Install hooks + skills
cc-brain uninstall # Remove hooks + skills (preserves brain data)
cc-brain uninstall --purge # Remove everything including brain dataSearch & Archive
cc-brain recall "query" # Search archive (scored results)
cc-brain recall "query" --context # Show surrounding lines
cc-brain archive list # List entries
cc-brain archive stats # Statistics (avg size, time span)
cc-brain archive prune --keep 20Project Identity
cc-brain project-id --init # Create stable .brain-idManual Save
cc-brain save --dry-run --json '{"t2": {"focus": "testing"}}'
cc-brain save --json '{"t3": "Added search functionality"}'
`---
Project Structure
`
src/
utils.js Shared utilities (safeWriteFileSync, isMainModule)
loader.js Loads T1+T2 into XML context, auto-prunes archive
saver.js Structured saver with validation, limits, atomic writes
recall.js Scored archive search with safe regex and color detection
archive.js Archive management (list, prune, stats)
project-id.js Stable project identity (.brain-id)
saver-prompt.md Instructions for saving
bin/
cc-brain.js CLI entry point with fast runtime detection
hooks/
hooks.json Hook configuration (SessionStart, PreCompact)
skills/
save.md /save skill
recall.md /recall skill
brain.md /brain skill
scripts/
install.js Install hooks + skills to ~/.claude/
uninstall.js Remove hooks + skills (--purge for full removal)
plugin.json Plugin manifest
`---
Features
- Persistent memory across sessions and compactions
- Structured saving with JSON validation and dry-run preview
- Input validation with shape checking, key allowlist, type enforcement
- Capacity warnings at 80% of line limits before rejecting
- Atomic file writes via temp + rename to prevent corruption
- Scored search with regex safe fallback and header-weighted ranking
- Smart color output that detects TTY and respects NO_COLOR
- Auto-prune removes archive entries older than 90 days
- Hook-safe install that merges without clobbering user config
- Cross-runtime support for Node (>=18) and Bun
- Stable project identity via
.brain-id that survives renames---
Project Identity
By default, projects are identified by directory name. For stable identity that survives renames:
`bash
cc-brain project-id --init
`Creates a
.brain-id file with a UUID. Commit it to your repo.---
Uninstall
`bash
cc-brain uninstall # Remove hooks, keep data
cc-brain uninstall --purge # Remove everything
``---
- Node.js >= 18 or Bun
- Claude Code
---
MIT - tripzcodes