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.

| Platform | Support | |----------|---------| | macOS (Apple Silicon) | Prebuilt binary | | Linux x86_64 / WSL | Prebuilt binary | | Linux ARM64 | Prebuilt binary | | macOS (Intel) | Build from source |

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.

| Metric | Value | |--------|-------| | Cached startup | ~150ms (p50, 54K-chunk index) | | Search latency (p95) | <1ms | | Binary size | 44MB | | Import speed | ~20 conversations/sec | | Embedding | 0.73ms/text (batch) |

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

| Tool | Description | Safety | |------|-------------|--------| | csr_reflect_on_past | Semantic search across past conversations | read-only | | store_reflection | Store insights for future retrieval | writes | | csr_quick_check | Fast existence check (count + top match) | read-only | | search_by_recency | Time-constrained search ("last week") | read-only | | get_recent_work | "What did we work on?" with session grouping | read-only | | get_timeline | Activity timeline with statistics | read-only | | csr_search_by_file | Find conversations that touched a file | read-only | | csr_search_by_concept | Theme-based search ("security", "testing") | read-only | | csr_search_insights | Aggregated patterns from search results | read-only | | csr_get_more | Paginate through additional results | read-only | | get_full_conversation | Retrieve complete JSONL conversation | read-only | | get_session_learnings | Iteration-level memory for Ralph loops | read-only | | csr_code_graph | Which conversations shaped a function or file (AST anchors) | read-only | | csr_why | Provenance chain — why does this code/decision exist | read-only | | csr_resolve | Record verified verdicts (resolved/still_open/regressed) on chunks | writes |

| Hook | What it does | |------|-------------| | SessionStart | Surfaces relevant past context at conversation start | | UserPromptSubmit | Predicts and injects context before Claude responds | | PostToolUse | Tracks file edits with session-scoped dedup | | Stop | Stores iteration learnings, detects stuck patterns | | PreCompact | Backs up state before context compaction | | SessionEnd | Stores session narrative for future retrieval |

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

| Metric | Without | With AI Narratives | |--------|---------|-------------------| | Search quality | 0.074 | 0.691 (9.3x) | | Token compression | 100% | 18% (82% reduction) | | Cost per conversation | - | ~$0.012 (Batch API) |

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.

| Symptom | Fix | |---------|-----| | No search results | Run csr-engine setup | | MCP tools not available | Run csr-engine setup, restart Claude Code | | "spawn ENOENT" in MCP | Ensure csr-engine is in PATH | | Slow first startup | Normal (~14s for index rebuild, subsequent: ~150ms) |

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