cc-recall

Recall your Claude Code conversations instantly with semantic search, and synthesize insights automatically from your coding sessions.

Features

Search

• 🔍 Semantic Search: Find relevant conversations using natural language queries
• 📚 Auto-Indexing: Automatically indexes new conversations when Claude Code sessions end
• 🏠 Local & Private: All embeddings and data stay on your machine
• ⚡ Fast: Vector search powered by ChromaDB
• 🎯 Accurate: Uses state-of-the-art sentence-transformers model
• 💬 Slash Command: Search directly within Claude Code using /search-history

Synthesis

• 🧠 Automated Insights: Automatically captures patterns, decisions, and learnings from conversations
• 📝 Markdown Memory: Stores insights as readable markdown files (no vector DB needed)
• 🔄 Three-Way Synthesis: Auto-synthesis every 20 prompts, AI-suggested at key moments, manual /synthesize command
• 📈 Progressive Disclosure: Lightweight index with details on demand
• 🚀 Backfill: Process all historical conversations with Haiku for speed

Installation

Prerequisites

• Python 3.10+
• uv package manager

Install uv (if not already installed)

curl -LsSf https://astral.sh/uv/install.sh | sh

Clone and Install

git clone <your-repo-url>
cd cc-recall
chmod +x install.sh
./install.sh

This will:

• Install dependencies with uv
• Index your existing chat history
• Install the /search-history and /synthesize slash commands
• Configure auto-indexing on session end
• Configure auto-synthesis every 20 prompts
• Create insights directory at ~/.claude/cc-recall/insights/
• Add synthesis reminders to your global CLAUDE.md

Manual Installation:

git clone <your-repo-url>
cd cc-recall
uv sync
uv run index-sessions
cp commands/search-history.md ~/.claude/commands/
# Then configure the hook in ~/.claude/settings.local.json (see Hook Configuration section)

Quick Start

1. Initial Setup

First, do a one-time full index of your existing chat history:

cd ~/cc-recall
uv run index-sessions

This will:

• Read your chat history from ~/.claude/history.jsonl
• Generate embeddings using the sentence-transformer model
• Store vectors in a local ChromaDB database (./chroma_db)

2. Enable Auto-Indexing (Recommended)

The SessionEnd hook is already configured in .claude/settings.local.json. It will automatically index new conversations when your Claude Code sessions end.

To verify it's working, check after your next session:

uv run index-sessions --stats

3. Search Your History

From Command Line:

uv run search-sessions "how to use git hooks"

Inside Claude Code:

/search-history embedding models and vector databases

Advanced Search Options

# Get more results
uv run search-sessions "debugging python" --results 20

# Filter by project
uv run search-sessions "API endpoints" --project "/path/to/project"

# Filter by date
uv run search-sessions "authentication" --date "2025-01-15"

# Get JSON output
uv run search-sessions "docker setup" --json

Usage Examples

# Find conversations about embeddings
uv run search-sessions "embedding models and vector search"

# Find debugging sessions
uv run search-sessions "fix bug in authentication flow"

# Find setup/configuration topics
uv run search-sessions "environment setup configuration"

# View database statistics
uv run index-sessions --stats

Synthesis: Capture Coding Insights

cc-recall automatically synthesizes insights from your coding sessions into structured markdown files. Unlike raw conversation search, synthesis extracts the meaning behind your work: architectural patterns, decisions, problem-solutions, and learning progressions.

How It Works

The synthesis system operates on three levels:

1. Automatic (Every 20 Prompts)

   • UserPromptSubmit hook tracks your conversation length
   • Triggers background synthesis every 20 user prompts
   • Non-blocking: runs silently without interrupting your flow

2. AI-Suggested (At Key Moments)

   • Claude monitors conversation context via global CLAUDE.md instructions
   • Suggests synthesis after: solving problems, making decisions, completing features
   • Natural prompts like: "Would you like me to run /synthesize to capture these insights?"

3. Manual (User Control)

   • Run /synthesize anytime within Claude Code
   • Full control over when to capture insights

What Gets Captured

Synthesis extracts meaningful insights, not trivial patterns:

• Architectural Patterns: Code structure preferences, design decisions, consistent approaches across projects
• Problem-Solutions: Recurring issues and their fixes, debugging strategies, what works and what doesn't
• Decisions: Technical choices with rationale, trade-offs accepted, technology selections
• Learning: Concepts being explored, skill progression, current focus areas

Storage: Progressive Disclosure

Insights are stored as markdown files at ~/.claude/cc-recall/insights/:

~/.claude/cc-recall/insights/
└── index.md          # Lightweight summary (loaded first)

• Index: Concise summaries with evidence (occurrences, projects, dates)
• Progressive: Load lightweight index first, details on demand
• No Vector DB: LLMs read markdown natively—no embeddings needed for synthesis

Backfill Historical Conversations

Process all your existing conversation history:

# Automated backfill using Haiku (fast & cheap)
uv run backfill-auto --auto

# Resume from a specific batch if interrupted
uv run backfill-auto --auto --resume 25

This processes conversations in batches, extracting insights from your entire coding history.

Manual Synthesis

Trigger synthesis manually within Claude Code:

/synthesize

Claude will:

1. Read the last ~50 conversation entries
2. Read current insights from ~/.claude/cc-recall/insights/index.md
3. Extract new patterns, problems, decisions, and learnings
4. Merge with existing insights (update, don't replace)
5. Update the index with evidence-based entries

Insight Quality

Instead of confidence scores, insights show evidence:

• Number of occurrences
• Projects where observed
• Date ranges
• Cross-references to related insights

Example:

### API-First Architecture
- Observed in: video-api, auth-service, data-pipeline (3 projects)
- Last updated: 2025-02-10
- Pattern: Prefer standalone API servers over monoliths
- Evidence: Consistent choice across 8 conversations over 3 months

Architecture

Components

Search System

• Parser (parser.py): Parses ~/.claude/history.jsonl into structured entries
• Indexer (index.py): Generates embeddings and stores in ChromaDB (full re-index)
• Incremental Indexer (incremental_index.py): Adds only new entries since last index
• Search (search.py): Semantic search interface with rich CLI output
• SessionEnd Hook (hooks/session-end-index.sh): Auto-indexes new entries on session exit
• Slash Command (~/.claude/commands/search-history.md): Search from within Claude Code

Synthesis System

• Synthesizer (synthesize.py): Extracts insights from conversation history
• Backfill (backfill.py): Manual batch prompt generator for historical processing
• Automated Backfill (backfill_auto.py): Automated historical processing using Haiku
• UserPromptSubmit Hook (hooks/prompt-counter-synthesize.sh): Auto-synthesis every 20 prompts
• Slash Command (~/.claude/commands/synthesize.md): Manual synthesis trigger
• CLAUDE.md Integration: AI suggests synthesis at natural breakpoints

Technology Stack

• Embedding Model: sentence-transformers/all-MiniLM-L6-v2
  • 384-dimensional embeddings
  • Optimized for semantic similarity
  • Works well with technical/code content
• Vector Database: ChromaDB
  • Local persistent storage
  • Fast similarity search
  • No external dependencies
• Data Source: ~/.claude/history.jsonl
  • Claude Code's native chat history format

Project Structure

cc-recall/
├── src/
│   └── claude_memory/
│       ├── __init__.py
│       ├── parser.py              # History file parser
│       ├── index.py               # Full indexing
│       ├── incremental_index.py   # Incremental indexing
│       ├── search.py              # Search interface
│       ├── synthesize.py          # Insight synthesis
│       ├── backfill.py            # Manual batch processing
│       └── backfill_auto.py       # Automated backfill with Haiku
├── hooks/
│   ├── session-end-index.sh       # Auto-index hook
│   └── prompt-counter-synthesize.sh  # Auto-synthesis hook
├── commands/
│   ├── search-history.md          # Search slash command
│   └── synthesize.md              # Synthesis slash command
├── docs/
│   └── synthesized-insights.md    # Design documentation
├── install.sh                     # One-command installer
├── pyproject.toml                 # Project configuration
├── README.md
└── .gitignore

Note: Personal insights are stored at ~/.claude/cc-recall/insights/ (not in the repo).

How Auto-Indexing Works

1. SessionEnd Hook: When a Claude Code session ends, the SessionEnd hook triggers
2. Incremental Index: The hook runs uv run index-new --silent which:
   • Checks the current number of indexed entries
   • Parses the history file to get all entries
   • Only indexes entries beyond the last indexed count
3. No Duplicates: The incremental indexer is idempotent - running it multiple times won't create duplicates
4. Silent Mode: Runs silently in the background, doesn't interrupt your workflow

Hook Configuration

Both hooks are configured in ~/.claude/settings.local.json:

{
  "hooks": {
    "SessionEnd": [
      {
        "command": "~/cc-recall/hooks/session-end-index.sh",
        "timeout": 30
      }
    ],
    "UserPromptSubmit": [
      {
        "command": "~/cc-recall/hooks/prompt-counter-synthesize.sh",
        "timeout": 5
      }
    ]
  }
}

• SessionEnd: Runs incremental indexing when session ends (blocks for up to 30s)
• UserPromptSubmit: Counts prompts and triggers synthesis every 20 prompts (background, 5s timeout)

Development

Install for Development

uv sync

Run Tests

# Test the parser
uv run python -m claude_memory.parser

# View indexing stats
uv run index-sessions --stats

Embedding Model Options

The default model (all-MiniLM-L6-v2) is fast and works well for most cases. You can experiment with other models by modifying the model_name parameter:

Alternative Models

• BAAI/bge-small-en-v1.5 - Better quality, slightly slower
• sentence-transformers/all-mpnet-base-v2 - Higher quality, larger model
• Any HuggingFace sentence-transformer model

Troubleshooting

Database Not Found

If you see "Database not found", run the indexer first:

uv run index-sessions

History File Not Found

Make sure you have Claude Code installed and have used it at least once. The history file should be at ~/.claude/history.jsonl.

Re-indexing

To re-index (e.g., after many new conversations):

uv run index-sessions
# Answer 'y' when prompted to clear and re-index

License

MIT

Contributing

Contributions welcome! Please feel free to submit a Pull Request.