README.md
A personal, local-first knowledge management system.
Smart Search
A personal, local-first knowledge management system. Index your Markdown notes, PDFs, DOCX, PPTX, XLSX, and HTML files into a searchable knowledge base that connects with everything running locally -- Claude Code (MCP), a desktop app, REST API, or CLI. Runs entirely on your machine: no cloud, no GPU, no subscriptions.
Version: 0.8.4 | License: MIT
Why Smart Search?
Your knowledge is scattered across notes, PDFs, slide decks, and spreadsheets. Smart Search brings it together:
- Search everything locally. Six document formats indexed into one knowledge base with hybrid search (semantic + keyword + reranking). Find what you need whether you remember the exact phrase or just the concept.
- Connect with your tools. MCP server for Claude Code, REST API for scripts and automation, CLI for power users, desktop app for visual management. One index, many interfaces.
- Stay responsive. All heavy lifting runs in an out-of-process Python server. Your editor, your Obsidian vault, your desktop -- nothing freezes during indexing.
- Own your data. Everything stays on disk -- LanceDB vectors and SQLite metadata in a local directory. No cloud sync, no telemetry, no accounts. MIT licensed.
- Keep it lightweight. CPU-only ONNX embeddings with lazy loading. The model loads when you search, unloads after 60 seconds idle. Steady-state RAM under 200MB.
Features
Search
- Hybrid search (default): combines vector similarity with FTS5 keyword matching via Reciprocal Rank Fusion
- Semantic mode: pure vector search with configurable relevance threshold
- Keyword mode: BM25 ranking via SQLite FTS5 with porter stemming
- Folder filtering: restrict results to specific directories
- Find related: discover similar documents by averaging chunk embeddings
Indexing
- Six formats:
.md,.pdf,.docx,.pptx,.xlsx,.html - Single pipeline: all non-Markdown files converted via MarkItDown, then chunked by headings
- Background indexing: non-blocking with per-folder progress, cancellation, and auto-resume on restart
- Hash-based dedup: unchanged files are skipped automatically
- Ephemeral indexes: create temporary
.smart-search/indexes inside any folder
Desktop App
- Tauri v2 + React desktop application with warm dark theme
- Quick Search:
Ctrl+Spaceglobal hotkey opens a floating search overlay (configurable shortcut) - Dashboard: index stats, per-folder status, model download progress
- Folder Manager: add/remove watch directories with drag-and-drop
- Settings: font scaling, embedding model selection, Matryoshka dimension picker, relevance threshold, autostart, MCP registration
- Repair Index: one-click maintenance (orphan removal, FTS5 rebuild, LanceDB compaction, compatibility check)
- System tray: background operation with tray icon
Embedding
- Default model: snowflake-arctic-embed-m-v2.0 (int8 ONNX, 297MB, 0.554 MTEB retrieval)
- Matryoshka truncation: 256-dim default, configurable per model
- Lazy loading: model loads on demand, unloads after 60s idle to free RAM
- Curated registry: switchable models with quality/size metadata
- CPU-only: ONNX Runtime, no GPU required
Architecture
- Out-of-process: all heavy lifting in Python, Obsidian/desktop stays responsive
- MCP server: 11 tools for Claude Code integration
- REST API: 20 endpoints on
localhost:9742 - CLI:
smart-searchcommand with subcommands for all operations - File-based storage: LanceDB (vectors) + SQLite (metadata + FTS5), no database server
Quick Start
Prerequisites
- Python 3.11+
- `uv` (recommended) or
pip
Install
uv pip install git+https://github.com/ekmungi/smart-search.git
Register with Claude Code
claude mcp add smart-search -- smart-search
Use
In Claude Code:
"Add C:/Users/me/vault to the knowledge base"
"Search my knowledge base for transformer architecture"
"Find notes related to meeting-notes/2026-03-10.md"
Installation Options
Option A: Install from GitHub (recommended)
uv pip install git+https://github.com/ekmungi/smart-search.git
Or with pip:
pip install git+https://github.com/ekmungi/smart-search.git
This creates the smart-search command on your PATH.
Option B: Local development install
git clone https://github.com/ekmungi/smart-search.git
cd smart-search
uv pip install -e ".[dev]"
Option C: Desktop app
Download the installer from the Releases page. The desktop app bundles the Python backend as a sidecar -- no Python installation required.
Verify installation
smart-search stats
MCP Server Setup
Register smart-search as an MCP server with Claude Code:
Method 1: `claude mcp add` (recommended)
claude mcp add smart-search -- smart-search
With
Tools (3)
searchPerform hybrid, semantic, or keyword search across indexed documents.indexAdd a directory or file to the knowledge base.statsGet statistics about the indexed knowledge base.Configuration
claude_desktop_config.json
{"mcpServers": {"smart-search": {"command": "smart-search"}}}Try it
→Add C:/Users/me/vault to the knowledge base
→Search my knowledge base for transformer architecture
→Find notes related to meeting-notes/2026-03-10.md
→What is the current status of my indexed documents?