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.

🎯 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:

1. Build the project: npm run build
2. Configure Cursor (see MCP-SETUP.md)
3. 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

1. Read-only Access – Safely reads Cursor's internal SQLite database
2. Separate Metadata – Stores your nicknames/tags in ~/.cursor-context/metadata.db
3. Auto-sync – Automatically syncs sessions on first access
4. Project Detection – Extracts workspace paths from tool results in messages
5. 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:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass (npm test)
5. 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