Claude Self-Reflect

Claude forgets everything. This fixes that.

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

Start Here — Full Documentation

Install | How It Works | MCP Tools | FAQ

The Forgetting Problem — context retention drops below 20% after 10 sessions

One Binary, 44MB — SQLite, HNSW, FastEmbed, AST, 6 hooks, 12 MCP tools

The Pipeline — 3 layers, quality score improves from 0.074 to 0.691

Install
What You'll Ask
How It Works
Performance
MCP Tools
Hooks
AI Narratives
CLI Reference
Upgrading from v7.x
Troubleshooting
Contributors

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.

How It Works

Everything runs locally in a single process. No network services, no containers.

SQLite stores chunks, embeddings, enrichment state
FastEmbed (all-MiniLM-L6-v2) generates 384-dim vectors locally
HNSW index provides sub-millisecond approximate nearest neighbor search
AST analysis extracts functions, types, imports from code (Rust, Python, TS, JS, Go, TSX)
3-layer enrichment progressively improves search quality from 0.074 to 0.691

*Layer 3 (AI Narratives) is optional and requires an Anthropic API key.

Performance

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 tools available to Claude when the MCP server is connected:

Tool	Description
`csr_reflect_on_past`	Semantic search across past conversations
`store_reflection`	Store insights for future retrieval
`csr_quick_check`	Fast existence check (count + top match)
`search_by_recency`	Time-constrained search ("last week")
`get_recent_work`	"What did we work on?" with session grouping
`get_timeline`	Activity timeline with statistics
`csr_search_by_file`	Find conversations that touched a file
`csr_search_by_concept`	Theme-based search ("security", "testing")
`csr_search_insights`	Aggregated patterns from search results
`csr_get_more`	Paginate through additional results
`get_full_conversation`	Retrieve complete JSONL conversation
`get_session_learnings`	Iteration-level memory for Ralph loops

Hooks

6 hooks fire at strategic moments during Claude Code sessions:

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)

Transform raw conversations into rich, searchable narratives with 9.3x better search quality. 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.

# Stop old services
docker compose down 2>/dev/null
claude mcp remove claude-self-reflect 2>/dev/null

# Install v8
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 troubleshooting 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

claude-self-reflect