lcgerke/mcp-lcg-history

mcp-lcg-history

An MCP server for retrieving and analyzing Claude Code conversation history with semantic embeddings, smart filtering, pagination, and cross-machine project identity.

Features

This MCP server provides 6 powerful tools for exploring your Claude Code conversation history:

1. list_projects 👀 Start Here

Discover all projects with Claude Code conversation history.

Why use this first: Get an overview of all available data before diving deeper.

Returns: Project IDs (canonical identifiers), all local paths for each project, session counts, message counts, and last activity time.

New: Projects are now grouped by canonical ID - the same git repository on different machines or paths will be recognized as the same project (once .claude/project.json is committed).

2. list_sessions 📁 Explore Sessions

List conversation sessions for exploration and filtering.

Parameters:

• projectPath (optional): Filter by specific project
• startDate (optional): Start date (e.g., "2025-06-30")
• endDate (optional): End date (e.g., "2025-06-30")
• timezone (optional): Timezone for date filtering (e.g., "Asia/Tokyo", "UTC")

Returns: Session IDs, timestamps, message counts, and project paths.

3. get_conversation_history 💬 Get Detailed Data

Retrieve paginated conversation history with smart filtering.

Key Features:

• Pagination: limit (default: 20) and offset for efficient data handling
• Message Filtering: messageTypes defaults to ["user"] to reduce data volume
• Timezone Support: Automatic timezone detection or specify (e.g., "Asia/Tokyo")
• Date Filtering: Smart date normalization with timezone awareness

Parameters:

• sessionId (optional): Specific session ID
• startDate (optional): Start date (e.g., "2025-06-30")
• endDate (optional): End date (e.g., "2025-06-30")
• limit (optional): Max entries per page (default: 20)
• offset (optional): Skip entries for pagination (default: 0)
• messageTypes (optional): ["user"] (default), ["user", "assistant"], etc.
• timezone (optional): e.g., "Asia/Tokyo", "UTC" (auto-detected)

Example:

{
  "startDate": "2025-06-30",
  "limit": 50,
  "messageTypes": ["user"],
  "timezone": "Asia/Tokyo"
}

Response includes pagination info:

{
  "entries": [...],
  "pagination": {
    "total_count": 150,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

4. search_conversations 🔍 Find Specific Content

Search across all conversation content by keywords with semantic search and advanced filtering.

New: You can now search by projectId to search across all paths with the same project identity!

Parameters:

• query (required): Search terms
• projectPath (optional): Project path (e.g., "-home-user-myproject") - use this OR projectId
• projectId (optional): Project UUID to search across all paths - use this OR projectPath
• limit (optional): Max results (default: 10)
• recencyFilterMinutes (optional): Exclude messages from last N minutes (default: 1, set to 0 to disable)
• startDate (optional): Start date (e.g., "2025-06-30")
• endDate (optional): End date (e.g., "2025-06-30")
• timezone (optional): Timezone for date filtering (e.g., "Asia/Tokyo", "UTC")

Example (by path):

{
  "query": "cache optimization",
  "projectPath": "-home-user-myproject",
  "limit": 5,
  "recencyFilterMinutes": 5
}

Example (by project ID - searches all paths):

{
  "query": "cache optimization",
  "projectId": "550e8400-e29b-41d4-a716-446655440000",
  "limit": 10
}

5. get_messages_before_compaction 📋 Recover Context After Clear

Retrieve conversation history from before a compact/clear event to recover lost context.

Use Case: After using /clear or /compact, recover the conversation that was lost.

Parameters:

• projectPath (required): Project directory path
• compactionOffset (optional): Which compaction - 1=most recent (default), 2=second most recent
• lookbackCount (optional): Number of messages to retrieve (default: 50, max: 500)
• messageTypes (optional): Filter by type (default: ["user", "assistant"])
• previewOnly (optional): Return only metadata without messages (default: false)

Example:

{
  "projectPath": "/home/user/my-project",
  "compactionOffset": 1,
  "lookbackCount": 50,
  "messageTypes": ["user", "assistant"]
}

Returns:

• Messages before the compaction
• Window boundaries (when the compaction occurred)
• Pagination info (hasMore for additional messages)

6. get_version ℹ️ Get Server Version

Get the current version of the mcp-lcg-history server.

Use Case: Verify which version of the server is running.

Returns:

• Server version number

Example:

{}

Quick Start

Prerequisites

• Go 1.21 or later - Download
• Claude Desktop 0.5.0+ - Download

Installation

# Clone the repository
git clone https://github.com/lcgerke/claude-code-history-mcp.git
cd claude-code-history-mcp

# Build the pure Go MCP server
go build -o build/claude-historian-pure ./cmd/claude-historian-pure

# Verify it works
./build/claude-historian-pure --version

Configuration

Add to your Claude Desktop config (~/.config/claude/mcp.json or platform equivalent):

{
  "mcpServers": {
    "claude-historian": {
      "command": "/full/path/to/claude-code-history-mcp/build/claude-historian-pure",
      "args": [],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

Important: Replace /full/path/to/ with the actual absolute path to your installation.

Restart Claude Desktop after configuration.

Recommended Workflow 🚀

1. Explore Available Data

// Start with list_projects to see what's available
{"tool": "list_projects"}

2. Find Relevant Sessions

// List sessions for a specific project or date range with timezone
{
  "tool": "list_sessions",
  "projectPath": "/Users/yourname/code/my-project",
  "startDate": "2025-06-30",
  "timezone": "Asia/Tokyo"
}

3. Get Targeted Data

// Get conversation history with optimal settings
{
  "tool": "get_conversation_history", 
  "sessionId": "specific-session-id",
  "messageTypes": ["user"],  // Only your inputs (default)
  "limit": 50
}

Data Source

This server reads Claude Code history files (.jsonl format) stored in ~/.claude/projects/.

Smart Features 💡

Message Type Filtering

• Default: Only ["user"] messages to reduce data volume
• Full conversation: Use ["user", "assistant"]
• Everything: Use ["user", "assistant", "system", "result"]

Timezone Intelligence

• Automatically detects your system timezone
• Supports explicit timezone specification (e.g., "Asia/Tokyo")
• Smart date normalization (e.g., "2025-06-30" → proper timezone bounds)

Pagination Support

• Efficient handling of large datasets
• total_count helps you understand data volume
• has_more indicates if there's additional data

Use Cases

Daily Work Review

What did I work on today?

1. list_projects → See active projects
2. get_conversation_history with today's date and messageTypes: ["user"]

Project Deep Dive

Analyze my recent work on Project X

1. list_sessions with specific project path
2. get_conversation_history for relevant sessions
3. Use pagination to browse through all data

Topic Research

Find all conversations about "API integration" in a specific project

1. search_conversations with query "API integration", projectPath, and date range
2. Use results to identify relevant sessions
3. get_conversation_history for detailed context

Example with advanced filtering:

{
  "tool": "search_conversations",
  "query": "API integration",
  "projectPath": "/Users/yourname/code/my-project",
  "startDate": "2025-06-01",
  "endDate": "2025-06-30",
  "timezone": "Asia/Tokyo",
  "limit": 50
}

Project Identity & Cross-Machine Recognition 🆔

New Feature: Projects are now identified by a canonical UUID that travels with your git repository.

How It Works

When you first access a git repository with this tool, it automatically:

1. Creates .claude/project.json at the git root with a unique UUID
2. Auto-stages the file (ready for your next commit)
3. Uses this UUID to identify the project across machines/paths

Example .claude/project.json:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "created": "2025-01-11T15:30:00Z",
  "tool_version": "1.0.0",
  "type": "git",
  "git_root": "/home/user/my-project"
}

Benefits

✅ Rename-Safe: Move or rename your repo - the ID stays the same ✅ Cross-Machine Recognition: Same repo on different machines shares the same project ID (once committed) ✅ Worktree Support: All git worktrees of the same repo share the same ID ✅ Path Grouping: list_projects groups by ID, showing all local paths ✅ Backward Compatible: Non-git projects still work using path-based IDs

What This Enables

• Project Recognition: Tool knows /home/alice/repo and /home/bob/repo are the same project
• Aggregated Statistics: Session/message counts combined across all paths
• Cross-Path Search: Use projectId in search_conversations to search all paths at once
• Foundation for Future Sync: Canonical IDs make it possible to sync conversations later

What This Doesn't Do (Yet)

⚠️ Conversation history is still machine-local - the .jsonl files in ~/.claude/projects/ are not synced between machines. Project identity provides recognition and grouping, but actual conversation unification across machines is future work.

Getting Started

For Git Repositories:

1. Use any tool from this MCP server
2. .claude/project.json is created automatically on first access
3. Commit the file: git add .claude/project.json && git commit -m "Add Claude project identity"
4. Push to remote so other machines get the same ID

For Non-Git Projects:

• No action needed - path-based IDs work automatically

Recommended .gitignore

Add this to your project's .gitignore to keep project identity while excluding other Claude files:

# Exclude all Claude files
.claude/*

# But keep project identity (checked in)
!.claude/project.json

Architecture

This MCP server uses a pure Go architecture powered by the official Go MCP SDK:

• Pure Go MCP Server (/cmd/claude-historian-pure): Native MCP protocol implementation
• Integrated Services: History tracking, semantic search, embeddings, and caching all in one binary
• No Dependencies: Single compiled binary with no runtime requirements

Why Pure Go?

• Official SDK: Uses github.com/modelcontextprotocol/go-sdk for native MCP support
• Performance: Fast startup, low memory footprint, efficient concurrency
• Simplicity: Single binary, easy deployment, no npm/Node.js required
• Reliability: Static compilation, no runtime dependencies

User/Claude Code → Pure Go MCP Server
                    (MCP Protocol + Semantic Search + Caching)

Performance & Caching 🚀

The server uses a tiered cache architecture for lightning-fast searches:

Cache Architecture

• L1 Cache: Fast in-memory LRU cache (default: 500 entries)
• L2 Cache: Persistent disk cache using BBolt (survives restarts)
• Automatic Promotion: L2 hits promoted to L1 for faster subsequent access
• Graceful Degradation: Falls back to L1-only if L2 initialization fails

Performance Improvements

Configuration

Configure caching via environment variables:

{
  "mcpServers": {
    "claude-historian": {
      "command": "/path/to/build/claude-historian-pure",
      "args": [],
      "env": {
        "CLAUDE_HISTORIAN_CACHE_DIR": "/custom/cache/path",
        "CLAUDE_HISTORIAN_L1_SIZE": "1000"
      }
    }
  }
}

Environment Variables:

• CLAUDE_HISTORIAN_CACHE_DIR: Cache directory (default: ~/.cache/claude-historian)
• CLAUDE_HISTORIAN_L1_SIZE: L1 cache size (default: 500)
• CLAUDE_HISTORIAN_MODEL_PATH: Path to embedding model (optional)
• CLAUDE_HISTORIAN_LOG_LEVEL: Log level - DEBUG, INFO, WARN, ERROR (default: WARN)

Cache Diagnostics

The worker logs helpful cache diagnostics on startup:

WARN: L2 cache is empty (32KB baseline) - embeddings will be cached as they are computed
WARN: L2 cache loaded with existing embeddings count=100 hint="warm cache will provide 100x faster searches"

To see detailed cache statistics, set CLAUDE_HISTORIAN_LOG_LEVEL=INFO:

{
  "mcpServers": {
    "claude-historian": {
      "command": "/path/to/build/claude-historian-pure",
      "args": [],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

Cache Management

View cache status:

ls -lh ~/.cache/claude-historian/embeddings.db

Clear cache (force rebuild):

rm ~/.cache/claude-historian/embeddings.db

Cache file size: Approximately 4KB per embedding (10,000 embeddings ≈ 40MB)

Troubleshooting

If searches are slow after restart:

1. Check cache directory permissions: ls -la ~/.cache/claude-historian/
2. Verify cache file exists: ls -lh ~/.cache/claude-historian/embeddings.db
3. Check logs for warnings about L2 cache initialization

If cache grows too large:

1. Remove the cache file to start fresh
2. Reduce L1 cache size with CLAUDE_HISTORIAN_L1_SIZE
3. Consider a different cache directory with more space

License

MIT