Claude Self-Reflect
May 7, 2026 · View on GitHub
Claude forgets everything. This fixes that.
Single 44MB binary. No databases. No containers. No API keys required.
Install | How It Works | MCP Tools | FAQ
v8.0 — Complete Rust Rewrite The entire Python/Docker/Qdrant stack has been replaced with a single Rust binary. Sub-millisecond search, 93ms startup, 273 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.
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. 12 MCP tools for explicit search.
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.
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.
| Platform | Support |
|---|---|
| macOS (Apple Silicon) | Prebuilt binary |
| Linux x86_64 / WSL | Prebuilt binary |
| Linux ARM64 | Prebuilt binary |
| macOS (Intel) | Build from source |
Alternative: npm
npm install -g claude-self-reflect
Build from source
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
What You'll Ask — after install, just ask Claude naturally
- "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.
Performance — sub-millisecond search, 93ms startup
| Metric | Value |
|---|---|
| Cached startup | 93ms |
| Search latency (p95) | <1ms |
| Binary size | 44MB |
| Import speed | ~20 conversations/sec |
| Embedding | 0.73ms/text (batch) |
MCP Tools — 12 annotated tools available to Claude
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 |
Hooks — 6 session lifecycle hooks
| 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.
AI Narratives — optional 9.3x quality boost
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) |
CLI Reference
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
Upgrading from v7.x
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.
Troubleshooting
| 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: ~93ms) |
Full guide: Documentation
Uninstall
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
Contributors (v1–v7)
- @TheGordon - Fixed timestamp parsing (#10)
- @akamalov - Ubuntu WSL insights
- @kylesnowschwartz - Security review (#6)
Documentation | npm | Issues | MIT License