Claude Self-Reflect MCP
Local memory for Claude Code: a single binary indexes past conversations and injects relevant context into new sessions.
- 230 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The index stores conversations in full, including pasted code and keys that ended up in Claude Code history.
- Six hooks fire on every session event and add context to prompts.
- Optional AI narratives run `claude -p` on your subscription and spend its limits.
Install
- Works in
Manual install
curl -fsSL https://raw.githubusercontent.com/ramakay/claude-self-reflect/main/scripts/install.sh | shThe first README option. Alternatives: `npm install -g claude-self-reflect` followed by `csr-engine setup`, and building from source.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The index stores conversations in full, including pasted code and keys that ended up in Claude Code history.
- Six hooks fire on every session event and add context to prompts.
- Optional AI narratives run `claude -p` on your subscription and spend its limits.
This is third-party code. Review the repository files before installing.
What it does
Claude Self-Reflect is memory for Claude Code in a single `csr-engine` binary of about 44 MB. It indexes past conversations and returns the right context in new sessions. Storage is SQLite, search is HNSW and FastEmbed computes embeddings locally, so no Docker, database or API key is needed. Setup registers an MCP server and six lifecycle hooks: `SessionStart`, `UserPromptSubmit`, `PostToolUse`, `Stop`, `PreCompact` and `SessionEnd`. The hooks inject context before Claude answers and store session outcomes. For explicit search there are 15 MCP tools, including `csr_reflect_on_past`, `search_by_recency`, `csr_search_by_file`, `csr_why` and `store_reflection`. Optional AI narratives run `claude -p` on your subscription and improve search quality. The `CSR_NO_AI_NARRATIVES=1` variable turns them off.
Who it is for. Claude Code users on long projects who are tired of re-explaining decisions, bugs and code layout in every session.
Good fit when
- You ask how a re-render problem on a component was solved last time.
- You need conversations that touched a specific file or function (`csr_search_by_file`, `csr_code_graph`).
- A new session should open with the related context from earlier work.
- You need the origin of a decision: why an earlier approach was dropped (`csr_why`).
Not a fit when
- Agent conversations contain keys or private data that must not sit in a local index.
- You work outside Claude Code: hooks and import are built around its conversation history.
- The Claude subscription must not be spent on background AI narratives.
Example request
Find how we solved the auth problem in this project and show which sessions discussed it.MCP
- Transport
- stdio
- Authentication
- not required
Environment variables
`CSR_AUTO_SETUP`- A value of 1 lets a non-interactive install activate on its own.
`CSR_NO_AI_NARRATIVES`- A value of 1 disables the optional AI narratives.
`CSR_NARRATIVE_MODEL`- Pins the model used for AI narratives.
Limitations
Prebuilt binaries exist for macOS on Apple Silicon, Linux x86_64 and WSL, and Linux ARM64. On Intel macOS you build from source. Activation happens only with your consent; restart Claude Code afterwards. The first start is slow, about 14 seconds to rebuild the index. The index holds the full text of conversations from `~/.claude/projects/`. AI narratives spend subscription tokens; `csr-engine status` shows the counters.
How to disable. Run `claude mcp remove claude-self-reflect`, delete `~/.claude-self-reflect/` and `~/.local/bin/csr-engine`, and for an npm install run `npm uninstall -g claude-self-reflect`. Check and remove the hooks the setup added to the Claude Code settings.
FAQ
How do I install Claude Self-Reflect?
Run `curl -fsSL https://raw.githubusercontent.com/ramakay/claude-self-reflect/main/scripts/install.sh | sh`. The script downloads a SHA256-verified binary and asks for consent before activation. Restart Claude Code.
Are API keys or Docker needed?
No. Storage, search and embeddings run locally inside one process. Claude access (an Anthropic key or a subscription) is needed only for the optional AI narratives.
How do I install through npm?
`npm install -g claude-self-reflect`, then `csr-engine setup` as a separate step. Without that step the install does not touch `~/.claude`.
How do I turn AI narratives off?
Set `CSR_NO_AI_NARRATIVES=1`. You can pin a model with `CSR_NARRATIVE_MODEL`.
What does the SessionStart hook do?
It surfaces relevant past context at the start of a session. The other hooks inject context before a response, track file edits, store iteration and session learnings and back up state before context compaction.
Discussion
No questions or reviews yet.
Related
MCP serversA Claude Code plugin that keeps memory across sessions in one local file, with no database, cloud or API keys
A Claude Code plugin that catches your corrections in chat and, after review, writes them into CLAUDE.md and AGENTS.md
cc-lens
Claude Code Lens (cc-lens)
Local Claude Code analytics: a dashboard of sessions, tokens, cost and projects from your ~/.claude data, no cloud
An MCP server and CLI that find in Claude Code and Codex sessions why a file became what it is: who asked the agent what, when and what changed
A local web editor for Claude Code config: shows project sizes, deletes old chat histories and manages MCP servers
A skill for searching past sessions: a full-text index of Claude Code, Codex, pi and Grok chats in one SQLite database
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Claude Self-Reflect (this card) | no | not required | 230 | |
| Claude-Mem | no | 113,534 | another memory plugin for Claude Code; Claude Self-Reflect is a single local Rust binary with SQLite and HNSW and no external services | |
| Episodic Memory | no | 499 | an episodic memory plugin; this one has 15 MCP tools and 6 hooks, and search ties code to conversations |
README in short
The project replaced the Python and Docker stack of version 7 with one Rust binary. Conversation data in `~/.claude/projects/` stays untouched, and the index is rebuilt from the same JSONL files.