Cursor IDE¶
The Cursor desktop application, modelled as its own backend
(cursor-ide) separate from the terminal CLI. It
stores chat history in VS Code-style state.vscdb SQLite databases
under the platform user-data directory.
Cursor IDE has no dedicated fast prompt-history backend. Pass --exhaustive
to project prompt records from these databases. Targeted effort cannot route
this backend.
Stores¶
- Role:
primary_chat- Format:
sqlite- Coverage:
default_search- Adapter:
cursor_ide.state_vscdb_modern.v1,cursor_ide.state_vscdb_legacy.v1
- Role:
primary_chat- Format:
sqlite- Coverage:
default_search- Adapter:
cursor_ide.state_vscdb_modern.v1
- Role:
app_state- Format:
sqlite- Coverage:
catalog_only- Adapter:
-
- Role:
cache- Format:
sqlite- Coverage:
catalog_only- Adapter:
-
cursor-ide.state_vscdb¶
Cursor IDE chat storage; known prompt/chat keys in ItemTable/cursorDiskKV hold conversation JSON. agentgrep does not scan arbitrary state values. Cursor does not publish a formal schema — agentgrep’s parser is the reference implementation. On WSL the store is discovered under the Windows-host mount too (see ADR 0009).
- Agent:
Cursor IDE
- Role:
primary_chat- Format:
sqlite- Coverage:
default_search- Path:
${HOME}/.config/Cursor/User/globalStorage/state.vscdb- Adapter:
cursor_ide.state_vscdb_modern.v1, cursor_ide.state_vscdb_legacy.v1- Data version:
-- Version strategies:
-- Observed:
Cursor IDE 3.15.6 (2026-08-08)
- Default search:
yes
SQLite tables observed (2026-08-08)
- ItemTable columns:
key,value- composerHeaders columns:
composerId,workspaceId,createdAt,lastUpdatedAt,isArchived,isSubagent,recency,checkpointAt,value- cursorDiskKV columns:
key,value
Cursor IDE store, parsed by the current cursor_ide.state_vscdb_modern.v1 adapter. Not the same as the Cursor CLI agent transcripts.
cursor-ide.workspace_state¶
Per-workspace state.vscdb, one per opened project under workspaceStorage/<hash>/. Same ItemTable shape as the global store; the aiService.prompts key holds that workspace’s prompt history. The directory hash contributes origin.cwd_hash; sibling workspace.json can contribute origin.cwd. Reuses the cursor_ide.state_vscdb_modern.v1 adapter.
- Agent:
Cursor IDE
- Role:
primary_chat- Format:
sqlite- Coverage:
default_search- Path:
${HOME}/.config/Cursor/User/workspaceStorage/<hash>/state.vscdb- Adapter:
cursor_ide.state_vscdb_modern.v1- Data version:
-- Version strategies:
-- Observed:
Cursor IDE 3.15.6 (2026-08-08)
- Default search:
yes
SQLite tables observed (2026-08-08)
- ItemTable columns:
key,value- composerHeaders columns:
composerId,workspaceId,createdAt,lastUpdatedAt,isArchived,isSubagent,recency,checkpointAt,value- cursorDiskKV columns:
key,value
Per-workspace IDE history, complementing the global cursor-ide.state_vscdb. Parsed by the shared cursor_ide.state_vscdb_modern.v1 adapter.
cursor-ide.composer_headers¶
A third table in the same state.vscdb as ItemTable and cursorDiskKV, holding one row per session: composerHeaders(composerId, workspaceId, createdAt, lastUpdatedAt, isArchived, isSubagent, recency, checkpointAt, value). The value JSON carries session identity and origin — name, isWorktree, trackedGitRepos, agentLocation, workspaceIdentifier, referencedPlans. Notably it lists sessions that have neither a composerData: nor a bubbleId: row, which no other store can see at all; the readers gate to ItemTable and cursorDiskKV, so nothing opens this table today.
- Agent:
Cursor IDE
- Role:
app_state- Format:
sqlite- Coverage:
catalog_only- Path:
${HOME}/.config/Cursor/User/globalStorage/state.vscdb- Adapter:
-
- Data version:
-- Version strategies:
shape_inference- Observed:
Cursor IDE 3.15.6 (2026-08-08)
- Default search:
no
cursor-ide.conversation_search¶
Cursor’s own FTS5 index over conversation bodies, beside state.vscdb. conversations(fts_rowid, source, scope, id, title, updated_at, is_archived, root_fingerprint, cache_fingerprint) with source constrained to local or cloud-cache, plus a virtual conversation_fts(title, body) using unicode61. Derived data — the bodies also live in cursorDiskKV — so it is catalogued as a cache rather than a transcript, and searching it would duplicate hits.
- Agent:
Cursor IDE
- Role:
cache- Format:
sqlite- Coverage:
catalog_only- Path:
${HOME}/.config/Cursor/User/globalStorage/conversation-search.db- Adapter:
-
- Data version:
-- Version strategies:
shape_inference- Observed:
Cursor IDE 3.15.6 (2026-08-08)
- Default search:
no
Record schemas¶
Global state database¶
cursor-ide.state_vscdb is the platform-specific global SQLite
database (state.vscdb). agentgrep reads known prompt and chat keys in
ItemTable/cursorDiskKV; it does not scan arbitrary state values.
Global records may not carry project origin because the database is
shared across workspaces.
Platform |
Path |
|---|---|
Linux |
|
macOS |
|
Windows |
|
Workspace state databases¶
cursor-ide.workspace_state covers one state.vscdb per opened
project under workspaceStorage/<hash>/. These share the global store’s
ItemTable shape; the aiService.prompts key holds that workspace’s typed
prompt history. agentgrep enumerates them through the platform
workspaceStorage directory and parses them with the same adapter as the
global store.
Project context¶
Store |
|
|
|
|---|---|---|---|
|
|
|
|
same composer keys |
sibling |
|
Cursor keeps the interesting metadata in cursorDiskKV, not in the
prompt keys: composerData:<uuid> is the session document, carrying the
model it ran under and a gitWorktree block with the worktree path and
branch name, and bubbleId:<uuid>:<uuid> is one turn of that session,
naming its own model. Both are read, and both are
lossless — Cursor writes the path, so --cwd,
cwd:, and branch: answer with the real values. A turn that ran in its
own worktree keeps its own origin rather than inheriting the session’s.
Per-workspace stores also contribute origin.cwd_hash from the
workspaceStorage/<hash> directory, and agentgrep resolves the sibling
workspace.json folder URI to origin.cwd. That pair lets --cwd,
cwd:, MCP cwd, and cwd_hash: target one Cursor workspace without
opening unrelated workspace databases. The workspace cwd is a fact
about the database, not a promise about every record in it, so a
composer bubble that names a different worktree still wins for its own
record.
Global state.vscdb records stay conservative when no composer origin is
known. They remain searchable by text, agent, scope, and other non-origin
fields, but they do not satisfy a hard current-project filter unless the
stored record itself carries project metadata.
Note
Cursor publishes no schema for the composerData and bubbleId keys.
Every read is guarded, so a schema change degrades to an absent field
rather than a wrong one.
Cross-host discovery on WSL¶
Cursor is a VS Code fork, so when its UI runs on a Windows host and edits
a project inside WSL, the IDE chat is written client-side on Windows under
/mnt/c/Users/<user>/AppData/Roaming/Cursor/User, not inside the distro.
On WSL, agentgrep detects this and also probes the Windows users mount so
both the global and per-workspace state.vscdb databases are searchable
from Linux. AGENTGREP_WSL_USERS_ROOT overrides the mount root (default
/mnt/c/Users) for non-default drive letters. See
ADR 0009: Cross-host discovery and remote-workspace path mapping for the design.