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

Related MCP server: engram-mcp

Prerequisites

• Python 3.12+

• Qdrant running locally on port 6333

• OpenAI API key

Starting Qdrant

Using Docker:

docker run -p 6333:6333 -v $(pwd)/qdrant_storage:/qdrant/storage qdrant/qdrant

Or install and run locally following Qdrant docs.

Installation

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:

{
  "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:

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:

# 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:

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

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):

{
  "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:

uv sync --extra dev

Run unit tests:

uv run pytest tests/ -m "not integration" -v

Run integration tests (requires running Qdrant and valid OpenAI API key):

uv run pytest tests/ -m integration -v

Run all tests:

uv run pytest tests/ -v

License

MIT