{
  "markdown": "# Claude Self-Reflect\n\n<div align=\"center\">\n\n<img src=\"docs-site/public/favicon.svg\" alt=\"Claude Self-Reflect\" width=\"80\" height=\"80\" />\n\n[![npm](https://badge.fury.io/js/claude-self-reflect.svg)](https://www.npmjs.com/package/claude-self-reflect) [![downloads](https://img.shields.io/npm/dm/claude-self-reflect.svg)](https://www.npmjs.com/package/claude-self-reflect) [![MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Release](https://github.com/ramakay/claude-self-reflect/actions/workflows/release.yml/badge.svg)](https://github.com/ramakay/claude-self-reflect/releases/latest) [![Claude Code](https://img.shields.io/badge/Claude%20Code-6B4FBB)](https://github.com/anthropics/claude-code) [![MCP](https://img.shields.io/badge/MCP-FF6B6B)](https://modelcontextprotocol.io/) [![Rust](https://img.shields.io/badge/Rust-000000?logo=rust)](https://github.com/ramakay/claude-self-reflect/tree/main/csr-engine) [![Local First](https://img.shields.io/badge/Local-4A90E2)](https://github.com/ramakay/claude-self-reflect) [![stars](https://img.shields.io/github/stars/ramakay/claude-self-reflect.svg?style=social)](https://github.com/ramakay/claude-self-reflect/stargazers)\n\n**Claude forgets everything. This fixes that.**\n\nSingle 44MB binary. No databases. No containers. No API keys required.\n\n[Install](#install) | [How It Works](#how-it-works) | [MCP Tools](#mcp-tools) | [Paper](docs/plans/annaswamy-2026-similarity-drowns-intent.pdf) | [FAQ](https://ramakay.github.io/claude-self-reflect/#/docs/troubleshooting)\n\n> **v9.4 — Multi-Source Memory**\n> 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.\n> Episodes carry real task state again (Claude Code's TodoWrite→TaskCreate rename had silently emptied them — found, fixed, and guarded with schema-miss telemetry).\n> Sub-millisecond search, ~150ms cached startup, 720+ tests, zero external dependencies.\n> [Release notes](https://github.com/ramakay/claude-self-reflect/releases/tag/v9.4.0)\n\n<img src=\"docs-site/public/images/csr-demo.gif\" alt=\"CSR Demo — Setup, Search, and Hooks\" width=\"800\" />\n\n</div>\n\n## Table of Contents\n\n- [The Problem](#the-forgetting-problem) — Why Claude needs memory\n- [The Architecture](#one-binary-44mb) — How CSR solves it\n- [The Pipeline](#the-pipeline) — Progressive enrichment (9.3x improvement)\n- [The Paper](#the-paper) — The research behind the retrieval design (preprint)\n- [Install](#install) — One-command install, consent-first activation\n- [What You'll Ask](#what-youll-ask) — Natural language, no syntax\n- [Performance](#performance) | [MCP Tools](#mcp-tools) | [Hooks](#hooks) | [CLI](#cli-reference)\n- [AI Narratives](#ai-narratives-optional) | [Upgrading](#upgrading-from-v7x) | [Troubleshooting](#troubleshooting)\n\n---\n\n## The Forgetting Problem\n\n<a href=\"https://ramakay.github.io/claude-self-reflect/\">\n<picture>\n  <source media=\"(prefers-color-scheme: dark)\" srcset=\"docs-site/public/images/card-01-hook-dark.png\" />\n  <img align=\"right\" src=\"docs-site/public/images/card-01-hook-light.png\" alt=\"The Forgetting Problem\" width=\"420\" />\n</picture>\n</a>\n\nClaude starts fresh every session. Solutions you found, architectures you designed, bugs you debugged — all gone.\n\nContext retention drops below **20% after 10 sessions**. CSR fixes this with a single binary that gives Claude perfect memory.\n\nNo special syntax. No commands. Install once, and past context appears automatically when you need it.\n\n<br clear=\"both\" />\n\n> **[Explore the full documentation →](https://ramakay.github.io/claude-self-reflect/)**\n\n---\n\n## One Binary. 44MB.\n\n<a href=\"https://ramakay.github.io/claude-self-reflect/#/docs/architecture\">\n<picture>\n  <source media=\"(prefers-color-scheme: dark)\" srcset=\"docs-site/public/images/card-02-arch-dark.png\" />\n  <img align=\"right\" src=\"docs-site/public/images/card-02-arch-light.png\" alt=\"Architecture — One Binary, 44MB\" width=\"420\" />\n</picture>\n</a>\n\nEverything runs locally in a single process. No Docker, no database server, no API keys required.\n\n- **SQLite** — storage for chunks, embeddings, enrichment state\n- **HNSW** — sub-millisecond vector search (<1ms p95)\n- **FastEmbed** — 384-dim local embeddings\n- **AST** — code-aware search across 6 languages\n\n**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.\n\n<br clear=\"both\" />\n\n> **[Explore the full documentation →](https://ramakay.github.io/claude-self-reflect/#/docs/architecture)**\n\n---\n\n## The Pipeline\n\n<a href=\"https://ramakay.github.io/claude-self-reflect/#/docs/enrichment\">\n<picture>\n  <source media=\"(prefers-color-scheme: dark)\" srcset=\"docs-site/public/images/card-03-pipeline-dark.png\" />\n  <img align=\"right\" src=\"docs-site/public/images/card-03-pipeline-light.png\" alt=\"The Pipeline — 3 layers, 9.3x improvement\" width=\"420\" />\n</picture>\n</a>\n\nThree layers progressively improve search quality from raw chunks to AI-enriched narratives — **9.3x improvement**.\n\nHigher quality context. Better decisions. Fewer tokens.\n\n<br clear=\"both\" />\n\n> **[Explore the full documentation →](https://ramakay.github.io/claude-self-reflect/#/docs/enrichment)**\n\n---\n\n## The Paper\n\n<a href=\"docs/plans/annaswamy-2026-similarity-drowns-intent.pdf\">\n<picture>\n  <source media=\"(prefers-color-scheme: dark)\" srcset=\"docs-site/public/images/card-04-paper-dark.png\" />\n  <img align=\"right\" src=\"docs-site/public/images/card-04-paper-light.png\" alt=\"Three-Trace Sagas — intent, deliberation, artifact\" width=\"420\" />\n</picture>\n</a>\n\nCSR's retrieval design is documented in a research preprint, measured on the system's own development history:\n\n> **Similarity Drowns Intent: Three-Trace Sagas and Reinstatement Recall for Provenance in Agentic Software Construction**\n> 2026 — [PDF](docs/plans/annaswamy-2026-similarity-drowns-intent.pdf)\n\nAsk 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.\n\n<br clear=\"both\" />\n\n---\n\n## Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/ramakay/claude-self-reflect/main/scripts/install.sh | sh\n```\n\nDownloads 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.\n\nNon-interactive installs never activate on their own: set `CSR_AUTO_SETUP=1` to opt in, or run `csr-engine setup` yourself.\n\n| Platform | Support |\n|----------|---------|\n| macOS (Apple Silicon) | Prebuilt binary |\n| Linux x86_64 / WSL | Prebuilt binary |\n| Linux ARM64 | Prebuilt binary |\n| macOS (Intel) | Build from source |\n\n<details>\n<summary>Alternative: npm</summary>\n\n```bash\nnpm install -g claude-self-reflect\ncsr-engine setup   # activation is a separate, explicit step\n```\n\nBy 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.\n\n</details>\n\n<details>\n<summary>Build from source</summary>\n\n```bash\ngit clone https://github.com/ramakay/claude-self-reflect.git\ncd claude-self-reflect/csr-engine\ncargo build --release\ncp target/release/csr-engine ~/.local/bin/\ncsr-engine setup\n```\n\n</details>\n\n<details>\n<summary><strong>What You'll Ask</strong> — after install, just ask Claude naturally</summary>\n\n- *\"How did we solve re-renders on this component?\"*\n- *\"What did we tell Joe about that commit?\"*\n- *\"What were our frustrations with this approach?\"*\n- *\"Where did we put the auth middleware config?\"*\n\nNo special syntax. No commands. CSR finds relevant past context and injects it automatically.\n\n</details>\n\n<details>\n<summary><strong>Performance</strong> — sub-millisecond search, ~150ms cached startup</summary>\n\n| Metric | Value |\n|--------|-------|\n| **Cached startup** | ~150ms (p50, 54K-chunk index) |\n| **Search latency (p95)** | <1ms |\n| **Binary size** | 44MB |\n| **Import speed** | ~20 conversations/sec |\n| **Embedding** | 0.73ms/text (batch) |\n\n</details>\n\n<details>\n<summary><strong>MCP Tools</strong> — 15 annotated tools available to Claude</summary>\n\nAll tools include [MCP tool annotations](https://spec.modelcontextprotocol.io/specification/2025-11-05/server/tools/#annotations) so Claude Code understands their safety characteristics.\n\n| Tool | Description | Safety |\n|------|-------------|--------|\n| `csr_reflect_on_past` | Semantic search across past conversations | read-only |\n| `store_reflection` | Store insights for future retrieval | **writes** |\n| `csr_quick_check` | Fast existence check (count + top match) | read-only |\n| `search_by_recency` | Time-constrained search (\"last week\") | read-only |\n| `get_recent_work` | \"What did we work on?\" with session grouping | read-only |\n| `get_timeline` | Activity timeline with statistics | read-only |\n| `csr_search_by_file` | Find conversations that touched a file | read-only |\n| `csr_search_by_concept` | Theme-based search (\"security\", \"testing\") | read-only |\n| `csr_search_insights` | Aggregated patterns from search results | read-only |\n| `csr_get_more` | Paginate through additional results | read-only |\n| `get_full_conversation` | Retrieve complete JSONL conversation | read-only |\n| `get_session_learnings` | Iteration-level memory for Ralph loops | read-only |\n| `csr_code_graph` | Which conversations shaped a function or file (AST anchors) | read-only |\n| `csr_why` | Provenance chain — why does this code/decision exist | read-only |\n| `csr_resolve` | Record verified verdicts (resolved/still_open/regressed) on chunks | **writes** |\n\n</details>\n\n<details>\n<summary><strong>Hooks</strong> — 6 session lifecycle hooks</summary>\n\n| Hook | What it does |\n|------|-------------|\n| **SessionStart** | Surfaces relevant past context at conversation start |\n| **UserPromptSubmit** | Predicts and injects context before Claude responds |\n| **PostToolUse** | Tracks file edits with session-scoped dedup |\n| **Stop** | Stores iteration learnings, detects stuck patterns |\n| **PreCompact** | Backs up state before context compaction |\n| **SessionEnd** | Stores session narrative for future retrieval |\n\nAll hooks use catch-all error handling. They never block Claude Code.\n\n</details>\n\n<details>\n<summary><strong>AI Narratives</strong> — optional 9.3x quality boost</summary>\n\nTransform raw conversations into rich, searchable narratives. Requires an Anthropic API key.\n\n```bash\ncsr-engine daemon\n```\n\n| Metric | Without | With AI Narratives |\n|--------|---------|-------------------|\n| Search quality | 0.074 | 0.691 (9.3x) |\n| Token compression | 100% | 18% (82% reduction) |\n| Cost per conversation | - | ~$0.012 (Batch API) |\n\n> **Token transparency:** Optional AI narratives (session briefings + story extraction) run\n> `claude -p` against your existing Claude subscription — smallest available model, capped\n> prompts, debounced, and skipped entirely when nothing changed. Every call — including failures and timeouts — is counted:\n> `csr-engine status` shows calls and tokens spent today; cache read/creation tokens (often\n> the majority of real usage) are tracked separately in the status JSON (`cache_tokens_today` /\n> `cache_tokens_total`). Disable anytime with\n> `CSR_NO_AI_NARRATIVES=1`; pin a model with `CSR_NARRATIVE_MODEL=<model>`.\n\n</details>\n\n<details>\n<summary><strong>CLI Reference</strong></summary>\n\n```\ncsr-engine                     Start MCP server (default)\ncsr-engine setup               One-shot setup: import + MCP + hooks\ncsr-engine status              System status (JSON)\ncsr-engine status --compact    One-line statusline output\ncsr-engine daemon              Background enrichment daemon\ncsr-engine hook install --apply Install Claude Code hooks\ncsr-engine eval                Quick eval (5 tests)\ncsr-engine eval --full         Full eval (20 tests)\ncsr-engine quality <file>      AST-based code quality analysis\n```\n\n</details>\n\n<details>\n<summary><strong>Upgrading from v7.x</strong></summary>\n\nv8.0 replaces the Python/Docker stack with a single Rust binary.\n\n```bash\ndocker compose down 2>/dev/null\ncurl -fsSL https://raw.githubusercontent.com/ramakay/claude-self-reflect/main/scripts/install.sh | sh\n```\n\nYour conversation data (`~/.claude/projects/`) is untouched. The new engine re-imports from the same JSONL files.\n\n</details>\n\n<details>\n<summary><strong>Troubleshooting</strong></summary>\n\n| Symptom | Fix |\n|---------|-----|\n| No search results | Run `csr-engine setup` |\n| MCP tools not available | Run `csr-engine setup`, restart Claude Code |\n| \"spawn ENOENT\" in MCP | Ensure `csr-engine` is in PATH |\n| Slow first startup | Normal (~14s for index rebuild, subsequent: ~150ms) |\n\nFull guide: [Documentation](https://ramakay.github.io/claude-self-reflect/#/docs/troubleshooting)\n\n</details>\n\n<details>\n<summary><strong>Uninstall</strong></summary>\n\n```bash\nclaude mcp remove claude-self-reflect\nrm -rf ~/.claude-self-reflect/\nrm ~/.local/bin/csr-engine\nnpm uninstall -g claude-self-reflect  # if installed via npm\n```\n\n</details>\n\n<details>\n<summary><strong>Contributors (v1–v7)</strong></summary>\n\n- **[@TheGordon](https://github.com/TheGordon)** - Fixed timestamp parsing (#10)\n- **[@akamalov](https://github.com/akamalov)** - Ubuntu WSL insights\n- **[@kylesnowschwartz](https://github.com/kylesnowschwartz)** - Security review (#6)\n\n</details>\n\n---\n\n[Documentation](https://ramakay.github.io/claude-self-reflect/) | [npm](https://www.npmjs.com/package/claude-self-reflect) | [Issues](https://github.com/ramakay/claude-self-reflect/issues) | MIT License\n",
  "bytes": 14328,
  "sha": "f2e21662e12ae479bab5327e1459003d5248d503d81e8b7a893a57310bb30bd1",
  "repo_slug": "ramakay/claude-self-reflect",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_ramakay_claude_self_reflect_claude_self__cfc3292e/readme"
}