# Cursor IDE Observability Schema

**Cross-validated against actual data from ~/.cursor and ~/Library/Application Support/Cursor**

---

## Overview

Cursor stores data across multiple locations:

1. **`~/Library/Application Support/Cursor/`** - Main app data (SQLite DBs, settings)
2. **`~/.cursor/`** - User config, MCP servers, projects metadata, agent transcripts (newer)
3. **`<workspace>/.cursor/`** - Per-project plans, scratchpad, rules

---

## 1. Core SQLite Databases

### 1.1 Global State Database

**Path:** `~/Library/Application Support/Cursor/User/globalStorage/state.vscdb`

**Tables:**

```sql
CREATE TABLE ItemTable (key TEXT UNIQUE ON CONFLICT REPLACE, value BLOB);
CREATE TABLE cursorDiskKV (key TEXT UNIQUE ON CONFLICT REPLACE, value BLOB);
```

#### ItemTable Key Patterns (Verified)

| Key Pattern | Description | Value Type |
|-------------|-------------|------------|
| `aiCodeTracking.dailyStats.v1.5.<date>` | Daily usage stats | JSON |
| `aiCodeTrackingLines` | Tracked code hashes with composer IDs | JSON array |
| `aiCodeTrackingScoredCommits` | Commits scored for AI attribution | JSON |
| `cursor/memoriesEnabled` | Memories feature flag | boolean |
| `cursor/pendingMemories` | Memories queue for review | JSON array |
| `cursorAuth/accessToken` | Auth token | string |
| `cursorAuth/cachedEmail` | User email | string |
| `cursorAuth/stripeMembershipType` | Subscription tier | string |
| `cursorai/serverConfig` | Server-side feature config | JSON |
| `cursorai/featureConfigCache` | Feature flags | JSON |
| `workbench.panel.aichat.view.aichat.chatdata` | Legacy chat panel data | JSON |
| `workbench.backgroundComposer.persistentData` | Background agent state | JSON |
| `cursor/notepadState` | Notepad entries | JSON |

#### Key JSON Schemas

**Daily Stats (`aiCodeTracking.dailyStats.v1.5.<date>`):**
```json
{
  "date": "2026-02-05",
  "tabSuggestedLines": 11,
  "tabAcceptedLines": 2,
  "composerSuggestedLines": 701,
  "composerAcceptedLines": 702
}
```

**Pending Memories (`cursor/pendingMemories`):**
```json
[
  {
    "id": "uuid",
    "memory": "User preference description",
    "title": "Short title",
    "requestId": "uuid",
    "composerId": "uuid",
    "timestamp": 1753426132473
  }
]
```

**Server Config (`cursorai/serverConfig`) - Key fields:**
```json
{
  "chatConfig": {
    "fullContextTokenLimit": 30000,
    "maxRuleLength": 100000,
    "maxMcpTools": 100
  },
  "backgroundComposerConfig": {
    "enableBackgroundAgent": true,
    "maxWindowInWindows": 10
  },
  "indexingConfig": {
    "maxConcurrentUploads": 64,
    "absoluteMaxNumberFiles": 100000
  }
}
```

---

### 1.2 Workspace State Database

**Path:** `~/Library/Application Support/Cursor/User/workspaceStorage/<hash>/state.vscdb`

**Mapping:** Each `<hash>` folder has a `workspace.json`:
```json
{
  "folder": "file:///path/to/workspace"
}
```

#### ItemTable Key Patterns (Verified)

| Key Pattern | Description | Value Type |
|-------------|-------------|------------|
| `aiService.prompts` | Prompt history | JSON array |
| `aiService.generations` | Generation history | JSON |
| `composer.composerData` | Composer threads index | JSON |
| `workbench.panel.composerChatViewPane.<uuid>` | Chat pane states | JSON |

**Composer Data Schema (`composer.composerData`):**
```json
{
  "allComposers": [
    {
      "type": "head",
      "composerId": "uuid",
      "createdAt": 1768989268373,
      "lastUpdatedAt": 1769708023016,
      "unifiedMode": "agent",           // "agent", "chat", "edit"
      "forceMode": "edit",
      "hasUnreadMessages": false,
      "totalLinesAdded": 0,
      "totalLinesRemoved": 0,
      "hasBlockingPendingActions": false,
      "isArchived": false,
      "isDraft": true,
      "isWorktree": false,
      "isSpec": false,
      "isProject": false,
      "isBestOfNSubcomposer": false,
      "numSubComposers": 0,
      "referencedPlans": [],
      "name": "Conversation title",
      "subtitle": "Context info",
      "contextUsagePercent": 23.35,
      "filesChangedCount": 0,
      "createdOnBranch": "main"
    }
  ],
  "selectedComposerIds": ["uuid"],
  "lastFocusedComposerIds": ["uuid"],
  "hasMigratedComposerData": true
}
```

**AI Service Prompts (`aiService.prompts`):**
```json
[
  {
    "text": "user query",
    "commandType": 1
  }
]
```

---

### 1.3 AI Code Tracking Database

**Path:** `~/.cursor/ai-tracking/ai-code-tracking.db`

**Tables:**

```sql
CREATE TABLE ai_code_hashes (
  hash TEXT PRIMARY KEY,
  source TEXT NOT NULL,          -- "tab", "composer"
  fileExtension TEXT,
  fileName TEXT,
  requestId TEXT,
  conversationId TEXT,
  timestamp INTEGER,
  createdAt INTEGER NOT NULL,
  model TEXT
);
CREATE INDEX idx_ai_code_hashes_createdAt ON ai_code_hashes(createdAt);

CREATE TABLE scored_commits (
  commitHash TEXT NOT NULL,
  branchName TEXT NOT NULL,
  scoredAt INTEGER NOT NULL,
  PRIMARY KEY (commitHash, branchName)
);

CREATE TABLE conversation_summaries (
  conversationId TEXT PRIMARY KEY,
  title TEXT,
  tldr TEXT,
  overview TEXT,
  summaryBullets TEXT,
  model TEXT,
  mode TEXT,
  updatedAt INTEGER NOT NULL
);
CREATE INDEX idx_conversation_summaries_updatedAt ON conversation_summaries(updatedAt);

CREATE TABLE tracking_state (
  key TEXT PRIMARY KEY,
  value TEXT NOT NULL
);
```

**Sample `ai_code_hashes` row:**
```
hash|source|fileExtension|fileName|requestId|conversationId|timestamp|createdAt|model
bcb53981|tab||Untitled-2|52a841d6-...|...|1767665819549|1767665819549|
```

---

## 2. File-Based Storage

### 2.1 Agent Transcripts (NEW - Not in original research)

**Path:** `~/.cursor/projects/<project-slug>/agent-transcripts/<composerId>.txt`

**Format:** Plain text with YAML frontmatter and structured conversation:
```
user:
<user_query>
User message here
</user_query>

A:
<think>
Agent reasoning...
</think>

[Tool call] ToolName
  param1: value1
  param2: value2

[Tool result] ToolName

A:
Response text...
```

### 2.2 Terminal Sessions

**Path:** `~/.cursor/projects/<project-slug>/terminals/<id>.txt`

**Format:** Plain text with YAML frontmatter:
```yaml
---
pid: 79706
cwd: /path/to/workspace
---
<terminal output content>
```

### 2.3 MCP Server Metadata

**Path:** `~/.cursor/projects/<project-slug>/mcps/<server-name>/`

**Structure:**
```
mcps/<server-name>/
├── SERVER_METADATA.json    # Server identity
├── INSTRUCTIONS.md         # Optional instructions
├── resources/              # Cached resources
└── tools/                  # Tool definitions
    └── <tool-name>.json    # Tool schema
```

**SERVER_METADATA.json:**
```json
{
  "serverIdentifier": "server-id",
  "serverName": "Server Display Name"
}
```

**Tool Definition (`tools/<name>.json`):**
```json
{
  "name": "tool_name",
  "description": "Tool description",
  "arguments": {
    "type": "object",
    "properties": { ... },
    "required": ["param1"]
  },
  "outputSchema": {
    "type": "object",
    "additionalProperties": true
  }
}
```

### 2.4 IDE State

**Path:** `~/.cursor/ide_state.json`

```json
{
  "recentlyViewedFiles": [
    {
      "relativePath": "path/in/project",
      "absolutePath": "/full/path/to/file"
    }
  ]
}
```

### 2.5 Global MCP Configuration

**Path:** `~/.cursor/mcp.json`

```json
{
  "mcpServers": {
    "server-name": {
      "command": "uvx",
      "args": ["package-name"]
    }
  }
}
```

### 2.6 Skills

**Path:** `~/.cursor/skills-cursor/<skill-name>/SKILL.md`

Stores custom skills/instructions for the agent.

---

## 3. Per-Project Files

### 3.1 Plans (Plan Mode)

**Path:** `<workspace>/.cursor/plans/*.md`

Markdown files created by Plan Mode.

### 3.2 Scratchpad

**Path:** `<workspace>/.cursor/scratchpad.md`

Used by long-running agents for iterative state.

### 3.3 Rules

**Path:** 
- `<workspace>/.cursorrules` - Legacy
- `<workspace>/.cursor/rules/*.mdc` - New format

Custom rules/instructions for the project.

---

## 4. Supporting Files

### 4.1 User Settings

**Path:** `~/Library/Application Support/Cursor/User/settings.json`

Standard VS Code settings format.

### 4.2 Profile Associations

**Path:** `~/Library/Application Support/Cursor/User/globalStorage/storage.json`

```json
{
  "profileAssociations": {
    "workspaces": {
      "file:///path/to/workspace": "__default__profile__"
    }
  }
}
```

---

## 5. Observability Schema Summary

### Core Tables for Extraction

| Table/Source | Purpose | Key Fields |
|--------------|---------|------------|
| `globalStorage/state.vscdb:ItemTable` | Global state, usage stats, memories | `aiCodeTracking.*`, `cursor/*` |
| `workspaceStorage/*/state.vscdb:ItemTable` | Per-workspace composers, prompts | `composer.composerData`, `aiService.*` |
| `ai-tracking/ai-code-tracking.db:ai_code_hashes` | Code attribution | `hash`, `source`, `composerId` |
| `ai-tracking/ai-code-tracking.db:conversation_summaries` | Chat summaries | `conversationId`, `title`, `tldr` |
| `projects/*/agent-transcripts/*.txt` | Full agent transcripts | Plain text |
| `projects/*/terminals/*.txt` | Terminal sessions | Plain text |
| `projects/*/mcps/*/tools/*.json` | MCP tool definitions | Tool schemas |

### Relationships

```
composerId (in composer.composerData)
    ↓
conversationId (in ai_code_hashes, conversation_summaries)
    ↓
agent-transcripts/<composerId>.txt
    ↓
Code changes tracked via hash in ai_code_hashes
```

### Key Identifiers

- **composerId**: UUID for a chat/agent session
- **bubbleId**: UUID for individual messages (in cursorDiskKV)
- **requestId**: UUID for specific LLM requests
- **workspace hash**: MD5-like hash mapping to workspace folder

---

## 6. Research vs Reality Comparison

| Research Claim | Actual Finding |
|----------------|----------------|
| Chat data in `cursorDiskKV` with `composerData:<id>` keys | ❌ `cursorDiskKV` exists but empty in tested DBs; data in `ItemTable` under `composer.composerData` |
| Bubbles stored as `bubbleId:<composerId>:<bubbleId>` | ❌ Not found; transcripts now in plain text files |
| Plan files in `.cursor/plans/` | ✅ Confirmed |
| Workspace DB has `state.vscdb` | ✅ Confirmed |
| NEW: Agent transcripts as `.txt` files | Not in research - new discovery |
| NEW: MCP tool definitions cached per-project | Not in research - new discovery |
| NEW: `ai-code-tracking.db` for attribution | Not in research - new discovery |
| NEW: Terminal sessions saved | Not in research - new discovery |

---

## 7. Extraction Priority

### P0 - High Value

1. `composer.composerData` - Chat/agent session metadata
2. `agent-transcripts/*.txt` - Full conversation content
3. `ai_code_hashes` - Code attribution tracking
4. `aiCodeTracking.dailyStats.*` - Usage metrics

### P1 - Medium Value

1. `cursor/pendingMemories` - Learned preferences
2. `conversation_summaries` - Quick overview
3. MCP tool invocations (if cached)
4. Terminal sessions

### P2 - Low Value / Settings

1. `cursorai/serverConfig` - Feature flags
2. User settings
3. Profile associations
