Search Claude Conversations

Purpose: Search through Claude Code conversation history using the vibe-check MCP server

---

Using the MCP Tool

The vibe-check MCP server provides a vibe_search tool that handles all database queries automatically.

Tool: mcp__vibe-check__vibe_search

Parameters:

• query (required): Search term with FTS5 syntax support (see below)
• repo (optional): Filter to specific repository name
• days (optional): Limit to last N days
• session_id (optional): Search within specific session
• limit (optional): Maximum results (default: 20)

FTS5 Query Syntax (powerful full-text search with relevance ranking):

• Simple: authentication - finds messages containing this word
• Phrase: "user authentication" - exact phrase match
• Boolean: auth AND oauth - both terms must be present
• Exclude: login NOT password - exclude certain terms
• Prefix: auth* - matches authentication, authorize, etc.
• Multiple terms: database schema - OR search (either term)

Results are automatically ranked by relevance with star indicators (⭐⭐⭐ = most relevant).

---

Usage Flow

When user requests a search:

1. Extract search criteria from user's question:

   • Search term/keyword
   • Date range (if specified) → convert to days parameter
   • Repository (if specified) → use repo parameter
   • Session ID (if specified) → use session_id parameter

2. Call the MCP tool with appropriate parameters

3. Present results to user - the tool already formats them nicely. Session headers include the full session UUID, the working directory, and a ready-to-run resume command (cd ... && claude --resume <full-uuid>). When you surface a session to the user, preserve the full UUID and include the resume command verbatim — the user cannot restore a session from an 8-character prefix.

4. Offer follow-up actions:

   • View full session (use vibe_session tool)
   • Narrow search (call vibe_search again with more filters)
   • Open in browser (use vibe_view tool)

---

Example Interactions

Example 1: Simple Keyword Search

User: "search my conversations for 'authentication'"

Claude: [Calls mcp__vibe-check__vibe_search with query="authentication"]

[Tool returns formatted results showing sessions and message previews]

Would you like to:
- View full details of a specific session
- Open a session in your browser
- Search for related terms

Example 2: Search with Repository Filter

User: "find when I worked on API endpoints in the vibe-check repo"

Claude: [Calls mcp__vibe-check__vibe_search with query="API endpoints", repo="vibe-check"]

[Tool returns filtered results]

Example 3: Recent Search

User: "what did I work on yesterday?"

Claude: [Note: For "recent work" queries, use the vibe_recent tool instead]
        [Calls mcp__vibe-check__vibe_recent with period="yesterday"]

Example 4: Search Within Session

User: "search for 'database' in session 2d072129-d799-4aa5-b19d-5b5617f5a9de"

Claude: [Calls mcp__vibe-check__vibe_search with query="database", session_id="2d072129-d799-4aa5-b19d-5b5617f5a9de"]

Example 5: Advanced FTS5 Phrase Search

User: "find conversations about 'full text search'"

Claude: [Calls mcp__vibe-check__vibe_search with query='"full text search"']

[Tool returns exact phrase matches, ranked by relevance with star indicators]

Example 6: FTS5 Boolean Search

User: "find conversations about authentication but not OAuth"

Claude: [Calls mcp__vibe-check__vibe_search with query="authentication NOT oauth"]

[Tool returns results containing 'authentication' but excluding 'oauth']

Example 7: FTS5 Prefix Search

User: "find conversations mentioning anything related to auth"

Claude: [Calls mcp__vibe-check__vibe_search with query="auth*"]

[Tool returns results matching auth, authentication, authorize, authorized, etc.]

---

Related Tools

Use these complementary MCP tools:

• mcp__vibe-check__vibe_recent: Show recent sessions by time period (today, yesterday, week, month)
• mcp__vibe-check__vibe_session: Get detailed info about a specific session
• mcp__vibe-check__vibe_view: Open a session in the local web viewer
• mcp__vibe-check__vibe_stats: Show overall usage statistics

---

Error Handling

The MCP tool handles errors automatically and provides helpful messages:

• If no results found, it suggests broader search terms and checking if monitor was running
• If database not accessible, it provides file path information
• All database locking is handled internally with read-only mode

---

Tips

• For broad exploration of recent work, use vibe_recent first
• For targeted keyword searches, use vibe_search with FTS5 syntax
• Use FTS5 features for better results:
  • Phrase search ("exact phrase") for precise matches
  • Prefix search (term*) to find variations
  • Boolean operators (AND, OR, NOT) for complex queries
• Combine filters (repo + days) to narrow results
• Results are ranked by relevance - most relevant appear first with more stars
• Use vibe_view to open interesting sessions in browser for full context

---

Advanced: Custom SQL Queries

For complex queries not covered by vibe_search, use the mcp__vibe-check__vibe_sql tool:

mcp__vibe-check__vibe_sql(
    query="SELECT ... FROM conversation_events WHERE ...",
    limit=100  # optional, max 1000
)

This provides read-only access to the full database with custom SQL. See the vibe-check-sql skill for more examples.

For schema information, see ~/.vibe-check/SCHEMA.md (auto-generated) or use the Read tool.