How Hansard works

Hansard reads the history your coding agents already save, copies it into an archive on your computer, and builds a search index over it. The app, the CLI, and your agents all read from that one archive.

Your history

Local harnessesRead as sessions are written

Cloud agentsImported when you run the command

Account exportsImported from a downloaded file

Watcher and import

Archive on this machine

ConversationsOne format for every harness

Original filesExact copies, kept after the harness deletes them

Search indexRebuilt from the conversations

MemoriesAgent memory files with revision history

Read by

Where you use it

The appMac app, or hansard web in a browser

The CLIhansard history, stats, and more

Your agentsRecall, continue, and memory search

From your agents to the archive

1. Sources. Each harness saves conversations in its own files or database, such as ~/.claude/projects for Claude Code or ~/.codex/sessions for Codex. Hansard reads them in place and never changes them. It also reads exports you download, such as a ChatGPT export, and cloud agents you choose to import from.
2. Archive. For each conversation, Hansard writes a transcript, a readable Markdown copy, a list of events such as tool calls and file edits, and details such as the project, models, and token counts. It stores attachments next to the conversation and keeps an exact copy of every original file it read. The archive is in ~/.hansard/data unless you chose another location.
3. Search index. Hansard indexes the archive so that searches, filters, and stats stay fast.
4. App, CLI, and agents. The app, commands such as hansard history, and the recall tools in your agents all read the same archive and index.

When redaction is on, Hansard hides common secrets in the transcript and the search index. The original copies keep their exact content, so protect the archive like the history it came from. See Redaction.

For the folders and files inside the archive, see Archive layout.

What the watcher does

The watcher is a background process that keeps the archive current. The Mac app starts it at login when Start at login is on in Settings → Imports. With the CLI, start it with hansard watcher start or turn on login startup during hansard init.

While it runs, the watcher:

• imports new and changed conversations shortly after a harness writes them;
• scans each source over a rolling window, 30 days by default, without removing older conversations from the archive;
• refreshes the search index;
• backs up agent memory files every 15 minutes;
• captures plan usage every 15 minutes when usage tracking is on;
• reinstalls the recall commands and MCP entries in your agents if they disappear, and refreshes them after an update;
• runs scheduled sync when you have set it up;
• warns when a harness’s original files start to disappear.

Without the watcher, the archive changes only when you run hansard import. See Background archiving to choose sources and manage the watcher.

Why the archive keeps original files

Harnesses delete old history. Some remove conversations after a retention period, and reinstalling a harness can empty its folder. Because Hansard keeps its own copy of every original file, with a checksum, your history outlives the harness’s copy. hansard doctor reports how long each harness keeps its own history.

The copies also let Hansard read your history again when its importers improve:

• hansard import re-reads sources that still exist.
• hansard rebuild --from-raw rebuilds conversations from the preserved copies, for sources that support it.
• hansard restore-sources copies preserved files back to their original location without overwriting existing files, so hansard import can read them again.

Deleting a conversation in a harness does not delete Hansard’s copy, and hansard delete removes Hansard’s copy without touching the harness. If a harness transcript file shrinks to less than half of what Hansard archived, Hansard keeps the archived version and reports the change in hansard status and hansard doctor.

What changes when you turn on sync

By default, nothing leaves your computer. Each sharing feature is off until you set it up, and each one sends something different.

Feature	What leaves your computer	Where it goes
Personal Sync	Your whole archive, including original files and memories	A storage bucket or shared folder you choose
Teams	Whole conversations from the repositories you select, without original files or memories	Your team’s shared bucket
Slack	Conversation summaries, digests, and optionally conversation turns	A Slack channel you choose
Hosted viewer	Everything the app shows, to anyone with the password	Other machines on your network

With Personal Sync, conversations from your other computers appear in the app next to your local ones, and you can continue them on this computer. Features that call a model, such as Deep Recall and work classification, also send conversation text to the model provider you choose. See What leaves your machine for every case.

Refresh the archive

Most of the time the watcher keeps the archive current. After an update, it also does the work of hansard rebuild --since all in the background, and hansard status shows its progress as Archive refresh. See Refresh after updates. When release notes or hansard doctor ask for a refresh, use the command they name.

Layer	hansard import	rebuild --from-raw	hansard rebuild	index rebuild
Harness fileseach harness's own folders
Original copiessession.raw/
Transcripttranscript.jsonl, metadata.json
Events and viewsevents.jsonl, view.json, conversation.md
Search indexused by search and recall

ReadsRewrites

Each command reads one layer and rewrites the layers built from it. None of them changes your harness files. After a large import or a raw rebuild, run hansard index rebuild to refresh search.

Command	What it does	When to use it
hansard import	Reads harness sources again and adds or updates conversations.	To import older history, or after an importer improves.
hansard rebuild	Refreshes titles, tool statistics, and the app’s copy of each conversation from files already in the archive. It does not read harness folders.	After an update that changes how conversations are displayed.
hansard index rebuild	Rebuilds the search index.	When search misses conversations that are in the archive.
hansard update	Clears the rebuildable parts of the archive and imports your configured sources again. It keeps your settings, memories, Deep Recall research, imported exports, and conversations whose original files are gone.	When a release requires a full reimport. Preview it first with hansard update --dry-run.