Skip to main content
Glama
cowork-history

cowork-history

by egoughnour

Cowork History MCP

An MCP (Model Context Protocol) server for searching and browsing your Claude conversation history stored in ~/.claude/. Works with both Claude Code and Cowork conversations.

Features

  • Hybrid Search - Combines multiple search methods for best results:

    • SQLite FTS5 - Fast full-text search with BM25 ranking

    • macOS Spotlight - Leverages system content indexing via mdfind

    • Vector Embeddings - Semantic similarity search (optional, requires Ollama)

  • Smart Path Reconstruction - Recovers actual filesystem paths via probing (not heuristic guessing)

  • Persistent Index - SQLite database with incremental updates for fast queries

  • Ollama Setup Tools - Automated installation and configuration for embeddings

Related MCP server: Memex

Installation

Option 1: Claude Desktop (One-Click Install)

Download cowork-history.mcpb from the latest release and double-click to install.

uvx cowork-history

Option 3: Via pip

pip install cowork-history

Option 4: Manual Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "cowork-history": {
      "command": "uvx",
      "args": ["cowork-history"],
      "env": {
        "OLLAMA_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "nomic-embed-text"
      }
    }
  }
}

Quick Start

Once installed, Claude can search your conversation history:

"What did we discuss about authentication last week?"
"Find the conversation where we debugged the payment webhook"
"Show me my conversations in the my-project folder"

Available Tools

Search & Browse

Tool

Description

cowork_history_search

Search conversations using hybrid search (FTS + Spotlight + vector)

cowork_history_list

List recent conversations, optionally filtered by project

cowork_history_get

Get full content of a specific conversation by session ID

cowork_history_projects

List all projects with conversation history

cowork_history_stats

Get statistics and search capability status

cowork_history_reindex

Rebuild index and optionally generate embeddings

Tool

Description

history_system_check

Check system requirements for Ollama

history_setup_ollama

Install Ollama via Homebrew (macOS)

history_setup_ollama_direct

Install Ollama via direct download (no Homebrew)

history_ollama_status

Check Ollama status and embedding model availability

Search Modes

The cowork_history_search tool supports multiple search modes:

Mode

Description

auto (default)

Uses all available methods, best results

fts

Full-text search only (fastest)

spotlight

macOS Spotlight only

vector

Semantic similarity only (requires Ollama)

hybrid

Explicit combination with ranking

Search Examples

"authentication bug"           → finds conversations with both words
"how to deploy"                → semantic search finds related discussions
"\"exact phrase\""             → exact phrase matching
project:"my-app" "database"    → filter by project

Vector search provides semantic similarity matching (finding related concepts even without exact keywords). It requires Ollama with an embedding model.

Quick Setup

Ask Claude to set it up for you:

"Set up Ollama for vector search"

Or manually:

# Install Ollama (macOS)
brew install ollama

# Start Ollama service
brew services start ollama

# Pull the embedding model
ollama pull nomic-embed-text

Then generate embeddings:

"Rebuild the history index with embeddings"

How It Works

Indexing

The server maintains a SQLite database at ~/.claude/.history-index/conversations.db with:

  • FTS5 virtual table for fast full-text search

  • Conversation metadata (session ID, project, timestamps, topic)

  • Full content for comprehensive search

  • Path cache for reconstructed paths

  • Embeddings table for vector search (optional)

The index updates automatically when you search (if >5 minutes old) or you can force a rebuild with cowork_history_reindex.

Environment Variables

Variable

Default

Description

OLLAMA_URL

http://localhost:11434

Ollama server URL

EMBEDDING_MODEL

nomic-embed-text

Ollama embedding model

Troubleshooting

No conversations found

  1. Make sure ~/.claude/ directory exists

  2. Check that you have conversation history (use Claude Code or Cowork first)

  3. Verify the MCP server is properly configured

Vector search not available

  1. Check Ollama is installed: ollama --version

  2. Check Ollama is running: curl http://localhost:11434/api/tags

  3. Check model is available: ollama list

  4. Pull embedding model: ollama pull nomic-embed-text

Search not finding expected results

  • Try natural language queries (semantic search is more flexible)

  • Use mode: "fts" for exact phrase matching

  • Check cowork_history_stats to see which search backends are active

Development

Running locally

# Clone the repository
git clone https://github.com/egoughnour/cowork-history
cd cowork-history

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run the server directly
python -m src.cowork_history_server

Testing with MCP Inspector

npx @modelcontextprotocol/inspector uvx cowork-history

License

MIT License - see LICENSE file for details.

Available Tools

10 tools
cowork_history_getGet Conversation DetailsA
Read-onlyIdempotent

Get full content of a specific conversation by session ID.

Inputs: params (required). Returns: result

cowork_history_listList Recent ConversationsA
Read-onlyIdempotent

List recent Claude conversations from the index, sorted by modification time.

Inputs: params (required). Returns: result

cowork_history_projectsList ProjectsB
Read-onlyIdempotent

List all projects with conversation history, showing reconstructed paths.

Inputs: params (required). Returns: result

cowork_history_reindexRebuild IndexA
Idempotent

Rebuild the conversation index and optionally generate embeddings.

Inputs: params (required). Returns: result

cowork_history_statsGet StatisticsB
Read-onlyIdempotent

Get statistics about conversation history and search capabilities.

Inputs: params (required). Returns: result

history_ollama_statusA

Check Ollama server status and available models.

Returns whether Ollama is running and if the embedding model is available. Use to check if semantic/vector search is available.

Inputs: force_refresh. Returns: object

history_setup_ollamaA

Install Ollama via Homebrew (macOS).

Requires Homebrew pre-installed. Uses 'brew install' and 'brew services'. PROS: Auto-updates, pre-built binaries, managed service. CONS: Requires Homebrew, may prompt for sudo on first install.

Inputs: model, install, pull_model, start_service. Returns: object

history_setup_ollama_directA

Install Ollama via direct download (macOS).

Downloads from ollama.com to ~/Applications. PROS: No Homebrew needed, no sudo required, fully headless. CONS: Manual PATH setup, no auto-updates.

Inputs: model, install, pull_model, start_service. Returns: object

history_system_checkA

Check if system meets requirements for Ollama embeddings.

Verifies: macOS, Apple Silicon (M1/M2/M3/M4), RAM, Homebrew. Use before attempting Ollama setup.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 10 tools

    Disambiguation3/5

    Most tools are distinct, but history_setup_ollama_direct and history_setup_ollama overlap as two installation methods for the same software. history_system_check and history_ollama_status are also somewhat related, though they check different aspects. Descriptions help clarify, but some ambiguity remains.

    Naming Consistency2/5

    Naming is inconsistent: tools use two different prefixes (history_ vs cowork_history_) and mix verb-first (setup_ollama, search) with noun-first (system_check, ollama_status) patterns. This makes the tool set feel disjointed and harder to predict.

    Tool Count4/5

    10 tools is within a reasonable range, but four of them are dedicated to Ollama setup/status, which is an optional dependency. This makes the set slightly heavier than necessary, though each tool still serves a distinct purpose.

    Completeness4/5

    The core history tools cover search, list, get, projects, stats, and reindex, providing solid lifecycle coverage for querying and maintaining conversation history. Minor gaps exist, such as lack of delete or export functionality, but they are not critical for the primary use case.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables comprehensive search and analysis of Claude Code conversation history using full-text search, optional semantic vector search, and conversation management tools. Provides fast SQLite-based indexing with role-based filtering, project organization, and hybrid search capabilities combining keyword and semantic matching.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables searching and retrieving Claude Code conversation history that would otherwise expire after 30 days. Supports full-text search, semantic search, and session management with automatic backup of all conversations.
      28
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables searching and retrieving Claude Code conversation history via hybrid semantic and keyword search, allowing the agent to access its own past interactions.
      142 PyPI
      5
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables searching and browsing past Claude Code conversations directly from within an active Claude session, with full-text search and cost tracking.
      MIT