Originally published on Extracurricular AI.
You remember fixing the authentication bug. You cannot remember which project contained the conversation.
cursor-history searches conversation text in supported local Cursor stores across discovered workspaces. It can read history created before you installed it, without a capture hook, embeddings, or an API key.
Start with a phrase you remember
npm install -g cursor-history
cursor-history list --all
cursor-history search "connection pool"
Run this on the machine where the history is stored, using Node.js 20.x or 22.x–26.x. The CLI searches parsed message content using case-insensitive text matching. It does not semantically infer that “database saturation” means “connection pool.”
Try a distinctive substring if a broad query returns too much:
cursor-history search "ECONNRESET" -n 30
cursor-history search "oauth callback"
cursor-history search "refreshToken"
Search returns up to 10 matching sessions by default. -n 30 raises the limit; -n 0 returns all matching sessions. list --all removes the listing limit; it is not a switch that enables global search. Search covers discovered workspaces by default unless you select a workspace.
Open the session that actually matched
For interactive use, copy the session index displayed in the result. If it is 12:
cursor-history show 12
cursor-history export 12
The number refers to the underlying session list within the same data roots and workspace scope. It is not the search result's ordinal position. New sessions can also change list indices, so use exact UUIDs for saved commands.
With jq installed, retrieve those UUIDs directly:
cursor-history search "authentication" --json | jq -r '.results[].sessionId'
Copy a returned ID into these commands, replacing the placeholder:
session_id='PASTE_RETURNED_SESSION_UUID'
cursor-history show "$session_id"
cursor-history export "$session_id" --format json --output ./conversation.json
The JSON export contains the available session representation. It may include source details and inferred timestamps; it is not proof of a complete original conversation.
Narrow the workspace when you know it
Keep the same scope on the follow-up read:
cursor-history --workspace /absolute/path/to/project search "authentication"
cursor-history --workspace /absolute/path/to/project show 1
Here 1 means session 1 in that workspace's list. Do not reuse a global index in a workspace-scoped read. A workspace filter also limits which conversation sources may be opened; it is more than a display filter.
If you get no useful matches
| Check | Why it matters |
|---|---|
| Try a shorter phrase or exact error token | Text search does not paraphrase the query |
Run cursor-history list --all --json
|
Inspect discovered sessions and any diagnostics |
| Check which machine and user account owns the files | Local search does not fetch SSH, cloud, or another user's history |
| Check custom roots or WSL paths | Composer data and ~/.cursor can live in different environments |
| Review source status | Missing, partial, or ambiguous sources can affect what is searchable |
For an explicit environment, set both roots to the intended directories:
CURSOR_DATA_PATH='/absolute/path/to/Cursor/User/workspaceStorage' CURSOR_STORE_ROOT='/absolute/path/to/.cursor' cursor-history search "authentication"
The platform guide explains these selectors. An empty result means no match was returned from the readable selected sources; it does not prove that a chat was deleted.
When to use Cursor's own commands
To continue an Agent CLI conversation, start with Cursor's native session commands. This workflow is useful when you need to locate text across local conversations and then inspect or export the result.
The MCP companion can let an assistant perform the search. As checked on September 8, 2026, MCP 0.3.1 uses reader 0.18.0. The packages release independently, so update the MCP package when upgrading the server.
If the search finds something useful, keep cursor-history on GitHub. For moved projects, continue with the recovery guide.
Implementation references: search traversal, text matcher, CLI JSON formatter.
Top comments (3)
The distinction between discovery and proof is important here. I would surface source coverage in every result—roots searched, unreadable stores, timestamp confidence, and whether content was truncated—so a user does not mistake a convenient local index for a complete record. That also makes cross-workspace search safer to automate.
Thanks, Alex. I read this as a broader point about making coverage and provenance visible throughout history discovery and inspection. We already expose some source and timestamp provenance in session details, but it isn’t consistently surfaced across list, search, and detail output.
I’ve clarified the current limitations in the README. We’ll open an issue to review these outputs together, covering searched roots, unreadable or skipped sources, timestamp provenance, and explicit truncation and result limits. Agreed that a convenient local view shouldn’t be mistaken for a complete record.
The 'history created before you installed it' property is the one that matters most, and today handed me a concrete case for it on the Claude Code side: a reader asked what two files in a measurement lab weighed, the lab directory was long gone, and the answer came from grepping the session transcripts for the script that had created them. Plain text matching was enough for that. The filter I keep wanting on top is by the files a session touched, since 'which session wrote handler.ts' comes up for me more often than any phrase I can remember.