GitHub - ramakay/claude-self-reflect: Claude forgets everything. This fixes that. 🔗 www.npmjs.com/package/claude-self-reflect

5 min read Original article ↗

Claude Self-Reflect

npm downloads MIT Release Claude Code MCP Rust Local First stars

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

CSR Demo — Setup, Search, and Hooks

Table of Contents

The Forgetting Problem

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.

Architecture — 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.


Explore the full documentation →

The Pipeline

The Pipeline — 3 layers, 9.3x improvement

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.

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.

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)

Documentation | npm | Issues | MIT License