Backends¶
agentgrep reads on-disk stores from multiple AI coding assistants. Each backend page documents the agent’s path layout, environment overrides, store descriptors, and record schemas.
Backend pages¶
OpenAI Codex CLI history, sessions, instructions, memory, goals, and SQLite state.
Claude Code history, project transcripts, tasks, memory, settings, and plugin surfaces.
cursor-agent transcripts, prompt history, chat blobs, and AI-tracking summaries.
Cursor desktop app state.vscdb SQLite — global and per-workspace chat history.
Gemini CLI chat sessions, prompt logs, checkpoints, settings, and skills.
Google Antigravity overview, split into CLI prompt recall and IDE-local stores.
Antigravity CLI prompt history, protobuf conversation databases, and local cache state.
Antigravity IDE protobuf transcripts, Markdown brain artifacts, skills, and settings.
Grok CLI prompt history, session transcripts, memory, logs, and config.
Pi (earendil-works) session transcripts, settings, prompts, and managed extensions.
OpenCode (anomalyco) SQLite session store, config, snapshots, and caches.
VS Code GitHub Copilot Chat JSON transcripts and inline-edit history, including WSL cross-host stores.
Unsupported backends¶
Some agents store their conversations in an obfuscated or encrypted form agentgrep cannot read. Their storage is catalogued for inventory, but they are excluded from search — see Unsupported backends (currently Windsurf).
Coverage levels¶
The backend pages distinguish search support from storage coverage.
Default-search stores are eligible for search without an inventory
opt-in; fast prompt effort narrows that tier to prompt-history roles.
Inspectable stores are known and can be inventoried explicitly.
Catalog-only stores are documented so future adapters do not mistake
them for prompt history; some catalog stores expose safe structural
samples for inspect_record_sample, but they still stay outside
search. Private stores are documented but intentionally not enumerated
from disk.
Search scope is record-level. --scope prompts is the default and
admits user-authored prompts. Fast effort reads dedicated prompt-history
logs only; --exhaustive also projects user turns from transcript backends.
Full conversation, assistant, tool, and event records require
--scope conversations or --scope all.
Targeted conversation routing¶
--deep starts from matching prompt evidence and opens only conversations
whose owning adapter can prove the prompt-to-transcript locator. Current
targeted routes cover Codex, Claude Code, Grok, and Antigravity CLI. The router
groups duplicate evidence before its conversation-attempt bound, applies
conversation-invariant agent and project filters before selection, and never
uses routing evidence as a result match.
Other backends require --exhaustive for conversation coverage. A targeted
miss is approximate, not a corpus-wide negative, and never triggers an
automatic exhaustive sweep.
Project context availability¶
Project context is best-effort and store-dependent. When a backend
records working directories, repository roots, branches, workspace
hashes, or sibling workspace metadata, agentgrep attaches that data as
RecordOrigin on search results. Those origins power
current-project search and the
origin fields in Origin fields.
Backends without project context still remain searchable; they simply do not match hard origin filters. Some SQLite-backed workspace stores, such as Cursor IDE and VS Code (GitHub Copilot Chat), expose enough source-level origin facts for agentgrep to skip mismatched workspace databases before parsing. Global stores that do not know their project stay conservative.
Each backend page carries a Project context section naming, per store,
which of model, cwd, and branch a record can carry and where the
value comes from — a SQLite column, a path segment, a sibling file, or a
nested key.
How agentgrep learns a working directory¶
Agents do not agree on how to write down where a session ran, so a cwd
reaches a record through one of three tiers. The tier decides what you
can filter on, and it is a property of the store, not of your query.
Lossless. The store wrote the path, or an encoding that inverts
exactly: a cwd column (codex.state_db,
pi.context_mode_db), a nested key
(cursor-ide.state_vscdb), a sibling file
(gemini.tmp.chats), or a %2F-escaped directory name
(grok.sessions). Records carry origin.cwd and answer
--cwd and cwd: with the real path.
Lossy. The store folded the path into a name that cannot be inverted
on its own. Cursor CLI’s projects/<name>/ segment replaced every
separator with - and escaped nothing, so foo-bar is equally
consistent with /foo/bar and /foo-bar. agentgrep reconstructs the
name against the filesystem and keeps the answer only when exactly one
reconstruction resolves to a directory that exists. Ambiguity, a
directory that has since moved, and a pathological name that exhausts the
probe budget all leave origin.cwd unset: a fabricated path does not
merely omit a result, it makes a repo-scoped filter silently skip your
own project, so a known-unknown is the safer answer.
Digest. The store only ever knew a hash of the path
(cursor-cli.chats). Records carry origin.cwd_hash
and nothing else, so they answer cwd_hash: and not cwd:. A digest
does not invert, so agentgrep never reverses one into a cwd — and it
never runs the hash the other way either: a cwd_hash is always read
from the name the store chose, never computed from a cwd recovered
somewhere else. A path segment is admitted as a cwd_hash only when it
has a digest’s shape, so a backup.db sitting beside a real database
does not publish its own file name as a searchable project identity.
The tiers stack. A store that hashes its directory name and repeats the
literal path inside — pi.context_mode_db,
gemini.tmp.chats — gives a record both cwd and
cwd_hash.
Only cwd_hash is a fact about where a source lives, so it is the only
origin field agentgrep trusts to skip a store before opening it. A cwd
learned from a sibling workspace.json or a project directory name
describes the source, not a promise about every record inside it — a
Cursor composer bubble can name its own worktree — so those stores are
still opened and filtered record by record.
Version detection¶
Source discovery reports version metadata separately from record content. agentgrep prefers concrete source evidence over app freshness: embedded metadata, file/record shape, and SQLite suffixes identify the data version; local version files provide app-version context only when they can be read without spawning an upstream CLI. If neither is available, the catalog observation stamp is reported as a low-confidence fallback.
Support matrix¶
- Default search:
- Opt-in parsers:
- Safe catalog samples:
- Memory:
-
- Plans / todos / goals:
- Instructions / plugins / skills:
-
- Indexes / summaries:
-
- App state / config:
- Runtime / cache / private:
- Default search:
-
- Opt-in parsers:
- Safe catalog samples:
- Memory:
-
- Plans / todos / goals:
- Instructions / plugins / skills:
- Indexes / summaries:
-
- App state / config:
- Runtime / cache / private:
- Default search:
- Opt-in parsers:
- Safe catalog samples:
- Memory:
- Plans / todos / goals:
- Instructions / plugins / skills:
- Indexes / summaries:
-
- App state / config:
- Runtime / cache / private:
- Default search:
- Opt-in parsers:
- Safe catalog samples:
- Memory:
- Plans / todos / goals:
- Instructions / plugins / skills:
- Indexes / summaries:
- App state / config:
- Runtime / cache / private:
- Default search:
- Opt-in parsers:
- Safe catalog samples:
- Memory:
-
- Plans / todos / goals:
- Instructions / plugins / skills:
- Indexes / summaries:
- App state / config:
- Runtime / cache / private:
- Default search:
- Opt-in parsers:
-
- Safe catalog samples:
-
- Memory:
-
- Plans / todos / goals:
-
- Instructions / plugins / skills:
-
- Indexes / summaries:
-
- App state / config:
- Runtime / cache / private:
-
- Default search:
- Opt-in parsers:
- Safe catalog samples:
- Memory:
- Plans / todos / goals:
-
- Instructions / plugins / skills:
- Indexes / summaries:
-
- App state / config:
- Runtime / cache / private:
- Default search:
- Opt-in parsers:
- Safe catalog samples:
- Memory:
- Plans / todos / goals:
- Instructions / plugins / skills:
- Indexes / summaries:
- App state / config:
- Runtime / cache / private:
- Default search:
- Opt-in parsers:
-
- Safe catalog samples:
- Memory:
-
- Plans / todos / goals:
-
- Instructions / plugins / skills:
-
- Indexes / summaries:
-
- App state / config:
- Runtime / cache / private:
- Default search:
- Opt-in parsers:
- Safe catalog samples:
- Memory:
-
- Plans / todos / goals:
-
- Instructions / plugins / skills:
- Indexes / summaries:
-
- App state / config:
- Runtime / cache / private:
- Default search:
- Opt-in parsers:
-
- Safe catalog samples:
- Memory:
-
- Plans / todos / goals:
-
- Instructions / plugins / skills:
-
- Indexes / summaries:
-
- App state / config:
- Runtime / cache / private:
- Default search:
-
- Opt-in parsers:
-
- Safe catalog samples:
- Memory:
- Plans / todos / goals:
- Instructions / plugins / skills:
- Indexes / summaries:
-
- App state / config:
- Runtime / cache / private:
-