claude-reflections

claude-reflections

Minimal conversation memory with vector search.

Overview

claude-reflections is a Claude Code plugin that indexes your past conversations and makes them searchable. The reflections skill is automatically triggered when you ask about past conversations, searches for relevant context, and reads the original JSONL files to provide detailed answers.

Key Features

• Zero infrastructure - embedded sqlite-vec database, no Docker or external services
• Reversible indexing - vectors point back to original JSONL files
• Per-project isolation - each project has its own database and state
• Incremental indexing - only processes new messages on each run
• Auto-indexing on search - search automatically indexes before searching
• Skill-based integration - automatically triggered by conversation questions

Architecture

flowchart LR
    A["Claude Code<br/>(user asks question)"] --> B["Skill<br/>(reflections)"]
    B --> C["CLI Commands<br/>(index + search)"]
    C --> D["sqlite-vec<br/>(vectors.db per project)"]

Skill workflow:

1. User asks: "How did we fix X?"
2. Skill determines project name from $PWD
3. Skill runs: uv run claude-reflections search "X"
4. CLI auto-indexes (incremental), then searches
5. Skill reads JSONL files at returned line numbers
6. Skill synthesizes answer from actual conversation content

Installation

Prerequisites

• Python 3.11+
• uv package manager

Automated Install (Recommended)

cd /path/to/claude-reflections
./install.sh

This will:

• Install Python dependencies (sqlite-vec, fastembed)
• Download the embedding model
• Create local marketplace at ~/.claude/plugins/local-marketplace
• Symlink plugin into marketplace
• Update ~/.claude/settings.json with plugin configuration

Vector databases are created automatically per-project on first use.

After installation:

1. Restart Claude Code
2. Verify installation:
   • Ask: "What skills are available?" → should show reflections
   • Ask: "What plugins are installed?" → should show claude-reflections
3. Try asking: "How did we implement X?" to trigger the skill

Manual Installation

If you prefer manual setup:

1. Install Python dependencies:

   cd /path/to/claude-reflections
   uv sync
   

2. Create local marketplace:

   mkdir -p ~/.claude/plugins/local-marketplace/.claude-plugin
   mkdir -p ~/.claude/plugins/local-marketplace/plugins
   
   # Symlink plugin
   ln -s /path/to/claude-reflections \
     ~/.claude/plugins/local-marketplace/plugins/claude-reflections
   

3. Create marketplace manifest:

   cat > ~/.claude/plugins/local-marketplace/.claude-plugin/marketplace.json << 'EOF'
   {
     "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
     "name": "local",
     "description": "Local development plugins",
     "owner": {"name": "your-name"},
     "plugins": [{
       "name": "claude-reflections",
       "description": "Minimal conversation memory with vector search",
       "version": "0.2.0",
       "source": "./plugins/claude-reflections",
       "category": "productivity"
     }]
   }
   EOF
   

4. Update Claude Code settings (~/.claude/settings.json):

   {
     "enabledPlugins": {
       "claude-reflections@local": true
     },
     "extraKnownMarketplaces": {
       "local": {
         "source": {
           "source": "directory",
           "path": "/home/YOUR_USER/.claude/plugins/local-marketplace"
         }
       }
     }
   }
   

5. Restart Claude Code for changes to take effect

Development Setup

For development without the marketplace:

# Clone and setup
cd ~/claude-reflections
uv sync --all-extras

# Install pre-commit hooks
uv run pre-commit install

Usage

Skill Usage (via Claude Code)

Once installed, the reflections skill is automatically available in Claude Code. The skill is triggered when you ask questions about past conversations:

Example questions:

• "How did we fix the authentication bug?"
• "What approach did we take for the API design?"
• "What have we discussed about X?"

The skill automatically:

1. Determines the current project from your working directory
2. Searches past conversations using vector similarity
3. Reads relevant JSONL files for full context
4. Provides synthesized answers based on actual conversations

Search automatically indexes before searching (incremental), ensuring results are always up-to-date.

See .claude/skills/reflections/SKILL.md for complete usage details.

CLI Commands

# List available projects
claude-reflections list

# Index a project (incremental)
claude-reflections index --project my-project

# Full reindex
claude-reflections index --project my-project --full

# Search
claude-reflections search "API design" --project my-project