Cursor Chat History

Connect your Cursor conversations to your git history.

Why?

You make a commit. Weeks later you wonder: "Why did I write it this way?"

The git message says fix auth bug but the real context - the debugging session, the alternatives considered, the AI suggestions - lives in a Cursor conversation you'll never find again.

This MCP server automatically links your Cursor conversations to git commits. When you revisit code, the AI assistant can pull up the original discussion.

Quick Start

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "cursor-chat-history": {
      "command": "npx",
      "args": ["-y", "--package=cursor-chat-history-mcp", "cursor-chat-history-mcp"]
    }
  }
}

That's it. Hooks install automatically on first use.

What You Can Do

Find Context for Code

"What was the context behind commit abc123?"
"Find the conversation that led to this fix"
"Show discussions about auth.ts from the last month"

Search Your Chat History

"Find all debugging sessions about performance"
"Search conversations mentioning useState"
"List recent conversations in this project"

Extract Patterns

"Create TypeScript guidelines from my actual usage"
"Extract error handling patterns from my conversations"
"Summarize my React patterns from chat history"

Available Tools

Git Linker

Tool	Purpose
get_file_context	Get conversations and commits related to a file
get_commit_conversations	Find conversations linked to a commit
list_conversation_commits	Find commits linked to a conversation
link_conversation_commit	Manually link conversation ↔ commit

Chat History

Tool	Purpose
list_conversations	Browse with filters (project, keywords, files)
get_conversation	Get full conversation content
search_conversations	Multi-keyword and pattern search
get_conversation_analytics	Usage patterns, file activity, language stats

Privacy

• 100% local - No external services, no API keys
• Your data stays on disk - SQLite databases only
• Open source - Audit the code yourself

---

How It Works

Hooks are installed automatically when the MCP server starts:

• Cursor hooks (~/.cursor/hooks.json) - capture file edits and session ends
• Git post-commit hook (current repo) - link commits to conversations

When you commit, the system finds related conversations using:

• File overlap (70%): Commits touching files discussed in conversations
• Recency (30%): Conversations from the last 14 days

Efficient Context Retrieval

Large conversations aren't loaded directly into context. Instead:

1. Use get_file_context with keywords to find relevant conversations
2. Call get_conversation - writes to ~/.cursor-chat-history/context/conversations/<id>.md
3. Use Read/Grep tools to navigate the markdown file efficiently

CLI Commands

# Query links
npx cursor-chat-history-mcp link list-conversation-links --conversation <id>
npx cursor-chat-history-mcp link get-commit-links --hash <commit-hash>

# Manual linking
npx cursor-chat-history-mcp link manual --conversation <id> --commit <hash>

Database Locations

Database	macOS	Windows	Linux
Cursor chats	~/Library/Application Support/Cursor/User/globalStorage/state.vscdb	%APPDATA%/Cursor/...	~/.config/Cursor/...
Git links	~/Library/Application Support/CursorChatHistory/links.sqlite	%APPDATA%/CursorChatHistory/...	~/.local/share/CursorChatHistory/...
Context files	~/.cursor-chat-history/context/conversations/	same	same

Override with CURSOR_DB_PATH or CURSOR_LINKS_DB_PATH.

Tool Reference

Core Tools Parameters

list_conversations

• limit (default: 10) - Number of results
• projectPath - Filter by project
• keywords - Search keywords
• hasCodeBlocks - Filter by code presence

get_conversation

• conversationId (required) - Conversation ID
• summaryOnly - Return summary only (saves context)

search_conversations

• query - Text search
• keywords + keywordOperator ('AND'/'OR') - Multi-keyword
• likePattern - SQL LIKE patterns

get_conversation_analytics

• scope - 'all', 'recent', 'project'
• projectPath - Filter by project
• includeBreakdowns - ['files', 'languages', 'temporal', 'size']

Git Linker Tools Parameters

get_file_context

• filePath (required) - File to get context for
• keywords - Filter by keywords (e.g., ["JWT", "auth"]) - returns matching excerpts
• limit - Max results (default: 5)

list_conversation_commits

• conversationId - Filter by conversation
• projectPath - Filter by project
• filePath - Filter by file

get_commit_conversations

• commitHash (required) - Git commit hash

link_conversation_commit

• conversationId (required)
• commitHash (required)
• confidence - Link confidence (0-1)

Development

git clone https://github.com/vltansky/cursor-chat-history-mcp
cd cursor-chat-history-mcp
yarn install
yarn build

Supported AI Assistants

Assistant	Status	Notes
Cursor	✅ Full	Chat, Composer, Agent modes
Claude Code	✅ Full	VS Code extension
Cline/Roo/Kilo	✅ Full	JSON task-based storage
Windsurf	✅ Full	SQLite (same pattern as Cursor)
GitHub Copilot Chat	✅ Full	VS Code native

Roadmap

• Knowledge graph extraction - Extract entities and relationships from conversations (learn more)
• Multi-agent support - Cline, Windsurf, Copilot Chat
• Quality scoring - Prioritize conversations with solutions
• Natural time filters - "last week", "yesterday"
• Topic clustering - Group by detected themes
• Semantic search - Find similar conversations via embeddings

Technical Notes

• Supports legacy and modern Cursor conversation formats
• Uses ROWID for chronological ordering (UUIDs aren't chronological)
• Close Cursor to avoid database lock issues
• See docs/SPEC.md for git linker specification

License

MIT