Which integrations are available for this server?

Provides read-only access to Cursor's internal SQLite database to retrieve chat session history and metadata

How do I use Chat Context MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Chat Context MCP find my chat about implementing authentication from last week" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Cursor Cross-Session Context Retrieval

Unlock the power of your Cursor chat history – Search, organize, and retrieve context from past conversations to enhance your AI-assisted development workflow.

Tests TypeScript License

🎯 The Problem

Every Cursor Composer session is isolated – when you start a new chat, the AI has no memory of your previous conversations. This leads to:

❌ Repeating context and explanations
❌ Lost architectural decisions and discussions
❌ Manual copy-pasting from old chats
❌ Difficulty finding specific conversations
❌ No organization or categorization of chat history

✨ The Solution

This library gives you programmatic access to your entire Cursor chat history with powerful organization and retrieval features:

✅ Nickname sessions – Give chats memorable names instead of UUIDs
✅ Tag & organize – Categorize sessions by feature, bug, topic, etc.
✅ Project-scoped search – Automatically filters chats by project
✅ Full-text search – Search across nicknames, tags, messages, and projects
✅ Rich formatting – Export sessions as Markdown, JSON, or compact previews
✅ Type-safe API – Fully typed TypeScript interface

🚀 Quick Start

Installation

npm install cursor-context-core

CLI Tool

The package includes a powerful command-line interface:

# Show statistics
cursor-context stats

# List sessions
cursor-context list --limit 10

# Search for sessions
cursor-context search "authentication"

# Get session details
cursor-context get my-nickname --format markdown

# Set nickname and tags
cursor-context nickname abc-123 my-important-chat
cursor-context tag add abc-123 feature backend

See CLI.md for complete CLI documentation.

MCP Server

Let AI automatically search and retrieve past chat sessions:

Setup:

Build the project: npm run build
Configure Cursor (see MCP-SETUP.md)
Restart Cursor

Usage in Chat:

You: "How did I implement authentication in that project?"

AI: *Automatically calls search_sessions tool*
    "I found your session 'auth-implementation' from 5 days ago..."

You: "Load that session"

AI: *Calls get_session tool*
    [Shows full conversation]

The AI decides when to search based on your conversation. See MCP-SETUP.md for setup instructions.

Library Usage

import { CursorContext } from 'cursor-context-core';

// Create API instance (auto-detects Cursor DB path)
const api = new CursorContext();

// Sync recent sessions
await api.syncSessions(50);

// Give a session a nickname
await api.setNickname('session-id', 'auth-implementation');
await api.addTag('session-id', 'feature');

// Retrieve by nickname
const session = await api.getSession('auth-implementation');
console.log(session.messages);

// Search across all sessions
const results = await api.searchSessions({ 
  query: 'authentication',
  projectPath: '/path/to/project'
});

// Clean up
api.close();

📚 Core Features

1. Session Management

// List sessions with filtering
const sessions = await api.listSessions({
  projectPath: '/path/to/project',  // Filter by project
  sortBy: 'newest',                 // newest, oldest, most_messages
  limit: 10,                        // Limit results
  tag: 'feature',                   // Filter by tag
  taggedOnly: true                  // Only tagged sessions
});

// Get a specific session
const session = await api.getSession('nickname-or-id', {
  includeMessages: true,           // Load full messages
  parseOptions: {
    excludeTools: false,           // Include tool calls
    maxContentLength: 10000        // Truncate long messages
  }
});

2. Organization

// Set nicknames
await api.setNickname('session-id', 'database-migration');

// Add tags
await api.addTag('session-id', 'backend');
await api.addTag('session-id', 'database');

// Remove tags
await api.removeTag('session-id', 'backend');

// List all tags
const tags = api.getTags();
// [{ tag: 'backend', count: 15 }, { tag: 'frontend', count: 8 }, ...]

3. Search

// Simple search
const results = await api.searchSessions({ 
  query: 'authentication' 
});

// Advanced search
const results = await api.searchSessions({
  query: 'API endpoints',
  projectPath: '/my/project',      // Scope to project
  taggedOnly: true,                // Only tagged sessions
  limit: 20,                       // Limit results
  caseSensitive: false             // Case sensitivity
});

4. Project Management

// List all projects
const projects = api.getProjects();
// [
//   { path: '/path/to/project', name: 'my-app', session_count: 42 },
//   ...
// ]

// Get sessions for a specific project
const projectSessions = await api.listSessions({
  projectPath: '/path/to/project'
});

5. Formatting

import { 
  formatSessionMarkdown, 
  formatSessionJSON,
  formatSessionPreview,
  formatSessionList
} from 'cursor-context-core';

// Markdown format (great for AI context)
const markdown = formatSessionMarkdown(session, {
  maxMessages: 10,          // Limit messages
  includeTools: true,       // Include tool calls
  includeMetadata: true     // Include header
});

// JSON format
const json = formatSessionJSON(session);

// Compact preview
const preview = formatSessionPreview(session.metadata);
// "📝 auth-implementation • 📁 my-app • 💬 42 • 📅 2 days ago"

// List of sessions
const list = formatSessionList(sessions);

6. Statistics

const stats = api.getStats();
console.log(stats);
// {
//   totalSessionsInCursor: 560,
//   totalSessionsWithMetadata: 50,
//   sessionsWithNicknames: 12,
//   sessionsWithTags: 25,
//   sessionsWithProjects: 35,
//   totalTags: 15,
//   totalProjects: 8
// }

🏗️ Architecture

Core Modules

src/core/
├── api.ts              # Main CursorContext API
├── cursor-db.ts        # Read-only access to Cursor's SQLite DB
├── metadata-db.ts      # Separate DB for nicknames/tags
├── message-parser.ts   # Parse Lexical richText format
├── workspace-extractor.ts  # Extract project paths from tool results
├── formatter.ts        # Format sessions for output
├── platform.ts         # Platform detection (macOS/Linux/Windows)
├── errors.ts          # Custom error types
└── types.ts           # TypeScript interfaces

How It Works

Read-only Access – Safely reads Cursor's internal SQLite database
Separate Metadata – Stores your nicknames/tags in ~/.cursor-context/metadata.db
Auto-sync – Automatically syncs sessions on first access
Project Detection – Extracts workspace paths from tool results in messages
Smart Parsing – Handles Cursor's complex Lexical richText format

📖 Advanced Usage

Custom Database Paths

const api = new CursorContext(
  '/custom/path/to/cursor.db',
  '/custom/path/to/metadata.db',
  true  // Enable auto-sync
);

Direct Database Access

// Access underlying databases for advanced operations
const cursorDB = api.getCursorDB();
const metadataDB = api.getMetadataDB();

// List all composer IDs
const allIds = cursorDB.listComposerIds(1000);

// Get raw composer data
const composerData = cursorDB.getComposerData('session-id');

Batch Operations

// Sync many sessions
const synced = await api.syncSessions(100);
console.log(`Synced ${synced} new sessions`);

// Bulk tagging
const sessions = await api.listSessions({ limit: 50 });
for (const session of sessions) {
  if (session.has_project) {
    await api.addTag(session.session_id, `project:${session.project_name}`);
  }
}

🧪 Testing

The library includes 169 comprehensive tests:

# Run all tests
npm test

# Run specific test suite
npm test tests/core/api.test.ts

# Watch mode
npm run test:watch

# Build
npm run build

Test coverage includes:

✅ Unit tests for each module
✅ Integration tests for the API
✅ End-to-end workflow tests
✅ Error handling and edge cases

🛠️ Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run examples
npm run dev examples/test-api.ts

# Run tests
npm test

📋 Database Schema

Cursor's Database (`state.vscdb`)

-- Key-value store
cursorDiskKV (
  key TEXT PRIMARY KEY,     -- e.g., "composerData:{uuid}"
  value TEXT                -- JSON data
)

Metadata Database (`~/.cursor-context/metadata.db`)

session_metadata (
  session_id TEXT PRIMARY KEY,
  nickname TEXT UNIQUE,
  tags TEXT,                    -- Comma-separated
  project_path TEXT,
  project_name TEXT,
  has_project INTEGER,
  created_at INTEGER,
  last_accessed INTEGER,
  first_message_preview TEXT,
  message_count INTEGER
)

🔒 Security & Privacy

✅ Read-only access to Cursor's database
✅ Local-only – No data sent to external servers
✅ Separate metadata – Your organization data is stored separately
✅ Retry logic – Handles database locks gracefully
✅ No modifications – Never writes to Cursor's internal database

🎯 Use Cases

1. MCP Server (Recommended)

Integrate with Cursor's Model Context Protocol to let AI automatically fetch context:

// MCP tool: list_sessions
const sessions = await api.listSessions({ limit: 10 });

// MCP tool: fetch_session_by_nickname
const session = await api.getSession('auth-implementation');
return formatSessionMarkdown(session);

2. CLI Tool

Build a command-line interface:

cursor-context list --project /path/to/project
cursor-context get auth-implementation --format markdown
cursor-context search "authentication" --limit 5
cursor-context tag session-id feature backend

3. VS Code Extension

Create a sidebar that shows session history with search and filters.

4. Custom Integrations

Export sessions to Notion/Obsidian
Generate documentation from chat history
Analyze development patterns
Create knowledge bases

🗺️ Roadmap

Phase 1: Core Library ✅ (Complete!)

✅ Database access
✅ Message parsing
✅ Metadata management
✅ Full API with search, tagging, formatting
✅ 169 comprehensive tests

Phase 2: CLI Tool ✅ (Complete!)

✅ List, get, search commands
✅ Nickname and tag management
✅ Stats and projects views
✅ Configuration management
✅ Multiple output formats (table, json, markdown, compact)
✅ Color support
Interactive TUI mode (future)
Shell completion (future)

Phase 3: MCP Server ✅ (Complete!)

✅ MCP protocol implementation
✅ 9 tool definitions with clear descriptions
✅ AI-invoked session search and retrieval
✅ Session management (tag, nickname)
✅ Universal (works in Cursor, VSCode, Claude Desktop)
✅ Stdio-based communication
✅ Integration with core library

Phase 4: VSCode/Cursor Extension (Future)

Slash commands (/chat, /chat search, etc.)
Session browser UI (sidebar panel)
Quick pick menus for explicit control
Status bar integration
Right-click context menus
User-invoked actions (vs AI-invoked in MCP)

Phase 5: Advanced Features

Full-text search with SQLite FTS5
Session similarity matching (vector embeddings)
Automatic tagging with AI
Multi-workspace support
Session analytics and insights

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass (npm test)
Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Built for the Cursor AI code editor
Uses better-sqlite3 for database access
Tested with Vitest

Made with ❤️ for developers who want to unlock their Cursor chat history

For detailed technical documentation, see CURSOR-CROSS-SESSION-CONTEXT.md