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:
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
Made with ❤️ for developers who want to unlock their Cursor chat history
For detailed technical documentation, see CURSOR-CROSS-SESSION-CONTEXT.md
