Smart Search

智能搜索

个人、本地优先的知识管理系统。将您的文档、笔记、电子表格等索引到可搜索的知识库中，该知识库与本地运行的所有内容相连接——Claude Code（MCP）、桌面应用程序、REST API或CLI。完全在您的机器上运行：没有云，没有GPU，没有订阅。

版本： 0.13.1 | 许可证： 麻省理工学院

______________________________________________________________________

为什么选择智能搜索？

你的知识分散在笔记、PDF、幻灯片和电子表格中。智能搜索将它结合在一起：

• 在本地搜索所有内容。 通过混合搜索（语义+关键字+重新排序）将14种文档格式编入一个知识库。无论你记得确切的短语还是只是概念，都要找到你需要的东西。
• 用你的工具连接。 用于Claude Code的MCP服务器，用于脚本和自动化的REST API，用于高级用户的CLI，用于可视化管理的桌面应用程序。一个索引，多个接口。
• 保持反应灵敏。 所有繁重的工作都在一个进程外的Python服务器中运行。你的编辑器、黑曜石保险库、桌面——在索引过程中没有任何东西会冻结。
• 拥有你的数据。 所有内容都保留在磁盘上——LanceDB矢量和SQLite元数据位于本地目录中。没有云同步，没有遥测，没有帐户。麻省理工学院许可。
• 保持轻便。 ONNX嵌入延迟加载和自动GPU加速。模型在搜索时加载，在CPU上空闲60秒后卸载（保持驻留在GPU上）。200MB以下的稳态RAM。

______________________________________________________________________

特性

搜索

• 混合搜索 （默认）：通过互易秩融合、交叉编码器重新排序和MMR多样性选择将向量相似性与FTS5关键字匹配相结合
• 交叉编码器重新排序：使用TinyBERT-L-2对（查询、文档）对进行联合评分，其精度高于单独使用双编码器相似性（+5-15nDCG@10在基准测试中）
• MMR多样性：消除同一文档中的冗余块，确保结果涵盖不同的信息
• 语义模式：具有可配置相关性阈值的纯矢量搜索
• 关键字模式：通过SQLite FTS5进行BM25排名，去除搬运工词干和停用词
• 文件夹筛选：将结果限制到特定目录
• 查找相关：通过平均块嵌入来发现类似的文档
• 搜索管道架构：完整检索管道的交互式可视化图

支持的文件

索引

• 14种格式：所有通过MarkItDown转换的非Markdown文件，然后按标题分块
• 仅关键字索引：在FTS5中索引的结构化文件（CSV、XLSX、JSON），用于关键字搜索，无需向量嵌入
• 持续转换工作者：用于二进制文件转换的长期子进程--消除了Windows上每个文件进程的创建开销
• 后台索引：无阻塞，每个文件夹进度、取消和重新启动时自动恢复
• 基于哈希的数据消除：未更改的文件将自动跳过
• 持久索引日志：存储在SQLite中的文件状态（已索引/失败），在服务器重新启动并重试每个文件后仍然有效
• 短暂指数：创建临时 .smart-search/ 任何文件夹内的索引

桌面应用

• 让V 2+反应 带有暖暗主题的桌面应用程序
• 快速搜索: Ctrl+Space 全局热键打开浮动搜索覆盖（可配置快捷方式）
• 仪表盘：索引统计信息、每个文件夹的状态、模型下载进度
• 文件夹管理器：通过拖放添加/删除监视目录
• 索引日志：包含状态、错误详细信息、每个文件重试次数和在默认应用程序中打开的持久文件日志
• 设置：字体缩放、嵌入模型选择、Matryoshka维度选择器、相关性阈值、自动启动、MCP注册
• 维修指数：一键维护（孤立删除、FTS5重建、LanceDB压缩、兼容性检查）
• 窗口状态：记住会话之间的大小和位置
• 优雅关闭：当桌面应用程序关闭时，服务器通过HTTP信号干净地退出
• 系统托盘：带托盘图标的后台操作

嵌入

• 默认模型：雪花型实际嵌入式m-v2.0（int8 ONNX，297MB，0.554 MTEB检索）
• 套娃截断：默认256暗，可按型号配置
• 延迟加载：模型按需加载，60秒空闲后卸载以释放RAM
• 管理登记处：具有质量/大小元数据的可切换模型
• GPU自动检测：CUDA和DirectML加速在可用时自动使用，否则CPU回退

建筑

• 进程外：Python中的所有繁重工作，黑曜石/桌面保持响应
• MCP服务器：用于集成Claude Code的11个工具
• REST API：20个端点 localhost:9742
• 命令行界面: smart-search 带子命令的命令用于所有操作
• 基于文件的存储：LanceDB（向量）+SQLite（元数据+FTS5），无数据库服务器

系统要求

||要求| |--|-------------| |操作系统| Windows 10/11（x64）| |RAM |最小2 GB（约200 MB空闲）| |存储空间|~300 MB（带AI型号）| |运行时|Python 3.11+（捆绑在桌面安装程序中）| |网络|不需要|

______________________________________________________________________

快速开始

先决条件

• Python 3.11+
• uv （推荐）或 pip

安装

uv pip install git+https://github.com/ekmungi/smart-search.git

使用克劳德代码注册

claude mcp add smart-search -- smart-search

使用

在克劳德代码中：

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

______________________________________________________________________

安装选项

选项A：从GitHub安装（推荐）

uv pip install git+https://github.com/ekmungi/smart-search.git

或者使用pip：

pip install git+https://github.com/ekmungi/smart-search.git

这将创建 smart-search PATH上的命令。

选项B：本地开发安装

git clone https://github.com/ekmungi/smart-search.git
cd smart-search
uv pip install -e ".[dev]"

选项C：桌面应用程序

从发布页面下载安装程序。桌面应用程序将Python后端打包为sidecar，不需要安装Python。

验证安装

smart-search stats

______________________________________________________________________

MCP服务器设置

使用Claude Code将智能搜索注册为MCP服务器：

方法1： claude mcp add （推荐）

claude mcp add smart-search -- smart-search

在虚拟环境中：

claude mcp add smart-search -- /path/to/venv/Scripts/smart-search

方法2： .mcp.json 文件

{
  "mcpServers": {
    "smart-search": {
      "command": "smart-search"
    }
  }
}

方法3:Python模块

{
  "mcpServers": {
    "smart-search": {
      "command": "/path/to/python",
      "args": ["-m", "smart_search.server"],
      "cwd": "/path/to/smart-search"
    }
  }
}

注： 在Windows上，在JSON路径中使用正斜杠或转义反斜杠。

______________________________________________________________________

CLI备忘单

# Index management
smart-search stats                           # Index stats and data directory
smart-search index ingest /path              # Index a file or folder
smart-search index ingest /path --ephemeral  # Create a local .smart-search/ index
smart-search index list                      # List all indexed files
smart-search index rebuild                   # Re-index all watched directories
smart-search index remove /path              # Remove files from index

# Search
smart-search search "query"                  # Hybrid search (default)
smart-search search "query" --mode semantic  # Vector-only search
smart-search search "query" --mode keyword   # FTS5 keyword search
smart-search search "query" --folder /path   # Search within a folder
smart-search search "query" --limit 5        # Limit results

# Watch directories
smart-search watch list                      # List watched directories
smart-search watch add /path/to/dir          # Add a watch directory
smart-search watch remove /path/to/dir       # Remove a watch directory

# Configuration
smart-search config show                     # Show current configuration
smart-search model show                      # Show current embedding model
smart-search model set model-name --dim 256  # Change embedding model

# Server
smart-search serve                           # Start HTTP server (port 9742)
smart-search mcp                             # Start MCP server (stdio)

# Ephemeral indexes
smart-search temp list                       # List ephemeral indexes
smart-search temp cleanup /path              # Remove an ephemeral index

______________________________________________________________________

克劳德代码提示

______________________________________________________________________

MCP工具

______________________________________________________________________

REST API

HTTP服务器运行在 localhost:9742 有23个端点：

______________________________________________________________________

配置

数据目录

覆盖： SMART_SEARCH_DATA_DIR=/custom/path

config.json

存储在数据目录中的持久配置。通过CLI、REST API或桌面设置面板进行管理。

环境变量

所有设置都可以用以下命令覆盖 SMART_SEARCH_ 前缀变量：

______________________________________________________________________

建筑

所有客户端都连接到 同一HTTP服务器 在端口9742上。服务器是唯一的事实来源——只有一个后端进程。

                         ┌─────────────────────────┐
                         │   HTTP Server (:9742)    │
                         │   smart-search serve     │
                         │   (FastAPI, 20 endpoints)│
                         └──────┬──┬──┬────────────┘
                                │  │  │
                 ┌──────────────┘  │  └──────────────┐
                 │                 │                  │
          ┌──────┴──────┐  ┌──────┴──────┐   ┌──────┴──────┐
          │  Desktop UI │  │  MCP Server │   │     CLI     │
          │  (Tauri v2) │  │  (proxy)    │   │  smart-search│
          │  fetch()    │  │  → :9742    │   │  search/etc │
          └─────────────┘  └─────────────┘   └─────────────┘
          Started by user   Started by         Run manually
          (or autostart)    Claude Code        in terminal

谁启动HTTP服务器？

• 桌面应用程序正在运行：Tauri应用程序将服务器作为sidecar进程启动。当您从系统托盘退出时，它会杀死服务器。
• 没有桌面应用程序：run smart-search serve 手动操作，否则MCP工具将出现故障。

关键点：MCP服务器不运行自己的后端。它是一个精简的翻译器——MCP协议，HTTP请求 :9742，返回MCP结果。如果HTTP服务器未运行，MCP工具将返回错误。

组件详情

Backend (Python, all share the HTTP server)
  http.py / http_routes.py       FastAPI app, 20 endpoints
  server.py / mcp_client.py      MCP server, proxies to HTTP
  search.py                      Hybrid search: vector + FTS5 + RRF + rerank + MMR
  fts.py                         FTS5 keyword search, BM25 ranking
  fusion.py                      Reciprocal Rank Fusion (k=60)
  reranker.py                    Cross-encoder reranking (TinyBERT, lazy-load)
  mmr.py                         Maximum Marginal Relevance diversity selection
  query_preprocessor.py          Stopword removal (FTS5), query normalization
  indexer.py                     Document ingestion pipeline
  conversion_worker.py           Persistent subprocess for binary file conversion
  markitdown_parser.py           File -> Markdown conversion
  markdown_chunker.py            Heading-based section splitting
  embedder.py                    ONNX embedding with lazy load/unload
  store.py                       LanceDB vectors + SQLite metadata + FTS5
  startup.py                     Orphan reconciliation, FTS5 backfill, repair
  watcher.py                     Watchdog file watcher with debounce
  indexing_task.py               Background task manager with cancellation
  config_manager.py              Persistent config.json

Storage (file-based, no database server)
  LanceDB      vectors/ directory (columnar, sub-50ms search)
  SQLite       metadata.db (indexed_files + chunks_fts virtual table)

Desktop (Tauri v2)
  Rust         System tray, sidecar manager, global shortcut
  React        Dashboard, Folder Manager, Settings, Quick Search

数据流

File -> MarkItDown (non-.md) -> Markdown -> MarkdownChunker -> Chunks
     -> Embedder -> LanceDB + SQLite FTS5

搜索流（混合模式）

Query -> Preprocess (stopwords / normalization)
      -> Vector search (LanceDB)    ─┐
      -> Keyword search (FTS5 BM25) ─┼─> RRF Fusion
                                          -> Cross-Encoder Rerank (TinyBERT, 30-60ms)
                                              -> MMR Diversity (lambda=0.8,  Final Results

______________________________________________________________________

运行测试

# Fast tests only (default)
pytest

# All tests including slow integration tests
pytest -m ""

# With coverage
pytest --cov=smart_search --cov-report=term-missing

425+个测试，涵盖所有模块。慢速测试（标记 @pytest.mark.slow)需要下载ML模型。

______________________________________________________________________

技术栈

______________________________________________________________________

许可证

麻省理工学院