conversation-search

FTS5 full-text search over Claude Code conversation history. Indexes JSONL transcripts from ~/.claude/projects/ into a persistent SQLite FTS5 database and exposes them as searchable memory. Available as both an MCP server and a CLI tool.

Based on Searchable Agent Memory in a Single File by Eric Tramel.

Development process

The initial implementation was produced by Claude Code following a structured pipeline:

1. PRD (ai-docs/features/001-conversation-search-mcp.md) — requirements and design decisions
2. Build spec (specs/conversation-search-mcp.md) — generated from the PRD, containing exact function signatures, filtering rules, acceptance criteria, and validation commands
3. Implementation (conversation_search.py) — written by Claude Code using the build spec as instructions

The search backend was later migrated from in-memory bm25s to SQLite FTS5 (specs/fts5-migration.md), peer-reviewed by Claude (Opus 4.6) and Codex (GPT-5.4), and executed as 5 sequential subagent tasks.

How it works

Claude Code stores conversation transcripts as JSONL files under ~/.claude/projects/<encoded-dir>/. This server:

1. Discovers matching project directories via glob pattern
2. Parses JSONL into turns (user message + assistant response + tool calls)
3. Builds an SQLite FTS5 index stored at ~/.cache/conversation-search/index.db
4. On warm start, only reparses files whose mtime/size has changed (sub-second startup)
5. Watches the filesystem for changes and reindexes (60s debounce)
6. Serves 4 MCP tools via stdio (serve) or SSE (daemon)

Requirements

• uv (Python >= 3.10 is resolved automatically)

No venv or manual install needed. uv run handles mcp, uvicorn, and watchdog automatically. No bm25s or other search library is required — SQLite FTS5 is part of the Python standard library.

Installation

Add to your MCP configuration — either project-level (.mcp.json) or global (~/.claude.json under the mcpServers key):

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

connect starts a shared daemon on first use and reuses it across sessions (see Daemon Mode). For standalone stdio mode (one index per session), replace connect with serve.

The --pattern flag controls which project directories under ~/.claude/projects/ are indexed. It defaults to * (all projects) if omitted. Patterns containing / are treated as filesystem paths and auto-converted to the encoded directory name format.

Pattern	Scope
*	All projects
~/repos/openclaw	Single project
~/repos/*	All repos projects
~/repos/open*	Projects starting with "open"
--pattern="-home-claude-repos-*"	Encoded format (requires = syntax for leading -)

Restart Claude Code after changing MCP configuration.

CLI Usage

The tool can also be used directly from the command line for scripting and debugging:

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

After the first uvx invocation, the conversation-search command is cached and can be called directly. Alternatively, use uv run conversation_search.py <command> from a local clone.

All CLI commands output pretty-printed JSON to stdout. Index progress is printed to stderr. Use 2>/dev/null to suppress progress output when piping.

Daemon Mode (Recommended for Multiple Sessions)

When running multiple Claude Code sessions simultaneously, use daemon mode to share a single SQLite FTS5 index instead of opening separate DB connections per session.

Setup

The default installation config already uses connect, which enables daemon mode automatically. On first session start, connect launches the daemon in the background. Subsequent sessions reuse it. The daemon exits after 15 minutes of inactivity.

Manual daemon control

# 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)

Configuration

Flag	Default	Description
--port	9237	Localhost port for the SSE server
--idle-timeout	900	Seconds of inactivity before daemon exits

Both flags work on daemon and connect subcommands.

How it works

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

Without daemon: N sessions each open the same SQLite DB (WAL mode handles concurrent reads). With daemon: Single writer/watcher; all sessions share one connection via SSE.

Tools

search_conversations

FTS5 full-text search across all indexed turns. All terms are implicitly ANDed.

Parameter	Type	Default	Description
query	str	required	FTS5 search query. All terms must match (implicit AND).
limit	int	10	Max results
session_id	str | None	None	Filter to one session
project	str | None	None	Substring filter on project name

Returns ranked results with session_id, turn_number, score, snippet (context window with [[match]] markers), timestamp.

Query syntax

Syntax	Example	Meaning
Keywords	heartbeat timer	Both must match (implicit AND)
Phrase	"systemd timer"	Exact phrase
Boolean	heartbeat AND NOT clawd	Boolean operators
Prefix	buffer*	Prefix matching
OR	heartbeat OR cron	Either term
Grouping	(timer OR cron) AND heartbeat	Grouped boolean
Literal	literal:foo.bar()	Code-like query, skips FTS5 syntax parsing

list_conversations

Browse indexed sessions with metadata.

Parameter	Type	Default	Description
project	str | None	None	Substring filter on project name
limit	int	50	Max results

Returns sessions sorted by last_timestamp desc, with summary, turn_count, cwd, git_branch.

read_turn

Full-fidelity retrieval of a single turn. Re-parses the source JSONL (not the index).

Parameter	Type	Description
session_id	str	Session UUID
turn_number	int	Zero-based turn index

Returns complete user_text, assistant_text, and tools_used with rendered tool details.

read_conversation

Paginated reading of consecutive turns from a session.

Parameter	Type	Default	Description
session_id	str	required	Session UUID
offset	int	0	Starting turn
limit	int	10	Number of turns

Usage pattern

The 4 tools are automatically exposed to the assistant via MCP — no extra instructions in CLAUDE.md, AGENTS.md, or similar files are needed. The server also provides instructions metadata through the MCP protocol to guide the assistant on effective usage.

Search wide, then read deep:

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 requires all query terms to match (implicit AND). Use specific keywords for best results. For either-or matching, use explicit OR. For code-like queries with special characters, use the literal: prefix.