{"id":29806270,"url":"https://github.com/ramakay/claude-self-reflect","last_synced_at":"2026-05-03T06:02:45.027Z","repository":{"id":306356323,"uuid":"1025921796","full_name":"ramakay/claude-self-reflect","owner":"ramakay","description":"Enable claude to self reflect.","archived":false,"fork":false,"pushed_at":"2025-07-25T06:15:30.000Z","size":818,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-25T07:37:24.476Z","etag":null,"topics":["ai-memory","claude","claude-desktop","conversation-memory","mcp","qdrant","semantic-search","vector-search"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ramakay.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-25T03:13:42.000Z","updated_at":"2025-07-25T06:15:27.000Z","dependencies_parsed_at":"2025-07-25T07:37:28.290Z","dependency_job_id":"b011539c-bafb-402f-914e-a9cb54c73248","html_url":"https://github.com/ramakay/claude-self-reflect","commit_stats":null,"previous_names":["ramakay/claude-self-reflect"],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/ramakay/claude-self-reflect","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramakay%2Fclaude-self-reflect","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramakay%2Fclaude-self-reflect/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramakay%2Fclaude-self-reflect/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramakay%2Fclaude-self-reflect/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ramakay","download_url":"https://codeload.github.com/ramakay/claude-self-reflect/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramakay%2Fclaude-self-reflect/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267397378,"owners_count":24080884,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-27T02:00:11.917Z","response_time":82,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-memory","claude","claude-desktop","conversation-memory","mcp","qdrant","semantic-search","vector-search"],"created_at":"2025-07-28T14:05:55.705Z","updated_at":"2026-05-03T06:02:45.015Z","avatar_url":"https://github.com/ramakay.png","language":"Python","funding_links":[],"categories":["Tools \u0026 Utilities","Project \u0026 Knowledge Management"],"sub_categories":["Other IDEs"],"readme":"# Claude Self-Reflect\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"docs-site/public/favicon.svg\" alt=\"Claude Self-Reflect\" width=\"80\" height=\"80\" /\u003e\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) | [FAQ](https://ramakay.github.io/claude-self-reflect/#/docs/troubleshooting)\n\n\u003c/div\u003e\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- [Install](#install) — One command setup\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\u003ca href=\"https://ramakay.github.io/claude-self-reflect/\"\u003e\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs-site/public/images/card-01-hook-dark.png\" /\u003e\n  \u003cimg align=\"right\" src=\"docs-site/public/images/card-01-hook-light.png\" alt=\"The Forgetting Problem\" width=\"420\" /\u003e\n\u003c/picture\u003e\n\u003c/a\u003e\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\u003cbr clear=\"both\" /\u003e\n\n\u003e **[Explore the full documentation →](https://ramakay.github.io/claude-self-reflect/)**\n\n---\n\n## One Binary. 44MB.\n\n\u003ca href=\"https://ramakay.github.io/claude-self-reflect/#/docs/architecture\"\u003e\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs-site/public/images/card-02-arch-dark.png\" /\u003e\n  \u003cimg align=\"right\" src=\"docs-site/public/images/card-02-arch-light.png\" alt=\"Architecture — One Binary, 44MB\" width=\"420\" /\u003e\n\u003c/picture\u003e\n\u003c/a\u003e\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 (\u003c1ms p95)\n- **FastEmbed** — 384-dim local embeddings\n- **AST** — code-aware search across 6 languages\n\n**6 hooks** fire across the session lifecycle. **12 MCP tools** for explicit search.\n\n\u003cbr clear=\"both\" /\u003e\n\n\u003e **[Explore the full documentation →](https://ramakay.github.io/claude-self-reflect/#/docs/architecture)**\n\n---\n\n## The Pipeline\n\n\u003ca href=\"https://ramakay.github.io/claude-self-reflect/#/docs/enrichment\"\u003e\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs-site/public/images/card-03-pipeline-dark.png\" /\u003e\n  \u003cimg align=\"right\" src=\"docs-site/public/images/card-03-pipeline-light.png\" alt=\"The Pipeline — 3 layers, 9.3x improvement\" width=\"420\" /\u003e\n\u003c/picture\u003e\n\u003c/a\u003e\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\u003cbr clear=\"both\" /\u003e\n\n\u003e **[Explore the full documentation →](https://ramakay.github.io/claude-self-reflect/#/docs/enrichment)**\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\nOne command. Downloads the binary, runs setup, registers MCP server, installs 6 hooks. Restart Claude Code.\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\u003cdetails\u003e\n\u003csummary\u003eAlternative: npm\u003c/summary\u003e\n\n```bash\nnpm install -g claude-self-reflect\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eBuild from source\u003c/summary\u003e\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\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWhat You'll Ask\u003c/strong\u003e — after install, just ask Claude naturally\u003c/summary\u003e\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\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003ePerformance\u003c/strong\u003e — sub-millisecond search, 93ms startup\u003c/summary\u003e\n\n| Metric | Value |\n|--------|-------|\n| **Cached startup** | 93ms |\n| **Search latency (p95)** | \u003c1ms |\n| **Binary size** | 44MB |\n| **Import speed** | ~20 conversations/sec |\n| **Embedding** | 0.73ms/text (batch) |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eMCP Tools\u003c/strong\u003e — 12 tools available to Claude\u003c/summary\u003e\n\n| Tool | Description |\n|------|-------------|\n| `csr_reflect_on_past` | Semantic search across past conversations |\n| `store_reflection` | Store insights for future retrieval |\n| `csr_quick_check` | Fast existence check (count + top match) |\n| `search_by_recency` | Time-constrained search (\"last week\") |\n| `get_recent_work` | \"What did we work on?\" with session grouping |\n| `get_timeline` | Activity timeline with statistics |\n| `csr_search_by_file` | Find conversations that touched a file |\n| `csr_search_by_concept` | Theme-based search (\"security\", \"testing\") |\n| `csr_search_insights` | Aggregated patterns from search results |\n| `csr_get_more` | Paginate through additional results |\n| `get_full_conversation` | Retrieve complete JSONL conversation |\n| `get_session_learnings` | Iteration-level memory for Ralph loops |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eHooks\u003c/strong\u003e — 6 session lifecycle hooks\u003c/summary\u003e\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\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAI Narratives\u003c/strong\u003e — optional 9.3x quality boost\u003c/summary\u003e\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\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCLI Reference\u003c/strong\u003e\u003c/summary\u003e\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 \u003cfile\u003e      AST-based code quality analysis\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eUpgrading from v7.x\u003c/strong\u003e\u003c/summary\u003e\n\nv8.0 replaces the Python/Docker stack with a single Rust binary.\n\n```bash\ndocker compose down 2\u003e/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\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTroubleshooting\u003c/strong\u003e\u003c/summary\u003e\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: ~93ms) |\n\nFull guide: [Documentation](https://ramakay.github.io/claude-self-reflect/#/docs/troubleshooting)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eUninstall\u003c/strong\u003e\u003c/summary\u003e\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\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eContributors (v1–v7)\u003c/strong\u003e\u003c/summary\u003e\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\u003c/details\u003e\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framakay%2Fclaude-self-reflect","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Framakay%2Fclaude-self-reflect","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framakay%2Fclaude-self-reflect/lists"}