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

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Enables AI to automatically search, retrieve, and organize your Cursor chat history across sessions. Supports tagging, nicknames, project-scoped search, and full-text search to maintain context between conversations.