# Semantic Transcript Search

A semantic search system for Claude Code transcript history, exposed as an MCP server so Claude Code can query its own past sessions.

## Architecture

```
~/.claude/projects/**/*.jsonl  →  Indexer  →  Qdrant (localhost:6333)
                                               ↑
Claude Code  →  MCP Server  →  Query API  ────┘
                                ↓
                        OpenAI Embeddings
```

## Prerequisites

- Python 3.12+
- [Qdrant](https://qdrant.tech/) running locally on port 6333
- OpenAI API key

### Starting Qdrant

Using Docker:
```bash
docker run -p 6333:6333 -v $(pwd)/qdrant_storage:/qdrant/storage qdrant/qdrant
```

Or install and run locally following [Qdrant docs](https://qdrant.tech/documentation/quick-start/).

## Installation

```bash
git clone https://github.com/ttrine/semantic-transcript-search.git
cd semantic-transcript-search
uv sync
```

## Configuration

Create a config file at `~/.config/transcript-search/config.json`:

```json
{
  "openai_api_key": "sk-...",
  "qdrant_url": "http://localhost:6333",
  "collection_name": "claude_transcripts",
  "embedding_model": "text-embedding-3-small",
  "embedding_dimensions": 1536
}
```

**Note:** If using `text-embedding-3-large`, set `embedding_dimensions` to `3072`.

Alternatively, set environment variables:
- `OPENAI_API_KEY` - Your OpenAI API key
- `QDRANT_URL` - Qdrant server URL (defaults to `http://localhost:6333`)

## Usage

### Continuous Indexing Service (Recommended)

Run the watcher service to automatically index new and modified transcripts:

```bash
uv run transcript-watcher
```

Options:
- `--foreground`: Run in foreground with console logging
- `--force-reindex`: Re-index all files before watching
- `--no-initial-index`: Skip initial indexing, watch only
- `--debounce FLOAT`: Debounce delay in seconds (default: 2.0)
- `--watch-path PATH`: Custom path to watch

#### macOS launchd Service

To run the watcher as a background service that starts at login:

```bash
# Install the service
cp launchd/com.transcript-search.watcher.plist ~/Library/LaunchAgents/

# Edit the plist to set the correct path to transcript-watcher binary
# Then load the service
launchctl load ~/Library/LaunchAgents/com.transcript-search.watcher.plist

# Check status
launchctl list | grep transcript

# View logs
tail -f ~/.local/log/transcript-search/watcher.log

# Stop service
launchctl unload ~/Library/LaunchAgents/com.transcript-search.watcher.plist
```

### One-Time Indexing

For manual/one-time indexing of all Claude Code transcripts:

```bash
uv run index-transcripts
```

Options:
- `--force`: Re-index all files (ignores cache)
- `--stats`: Show collection statistics
- `--base-path PATH`: Custom path to search for transcripts

### CLI Search

```bash
uv run search-transcripts "how did we implement the TDD workflow?"
```

Options:
- `-n, --limit`: Number of results (default: 10)
- `-p, --project`: Filter by project path
- `-t, --type`: Filter by message type (user/assistant)
- `-j, --json-output`: Output as JSON
- `-f, --full`: Show full content instead of preview

### MCP Server Integration

Add to your Claude Code MCP configuration (`~/.claude/mcp.json`):

```json
{
  "mcpServers": {
    "transcript-search": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/semantic-transcript-search", "python", "-m", "transcript_search.mcp_server"]
    }
  }
}
```

After restarting Claude Code, the `search_transcripts` tool will be available.

## MCP Tools

### search_transcripts

Search through past Claude Code session transcripts using semantic similarity.

Parameters:
- `query` (required): The search query
- `limit`: Maximum results (default: 10)
- `project_filter`: Filter to specific project
- `message_type`: Filter by "user" or "assistant"

### get_session_context

Retrieve full context from a specific session after finding a relevant match.

Parameters:
- `session_id` (required): The session ID to retrieve
- `limit`: Maximum messages (default: 50)

## Development

Install dev dependencies:
```bash
uv sync --extra dev
```

Run unit tests:
```bash
uv run pytest tests/ -m "not integration" -v
```

Run integration tests (requires running Qdrant and valid OpenAI API key):
```bash
uv run pytest tests/ -m integration -v
```

Run all tests:
```bash
uv run pytest tests/ -v
```

## License

MIT