Claude Self-Reflect

Claude forgets everything. This fixes that.

Single 44MB binary. No databases. No containers. No API keys required.

Install | How It Works | MCP Tools | FAQ

v9.2 — Episode Intelligence Sessions end as structured episodes; new sessions open with a CONTINUUM of where you left off. Provenance re-ranking, semantic intent routing, code graph, full-transcript recall, telemetry dashboard. Sub-millisecond search, ~150ms cached startup, 570+ tests, zero external dependencies. Release notes | Announcement

Table of Contents

• The Problem — Why Claude needs memory
• The Architecture — How CSR solves it
• The Pipeline — Progressive enrichment (9.3x improvement)
• Install — One command setup
• What You'll Ask — Natural language, no syntax
• Performance | MCP Tools | Hooks | CLI
• AI Narratives | Upgrading | Troubleshooting

The Forgetting Problem

Claude starts fresh every session. Solutions you found, architectures you designed, bugs you debugged — all gone.

Context retention drops below 20% after 10 sessions. CSR fixes this with a single binary that gives Claude perfect memory.

No special syntax. No commands. Install once, and past context appears automatically when you need it.

Explore the full documentation →

One Binary. 44MB.

Everything runs locally in a single process. No Docker, no database server, no API keys required.

• SQLite — storage for chunks, embeddings, enrichment state
• HNSW — sub-millisecond vector search (<1ms p95)
• FastEmbed — 384-dim local embeddings
• AST — code-aware search across 6 languages

6 hooks fire across the session lifecycle. 13 MCP tools for explicit search — including csr_code_graph, linking code symbols to the conversations that shaped them.

Explore the full documentation →

The Pipeline

Three layers progressively improve search quality from raw chunks to AI-enriched narratives — 9.3x improvement.

Higher quality context. Better decisions. Fewer tokens.

Explore the full documentation →

Install

curl -fsSL https://raw.githubusercontent.com/ramakay/claude-self-reflect/main/scripts/install.sh | sh

One command. Downloads the binary, runs setup, registers MCP server, installs 6 hooks. Restart Claude Code.

npm install -g claude-self-reflect

git clone https://github.com/ramakay/claude-self-reflect.git
cd claude-self-reflect/csr-engine
cargo build --release
cp target/release/csr-engine ~/.local/bin/
csr-engine setup

• "How did we solve re-renders on this component?"
• "What did we tell Joe about that commit?"
• "What were our frustrations with this approach?"
• "Where did we put the auth middleware config?"

No special syntax. No commands. CSR finds relevant past context and injects it automatically.

All tools include MCP tool annotations so Claude Code understands their safety characteristics.

All hooks use catch-all error handling. They never block Claude Code.

Transform raw conversations into rich, searchable narratives. Requires an Anthropic API key.

csr-engine daemon

Token transparency: Optional AI narratives (session briefings + story extraction) run claude -p against your existing Claude subscription — smallest available model, capped prompts, debounced, and skipped entirely when nothing changed. Every call — including failures and timeouts — is counted: csr-engine status shows calls and tokens spent today; cache read/creation tokens (often the majority of real usage) are tracked separately in the status JSON (cache_tokens_today / cache_tokens_total). Disable anytime with CSR_NO_AI_NARRATIVES=1; pin a model with CSR_NARRATIVE_MODEL=<model>.

csr-engine                     Start MCP server (default)
csr-engine setup               One-shot setup: import + MCP + hooks
csr-engine status              System status (JSON)
csr-engine status --compact    One-line statusline output
csr-engine daemon              Background enrichment daemon
csr-engine hook install --apply Install Claude Code hooks
csr-engine eval                Quick eval (5 tests)
csr-engine eval --full         Full eval (20 tests)
csr-engine quality <file>      AST-based code quality analysis

v8.0 replaces the Python/Docker stack with a single Rust binary.

docker compose down 2>/dev/null
curl -fsSL https://raw.githubusercontent.com/ramakay/claude-self-reflect/main/scripts/install.sh | sh

Your conversation data (~/.claude/projects/) is untouched. The new engine re-imports from the same JSONL files.

Full guide: Documentation

claude mcp remove claude-self-reflect
rm -rf ~/.claude-self-reflect/
rm ~/.local/bin/csr-engine
npm uninstall -g claude-self-reflect  # if installed via npm

• @TheGordon - Fixed timestamp parsing (#10)
• @akamalov - Ubuntu WSL insights
• @kylesnowschwartz - Security review (#6)

Documentation | npm | Issues | MIT License