{"id":"20976adf-db00-41d7-b2ca-d2a8d7d515bf","slug":"claude-semantic-search","kind":"mcp","name":"claude-semantic-search","summary":"","owner":"pauloportella","repoUrl":"https://github.com/pauloportella/claude-semantic-search","license":"MIT","licenseTier":"permissive","trust":"community","stars":7,"match":null,"fewStars":false,"format":"mcp","createdAt":"2025-07-10T20:33:33.000Z","addedAt":"2026-10-21T15:30:56.788Z","logoUrl":"https://avatars.githubusercontent.com/u/22947229?u=772455b75414f061d5c4feab963ea930edee7006&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["search"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T15:31:31.452Z","sample":false,"url":"https://conduits.dev/tools/claude-semantic-search","language":"Python","transports":["stdio"],"install":{"pypi":"claude-semantic-search"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Claude Semantic Search\n\nSemantic search for Claude conversations. Find what you discussed instantly using natural language queries.\n\n<figure style=\"text-align: center;\">\n  <img width=\"600\" alt=\"Claude Semantic Search interface\" src=\"https://github.com/user-attachments/assets/b5d35184-27b7-44c3-b4aa-9dc7c6e21af6\" />\n</figure>\n\n## Features\n\n- **Natural language search** across all your Claude conversations\n- **Multiple interfaces**: CLI, MCP (Claude Code/Desktop/Cursor), Alfred workflow\n- **Smart chunking**: Context-aware splitting optimized for code and Q&A\n- **GPU acceleration**: AMD ROCm, NVIDIA CUDA, and Apple Silicon support\n- **Auto-indexing**: Background daemon watches for new conversations\n\n## Quick Start\n\n```bash\ngit clone https://github.com/pauloportella/claude-semantic-search\ncd claude-semantic-search\n./install.sh\n```\n\nThe installer will:\n- Detect and install GPU support (AMD/NVIDIA/Apple Silicon)\n- Configure MCP for Claude Code, Claude Desktop, and Cursor\n- Download the embedding model (~420MB)\n- Index your conversations\n\nThen restart your Claude apps and search:\n```\n\"Find my GPU performance discussions\"\n\"Show conversations about the daisy project with code\"\n```\n\n## Usage\n\n### CLI Commands\n\n```bash\n# Index conversations (auto-detects GPU)\nclaude-index\n\n# Force reindex everything\nclaude-index --force\n\n# Search\nclaude-search \"your query\"\nclaude-search \"error handling\" --project myapp --has-code\n\n# View stats\nclaude-stats\n\n# Auto-index daemon\nclaude-start   # start background daemon\nclaude-status  # check status\nclaude-stop    # stop daemon\n```\n\n### GPU Support\n\nGPU acceleration is **automatic** - the installer detects your hardware:\n\n| GPU Type | Speedup | Support |\n|----------|---------|---------|\n| **AMD ROCm** | ~6-8x | Embeddings accelerated, search on CPU |\n| **NVIDIA CUDA** | ~10x | Full acceleration (embeddings + search) |\n| **Apple Silicon** | ~2-3x | Embeddings accelerated, search on CPU |\n\nDisable GPU: `claude-index --no-gpu`\n\n### Advanced Search\n\n```bash\n# Filter by project (partial match)\nclaude-search \"database\" --project myapp\n\n# Date range\nclaude-search \"deployment\" --after 2024-01-01 --before 2024-12-31\n\n# Code only\nclaude-search \"async function\" --has-code\n\n# Related chunks\nclaude-search --related-to chunk_abc123 --same-session\n```\n\n## Architecture\n\n```\nJSONL Files → Parser → Chunker → Embeddings (all-mpnet-base-v2) → FAISS + SQLite\n                                                                         ↓\n                                                    CLI / MCP Server / Alfred\n```\n\n**Key Components:**\n- **Embeddings**: all-mpnet-base-v2 (768-dim vectors)\n- **Search**: FAISS IndexFlatIP + SQLite metadata\n- **Chunking**: Q&A pairs, code blocks, context segments\n- **Incremental**: Only processes new/modified files\n\n## Development\n\n```bash\n# Setup\ngit clone https://github.com/pauloportella/claude-semantic-search\ncd claude-semantic-search\nuv sync\n\n# Run tests\nuv run pytest\nuv run pytest --cov=src\n\n# Format code\nuv run black src/ tests/\nuv run isort src/ tests/\n```\n\n## Configuration\n\n**Data Directory**: `~/.claude-semantic-search/data` (customizable)\n\n```bash\n# Environment variable\nexport CLAUDE_SEARCH_DATA_DIR=/your/path\n\n# Or via flag\nclaude-index --data-dir /your/path\n```\n\n**MCP Configuration** (auto-configured by installer):\n- Claude Code: `~/.claude.json`\n- Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Cursor: `~/.cursor/mcp.json`\n\n## Troubleshooting\n\n```bash\n# Check GPU status\nclaude-stats\n\n# Verify model\nls ~/.claude-semantic-search/data/models/\n\n# Rebuild index\nclaude-index --force\n\n# Check daemon\nclaude-status\n```\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Acknowledgments\n\n- [sentence-transformers](https://github.com/UKPLab/sentence-transformers) - Embedding models\n- [FAISS](https://github.com/facebookresearch/faiss) - Vector search\n- [Click](https://github.com/pallets/click) - CLI framework\n"}