Claude Code History Search (cch)

A local CLI intelligence layer for Claude Code sessions. Provides asynchronous background indexing, file archiving, and semantic hybrid search over your Claude Code history.

Architecture

~/.claude/projects/
      ↓
  [Daemon Watcher] (chokidar) ━━━━> [Archiver] ━━> ~/.cc-memory/archive/
      ↓
  [Indexer / Parser]  (better-sqlite3)
      ↓    [vec0 / FTS5]
  ~/.cc-memory/index.db
      ↓
  [Hybrid Query CLI]
      ↑
   cch ask

Quick Start

1. Install globally: npm install -g claude-history-search
2. Start the daemon (runs background indexing and archiver): cch daemon start
3. Ask your semantic queries: cch ask "how did we fix the react router auth bug?"

CLI Commands

• cch daemon start: Start the background watcher/indexer daemon.
• cch daemon stop: Stop the background daemon.
• cch daemon status: Shows heartbeat and PID if running.
• cch ask <query>: Natural language search against all tracked exchanges using hybrid Cosine Similarity + BM25 ranking. Use --no-content to print only metadata (project, date, score, session ID) without conversation text.

  Privacy note: ask prints conversation content to stdout. Do not pipe output to shared logs or public channels.

• cch search <query>: Lighter session-level semantic search.
• cch status: Print index sizing metrics (total sessions, exchanges tracked).
• cch archive --now: Force immediate sweep and archive of expiring session files.
• cch index --reset: Stop the daemon, wipe the local DB, and require restart.
• cch index --rebuild-fts: Rebuild the FTS5 keyword index (use if keyword search returns stale results).
• cch config: Open configuration settings in $EDITOR.

Config Options

Configurations are saved in ~/.cc-memory/config.json.

• embeddingModel: "local" (default). Note: "openai" is listed as a future option but is not yet implemented.
• archiveIntervalHours: Archiver routine timer (default: 6).
• archiveWarningGb: Max folder size before warnings emit (default: 2).
• searchResultCount: Number of results returned by ask and search (default: 5).
• vectorWeight: Weight for vector similarity in hybrid search, between 0 and 1 (default: 0.6). The keyword weight is 1 - vectorWeight.

Note: Index freshness warnings and detailed health checks in cch status (e.g., stale index detection, embedding model availability, archive staleness) are planned for a future release.