Skip to content

Search

Steps for

Search finds a conversation when you remember something about it: a phrase, the project, a command that ran, a file that changed, or a commit it made. For questions that need several searches and a written answer, use Deep Recall instead.

App
Sessions → Search conversations
CLI
hansard history
In your agent
/recall
Searching for cache key lists five matching conversations and highlights the match in the open oneSearching for cache key lists five matching conversations and highlights the match in the open one
  1. Open Sessions in the dock.
  2. Select Search conversations (the search icon beside the conversation count), or press /.
  3. Type a distinctive phrase from the request, the response, or the tool output. The sidebar changes to Search results, with matching Projects & folders first and matching Conversations below them.
  4. Each result shows an excerpt with the matched words highlighted. Select a result to open the conversation at the matching message, with find in transcript started on the match. The first matching conversation opens automatically, and the arrow keys move through the results.
  5. With the conversation open, press n for the next matching message and Shift+N for the previous one.
  6. To return to the full list, select Close search.

Search terms do not need to match a title. Two to six distinctive words, such as a feature name, an error string, or a file name, work better than a full sentence.

Type To find
cache Words that start with it. Words shorter than three characters match whole words only.
"rate limiter" The words together, in this order.
sqlite-vec, search.js Words joined by -, ., _, /, :, or @, matched as a phrase.
-staging, -"dry run" Passages without that word or phrase.

Case and accents are ignored, so café matches cafe. Chinese, Japanese, Korean, and Thai terms match text that starts with them after a space or punctuation. The same syntax works in hansard history and in agent recall.

You can change the search shortcuts in Settings → Shortcuts.

Filter & sort (the sliders icon beside the search icon) narrows the conversation list. Filters apply with or without search text.

Filter & sort, with Source, Model, Device, Time, Include, Folder, File, and Commit filtersFilter & sort, with Source, Model, Device, Time, Include, Folder, File, and Commit filters
Filter What it limits
Source The harness a conversation came from, such as Codex CLI, Claude Code CLI, or ChatGPT Work Local. Each option counts the conversations it keeps.
Model The model recorded for the conversation.
Device The device that ran the conversation: this computer or a device that synced to it. Imported web conversations belong to an account rather than a device, so a device filter hides them.
Person Who ran the conversation. Appears only when the archive holds conversations from more than one person.
Time All time, Last 7 days, Last 30 days, Last 90 days, or Last 180 days.
Include Agents (interactive coding agents), SDK (programmatic Codex and Claude SDK sessions), and Web (imported ChatGPT, Claude.ai, and Gemini conversations).
Folder Part of a folder path or project name.
File Conversations that edited a file whose path contains this text.
Commit Conversations that recorded a commit starting with this SHA. Enter at least 7 hexadecimal characters.

Select Reset at the top of the filter panel to clear every filter. Do this before you conclude that a conversation was never imported.

To hide imported web chats by default, open Settings → General and turn off Show web chats in Conversations. The setting changes what the list shows, not what Hansard archives.

Archive search finds conversations. To find text inside the conversation you have open, select Find in transcript (the search icon in the conversation header) or press Cmd+F on macOS or Ctrl+F elsewhere. Press Enter for the next match and Shift+Enter for the previous one.

Find searches only the messages the View menu currently shows. Choose View → Everything to include every kind of message. When find cannot reach part of the transcript yet, such as earlier messages that are not loaded or tool cards that are still closed, an info icon appears after the match count. Point to it to see what the search leaves out.

List the 20 most recent conversations:

Terminal window
hansard history

Search by text. Text searches return 10 results unless you set --limit:

Terminal window
hansard history "authentication migration" --since 90d --limit 20

Combine text with filters, or use filters alone:

Terminal window
hansard history --repo github.com/example/app --provider codex-cli
hansard history "cache invalidation" --tool apply_patch
hansard history --command "git commit" --since 30d
hansard history "flaky test" --folder ~/code/app
hansard history "grant proposal draft" --role user --since 2026-09-14 --until 2026-09-14 --hits-per-session 3
Option What it matches
--repo <repo-or-path> A repository such as github.com/example/app, a working directory, or a displayed path. Path fragments work.
--project <project> One configured project: a merge, path-rule, or portfolio ID, or a route key such as merge:<id> or rule:<id>. See Projects and coordinators.
--folder <path> Conversations whose working directory is at or under a path. ~ expands.
--provider <source> A harness or source ID, such as codex-cli, claude, cursor, or chatgpt-work-local. Separate several with commas. See Supported harnesses.
--tool <name> Conversations that called a tool, such as apply_patch or Bash.
--command <head> Conversations that ran a shell command, matched on its first words, such as git commit.
--file <path> Conversations that edited a file.
--commit <sha> Conversations whose shell output confirmed a git commit.
--since <window> Conversations started since a window such as 7d, 30d, or 90d, or since a date. A date such as 2026-09-14 starts at midnight on your computer’s clock.
--until <date> Conversations started by a date or window, in the same forms as --since. A date includes that whole day on your computer’s clock, so a conversation from 11 PM counts for that day.
--role <role> Search results only in messages with that role: user for what you wrote, or assistant, system, tool, or metadata (titles). Separate several with commas.
--hits-per-session <count> Up to 5 matching messages for each conversation, the best as the result and the rest listed under it.
--group-revisions Marks a match in a message you pasted again with edits, such as a revised draft, and names its earlier and latest versions. Versions of one message count as one match.
--mode <mode> hybrid merges keyword matches with matches by meaning, the default once search by meaning is on. keyword matches the words as written. meaning finds conversations about the same thing in other words.
--limit <count> The number of results.
--include-subagents Also include subagent runs, which the default list hides.
--no-web-chats Exclude imported web chats.
--json Print results as JSON for scripts and agents.
--markdown-fallback A recovery search for old archives that predate the current index. Normal searches do not need it.

Each JSON result includes the session_id, the harness, the repository and working directory, the start time in UTC and on your computer’s clock (started_at_local), the matched text with an excerpt, a score, and whether the conversation was received from another device. With --hits-per-session, the further matches are in more_hits; with --group-revisions, revisions lists earlier versions of the matched message and latest_revision names a later one.

Within a conversation, Hansard prefers the message that contains every search word, even when a long message holds them in different paragraphs, over a shorter one that contains fewer.

Turn on Search by meaning in Settings → Imports → Search, or run hansard embeddings enable. Hansard downloads the EmbeddingGemma 2 model and a llama.cpp runtime, about 330 MB, and embeds your conversations and memories on this computer. Nothing is sent off it. Settings shows the download, then how many conversations are embedded. After that, the sidebar search, hansard history, hansard memory search, and agent recall rank results by meaning as well as by keyword. A half-remembered description finds the conversation even when it shares no words with it:

Terminal window
hansard history "why do my accounts keep getting signed out"
hansard history "why do my accounts keep getting signed out" --mode meaning

A search that names an identifier, such as a commit, a file path, a snake_case name, or a quoted phrase, ranks keyword matches first. Every filter applies to both kinds of match. The page title names the mode that ran, and each JSON result lists matched_by (keyword, meaning, or both) and, for a match by meaning, its similarity. If the model does not answer within a second or two, for example while it starts, the search shows keyword matches and prints a note.

The model stays loaded until the watcher stops the server after five idle minutes. The next uncached query then waits for the server to start. Stored vectors stay available, and this needs no reimport.

In the sidebar, a result that only the meaning ranking found shows Matched by meaning under its excerpt. Opening it does not start find in transcript, because the conversation need not contain your words.

To find screenshots by what they show, also turn on Screenshot search, or run hansard embeddings enable --images. It downloads the model’s vision file and keeps only its image encoder: with the text model and the runtime, about 880 MB of downloads and about 540 MB kept on disk. It then embeds the PNG, JPEG, GIF, and BMP images attached to conversations. WebP images are skipped. A match by screenshot names the message that holds the image:

Terminal window
hansard embeddings search "stats page with the clipped chart"
hansard embeddings search "stats page with the clipped chart" --images

With --images, hansard embeddings search matches only screenshots.

Each conversation keeps at most 24 images, with person-attached images first. Images must be no larger than 20 MB. An image attached to several conversations is embedded once.

Once search by meaning is ready, Related conversations in a conversation’s Actions menu lists the eight conversations closest in meaning to it, read from the stored vectors. hansard embeddings similar <session-id> prints the same list, and --images lists conversations whose screenshots look like this one’s. Graph also links conversations of similar subject and similar screenshots.

hansard embeddings status shows the model, disk use, and how many conversations are embedded. hansard embeddings disable turns search by meaning off and keeps the downloads; add --remove to delete the model and the stored vectors, as Remove… does in Settings. Run hansard help embeddings for every subcommand.

Setup selects Search by meaning when disk space permits and queues installation after import. Saved choices remain. Turn the setup switch off to skip the download. Downloads use pinned SHA-256 checks. The model runs through Metal on Apple silicon and the CPU elsewhere.

Automatic passes embed new or changed conversations, newest first, for at most a minute. Each conversation keeps at most 40 passages. Memory search embeds current snapshots as passages of whole lines and excludes skill folders.

Pause under Settings → Imports → Search pauses automatic embedding, graph builds, labeling, summaries, archive refresh, and outcome labels. These passes run at background priority and pause on battery power or thermal pressure. Interactive searches remain available. Turning Search by meaning off cancels its active pass and queued setup work. See Background work.

Embeddings also group conversations into subjects without a model request. hansard embeddings subjects lists them, and Stats → Projects → Subjects shows their conversations, session time, and tokens. The section stays hidden while embeddings are off. Classification explains optional labels derived from neighboring conversations.

To find every conversation that edited a file, pass a file name, a trailing path fragment, or a full path. The match is case-insensitive:

Terminal window
hansard history --file src/server/auth.ts

To find the conversation that made a commit, pass 7 to 40 characters of its SHA:

Terminal window
hansard history --commit 1a2b3c4

Both filters read what Hansard recorded at import time. The commit filter uses the confirmation line that git commit printed in the archived shell output. Hansard never inspects your repository, so a listed commit may since have been amended or reverted.

hansard why names the archived agent edit that last wrote one line of a file:

Terminal window
hansard why src/server/auth.ts:120
hansard why src/server/auth.ts:120 --all --json

Hansard matches the line’s current text, and its neighbors when the line is short or repeated, against the lines that recorded file edits added. Edits made in another checkout or worktree of the same repository count. The result names the session, the edit’s time and tool, your prompt before the edit, and the agent’s last words before it. In a Git checkout it also shows the commit that last changed the line and any archived session that recorded that commit; --no-git skips that lookup.

--all lists every archived edit that wrote the text instead of the latest three, and --limit N sets how many of the most recent sessions that edited the file are searched (200 by default). Edits made through shell scripts, other tools, or by hand are not recorded as file edits, so their lines report no archived author.

Read a file’s history and a task’s context

Section titled “Read a file’s history and a task’s context”

Without a line number, hansard why prints the history of the whole file. hansard work-context prints the task a conversation belongs to:

Terminal window
hansard why src/server/auth.ts
hansard why src/server/auth.ts --symbol refreshToken
hansard work-context <session-id>

File history lists the project memories that name the file, then the conversations that edited it, newest first, with the commits they made, reverts, test failures and later fixes, live sessions that edited it, and the files that import it. --symbol narrows the history to one function, class, or method. Work context lists the task’s conversations in order, the steps their task lists recorded as open, done, or dropped, failing and fixed tests, commits, and the most closely linked conversations. Every entry names a conversation and message index, a commit, or a line of a memory, so you can open the evidence with hansard show or hansard memory show. --until hides everything after a date, except with --symbol or a line number, and --json prints the entries as data. Agents read the same answers through the code_history and work_context recall tools. The watcher keeps the index behind these answers current after imports, without model requests, and hansard experience status reports its state.

Print a whole conversation as readable text:

Terminal window
hansard show <session-id>

A long conversation can exceed what an agent or terminal will display. Read the latest 20 messages first:

Terminal window
hansard show <session-id> --json --msg-limit 20

Read the opening messages, where the original goal usually is:

Terminal window
hansard show <session-id> --json --msg-offset 0 --msg-limit 8

Without --msg-offset, a windowed request returns the latest messages. Windowed output leaves out the full Markdown and event copies and shortens very large tool output, but it keeps every tool call’s arguments. For more ways to read a conversation, see Browse conversations.

Search looks at user prompts, assistant responses, subagent results, tool calls, and the first 600 characters of each tool result. Thinking and context cards are not searched. Conversations synced from your other devices are included and marked as received.

A search that finds nothing means no match exists in the indexed text. It does not prove that something never happened: the harness may not have been imported, the conversation may predate your import window, or the wording may differ.

Can I search every coding agent’s history at once?

Section titled “Can I search every coding agent’s history at once?”

Yes. One search covers every harness, project, and year in the archive, including conversations synced from your other devices. To limit it to one harness, add --provider, as in hansard history "retry budget" --provider claude.

Which agent conversation wrote this line of code?

Section titled “Which agent conversation wrote this line of code?”

Run hansard why <file>:<line>. It names the archived agent edit that last wrote the line, with the session, the time, the tool, and your prompt before the edit. See Find the conversation that wrote a line.

Can my coding agent search my past conversations itself?

Section titled “Can my coding agent search my past conversations itself?”

Yes. Install recall with hansard integrations add-to <agent>, then type /recall and a topic in Claude Code, or ask the agent in plain language. See Recall in your agents.

Does search cover thinking and tool output?

Section titled “Does search cover thinking and tool output?”

Search covers prompts, responses, subagent results, tool calls, and the first 600 characters of each tool result. Thinking and context cards are not searched.

A conversation you expect is missing. Select Reset in the filter panel and check that Include has the right types turned on. Run hansard index status to see whether indexing is paused. If the conversation still does not appear, check that its harness is imported in Supported harnesses.

Too many results. Add --repo, --provider, or --since, or use more specific words.

--file or --commit returns nothing for older conversations. Older archives may not record edited files and commits yet. Run hansard rebuild --since all to add them without reimporting.

A result shows a path such as path:3f9a… instead of a folder. Folders outside a Git repository use a stable storage key. The JSON result’s repo_display and cwd fields show the readable path.