AI导哈

对话全文搜索工具

一个基于SQLite FTS5的全文搜索工具，用于索引和搜索Claude Code的对话历史记录，支持CLI和MCP服务器模式。

  • by gebeer
  • Python
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 gebeer/conversation-search-mcp

使用说明

对话搜索

对Claude Code对话历史进行FTS5全文搜索。对JSONL转录本进行索引 ~/.claude/projects/ 并将其作为可搜索内存公开。可作为MCP服务器和CLI工具使用。

基于 单个文件中的可搜索代理内存 埃里克·特拉梅尔。

开发流程

最初的实现是由Claude Code按照结构化的管道生成的：

  1. 产品需求文档 (ai-docs/features/001-conversation-search-mcp.md)--要求和设计决策
  2. 构建规范 (specs/conversation-search-mcp.md)--从PRD生成，包含精确的函数签名、过滤规则、接受标准和验证命令
  3. 实施 (conversation_search.py)--由Claude Code使用构建规范作为指令编写

搜索后端后来从内存中的bm25s迁移到SQLite FTS5(specs/fts5-migration.md)，由Claude（Opus 4.6）和Codex（GPT-5.4）进行同行评审，并作为5个连续的子代理任务执行。

运作原理

Claude Code将对话记录存储为JSONL文件 ~/.claude/projects/<encoded-dir>/。此服务器：

  1. 通过glob模式发现匹配的项目目录
  2. 将JSONL解析为回合（用户消息+助理响应+工具调用）
  3. 构建存储在以下位置的SQLite FTS5索引 ~/.cache/conversation-search/index.db
  4. 在热启动时，仅重新分析mtime/大小已更改的文件（亚秒启动）
  5. 监视文件系统的更改和重新索引（60秒去抖动）
  6. 通过stdio提供4个MCP工具(serve)或SSE(daemon)

需求

  • uv （Python>=3.10会自动解析）

无需venv或手动安装。 uv run 手柄 mcp, uvicorn，以及 watchdog 自动。不 bm25s 或者需要其他搜索库——SQLite FTS5是Python标准库的一部分。

安装

添加到MCP配置中——项目级别(.mcp.json)或全球(~/.claude.json 在...之下 mcpServers 按键）：

{
  "mcpServers": {
    "conversation-search": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/gebeer/conversation-search.git",
        "conversation-search", "connect"
      ]
    }
  }
}

connect 首次使用时启动共享守护进程，并在会话之间重用它（请参见 守护程序模式).对于独立stdio模式（每个会话一个索引），请替换 connect 随着 serve.

这 --pattern 标志控制下的项目目录 ~/.claude/projects/ 被编入索引。它默认为 * （所有项目）如果省略。图案包含 / 被视为文件系统路径，并自动转换为编码的目录名格式。

模式 范围
* 所有项目
~/repos/openclaw 单个项目
~/repos/* 所有repos项目
~/repos/open* 以“open”开头的项目
--pattern="-home-claude-repos-*" 编码格式（需要 = 前导语法 -)

更改MCP配置后重新启动Claude Code。

CLI使用情况

该工具也可以直接从命令行用于脚本编写和调试：

uvx --from git+https://github.com/gebeer/conversation-search.git \
  conversation-search search --query "heartbeat" --limit 5

conversation-search list --project "claude" --limit 10

conversation-search read-turn --session-id "<uuid>" --turn 5

conversation-search read-conv --session-id "<uuid>" --offset 0 --limit 10

第一次之后 uvx 调用，the conversation-search 命令被缓存，可以直接调用。或者，使用 uv run conversation_search.py <command> 从本地克隆。

所有CLI命令都将打印精美的JSON输出到stdout。索引进度已打印到stderr。使用 2>/dev/null 以抑制配管时的进度输出。

守护进程模式（建议用于多个会话）

当同时运行多个Claude Code会话时，使用守护进程模式共享一个 SQLite FTS5索引，而不是为每个会话打开单独的数据库连接。

设置

默认值 安装 配置已使用 connect，这会自动启用守护进程模式。在第一次会话开始时， connect 在后台启动守护进程。后续会话会重用它。守护进程在15分钟不活动后退出。

手动守护程序控制

# Start daemon in foreground (useful for debugging)
conversation-search daemon

# Custom port and idle timeout
conversation-search daemon --port 9300 --idle-timeout 1800

# Stop daemon
kill $(cat ~/.cache/conversation-search/daemon.pid)

配置

标志 默认值 描述
--port 9237 SSE服务器的本地主机端口
--idle-timeout 900秒 守护进程退出前处于非活动状态

两面旗帜都起作用 daemon 和 connect 子命令。

运作原理

Claude Code session A ──┐
Claude Code session B ──┼── connect (stdio↔SSE bridge) ──► daemon (SSE on localhost:9237)
Claude Code session C ──┘                                       │
                                                          • one FTS5 index (~10 MB)
                                                          • one filesystem watcher
                                                          • one reindex loop

没有守护进程： N个会话各自打开相同的SQLite数据库（WAL模式处理并发读取）。 使用守护进程： 单作者/观察者；所有会话通过SSE共享一个连接。

工具

search_conversations

FTS5全文搜索所有索引轮次。所有术语均隐式与。

参数 类型 默认值 说明
query str 必填 FTS5搜索查询。所有术语必须匹配（隐含AND）。
limit int 10 最大结果
session_id str | None None 筛选到一个会话
project str | None None 项目名称上的子字符串筛选器

返回排名结果 session_id, turn_number, score, snippet （上下文窗口 [[match]] 标记）， timestamp.

查询句法

语法 示例 含义
关键词 heartbeat timer 两者必须匹配（隐式AND）
短语 "systemd timer" 精确短语
布尔值 heartbeat AND NOT clawd 布尔运算符
前缀 buffer* 前缀匹配
或 heartbeat OR cron 任一术语
分组 (timer OR cron) AND heartbeat 分组布尔值
字面意思 literal:foo.bar() 类似代码的查询，跳过FTS5语法解析

list_conversations

使用元数据浏览索引会话。

参数 类型 默认值 说明
project str | None None 项目名称上的子字符串筛选器
limit int 50 最大结果

返回按以下方式排序的会话 last_timestamp desc，与 summary, turn_count, cwd, git_branch.

read_turn

单圈高保真检索。重新解析源JSONL（不是索引）。

参数 类型 说明
session_id str 会话UUID
turn_number int 零基转弯指数

退货完成 user_text, assistant_text，以及 tools_used 带有渲染的工具细节。

read_conversation

对一节课中连续轮次的分页阅读。

参数 类型 默认值 说明
session_id str 必需 会话UUID
offset int 0 开始转弯
limit int 10 转弯次数

使用模式

这4个工具通过MCP自动暴露给助手——中没有额外的说明 CLAUDE.md, AGENTS.md，或需要类似的文件。服务器还提供 instructions 元数据通过MCP协议指导助手有效使用。

广泛搜索，然后深入阅读：

search_conversations("ProcessWire login redirect")  ->  find relevant turns
read_turn(session_id, turn_number)                   ->  get full context
read_conversation(session_id, offset, limit)         ->  read surrounding turns

FTS5要求所有查询项匹配（隐式AND）。使用特定关键字以获得最佳结果。对于非此即彼或匹配，请使用显式 OR。对于带有特殊字符的类代码查询，请使用 literal: 前缀。

相关 MCP