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 | Paper | FAQ

v9.4 — Multi-Source Memory CSR now remembers more than transcripts: task outcomes, plan documents, and a cross-project session registry — each absorbed at the lifecycle stage it belongs to. Episodes carry real task state again (Claude Code's TodoWrite→TaskCreate rename had silently emptied them — found, fixed, and guarded with schema-miss telemetry). Sub-millisecond search, ~150ms cached startup, 720+ tests, zero external dependencies. Release notes

Table of Contents

• The Problem — Why Claude needs memory
• The Architecture — How CSR solves it
• The Pipeline — Progressive enrichment (9.3x improvement)
• The Paper — The research behind the retrieval design (preprint)
• Install — One-command install, consent-first activation
• 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. 15 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 →

The Paper

CSR's retrieval design is documented in a research preprint, measured on the system's own development history:

Similarity Drowns Intent: Three-Trace Sagas and Reinstatement Recall for Provenance in Agentic Software Construction 2026 — PDF

Ask a memory system "why did we drop Qdrant?" and cosine similarity returns a recording of you asking that question earlier, at 0.984 similarity. The decision itself scores lower than its own echoes. The paper measures this failure, the multi-hop walk built to counter it (+53% and +47% ground-truth session coverage over one-shot kNN on two corpora, pre-registered gates, blind cross-vendor judging), and a second finding that fell out of evaluation: a self-recording memory system ingests its own eval dialogue and drowns the answers it's being tested on. It also keeps its negative results — a pre-registered ratification-weighting hypothesis died at ρ≈0 and forbade an entire staleness design.

Install

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

Downloads the binary (SHA256-verified), then asks before activating. Setup — which registers the MCP server, installs 6 hooks, and imports your conversations — only runs with your consent. Restart Claude Code after.

Non-interactive installs never activate on their own: set CSR_AUTO_SETUP=1 to opt in, or run csr-engine setup yourself.

npm install -g claude-self-reflect
csr-engine setup   # activation is a separate, explicit step

By default npm install only downloads the checksummed binary — it does not touch ~/.claude or index conversations. Activation happens when you run csr-engine setup, or set CSR_AUTO_SETUP=1 during install to opt in.

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