Skip to content
Conduit

mcp server

claude-semantic-search

pauloportella/claude-semantic-searchcommunitylistedunreviewed
Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

  • uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "claude-semantic-search": {
      "command": "uvx",
      "args": [
        "claude-semantic-search"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 21, 2026

Claude Semantic Search

Semantic search for Claude conversations. Find what you discussed instantly using natural language queries.

Features

  • Natural language search across all your Claude conversations
  • Multiple interfaces: CLI, MCP (Claude Code/Desktop/Cursor), Alfred workflow
  • Smart chunking: Context-aware splitting optimized for code and Q&A
  • GPU acceleration: AMD ROCm, NVIDIA CUDA, and Apple Silicon support
  • Auto-indexing: Background daemon watches for new conversations

Quick Start

git clone https://github.com/pauloportella/claude-semantic-search
cd claude-semantic-search
./install.sh

The installer will:

  • Detect and install GPU support (AMD/NVIDIA/Apple Silicon)
  • Configure MCP for Claude Code, Claude Desktop, and Cursor
  • Download the embedding model (~420MB)
  • Index your conversations

Then restart your Claude apps and search:

"Find my GPU performance discussions"
"Show conversations about the daisy project with code"

Usage

CLI Commands

# Index conversations (auto-detects GPU)
claude-index

# Force reindex everything
claude-index --force

# Search
claude-search "your query"
claude-search "error handling" --project myapp --has-code

# View stats
claude-stats

# Auto-index daemon
claude-start   # start background daemon
claude-status  # check status
claude-stop    # stop daemon

GPU Support

GPU acceleration is automatic - the installer detects your hardware:

GPU TypeSpeedupSupport
AMD ROCm~6-8xEmbeddings accelerated, search on CPU
NVIDIA CUDA~10xFull acceleration (embeddings + search)
Apple Silicon~2-3xEmbeddings accelerated, search on CPU

Disable GPU: claude-index --no-gpu

Advanced Search

# Filter by project (partial match)
claude-search "database" --project myapp

# Date range
claude-search "deployment" --after 2024-01-01 --before 2024-12-31

# Code only
claude-search "async function" --has-code

# Related chunks
claude-search --related-to chunk_abc123 --same-session

Architecture

JSONL Files → Parser → Chunker → Embeddings (all-mpnet-base-v2) → FAISS + SQLite
                                                                         ↓
                                                    CLI / MCP Server / Alfred

Key Components:

  • Embeddings: all-mpnet-base-v2 (768-dim vectors)
  • Search: FAISS IndexFlatIP + SQLite metadata
  • Chunking: Q&A pairs, code blocks, context segments
  • Incremental: Only processes new/modified files

Development

# Setup
git clone https://github.com/pauloportella/claude-semantic-search
cd claude-semantic-search
uv sync

# Run tests
uv run pytest
uv run pytest --cov=src

# Format code
uv run black src/ tests/
uv run isort src/ tests/

Configuration

Data Directory: ~/.claude-semantic-search/data (customizable)

# Environment variable
export CLAUDE_SEARCH_DATA_DIR=/your/path

# Or via flag
claude-index --data-dir /your/path

MCP Configuration (auto-configured by installer):

  • Claude Code: ~/.claude.json
  • Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Cursor: ~/.cursor/mcp.json

Troubleshooting

# Check GPU status
claude-stats

# Verify model
ls ~/.claude-semantic-search/data/models/

# Rebuild index
claude-index --force

# Check daemon
claude-status

License

MIT License - see LICENSE file for details.

Acknowledgments

↑↓ navigate openesc close