# How Hansard works

> How Hansard turns agent history into one local archive, keeps it current, and makes it available to the app, the CLI, and your agents.

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.

## 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](https://www.hansard.dev/privacy/redaction/).

For the folders and files inside the archive, see
[Archive layout](https://www.hansard.dev/reference/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](https://www.hansard.dev/imports/watcher/) 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](https://www.hansard.dev/sync/personal-sync/) | Your whole archive, including original files and memories                                | A storage bucket or shared folder you choose |
| [Teams](https://www.hansard.dev/sync/teams/)                 | Whole conversations from the repositories you select, without original files or memories | Your team's shared bucket                    |
| [Slack](https://www.hansard.dev/sync/slack/)                 | Conversation summaries, digests, and optionally conversation turns                       | A Slack channel you choose                   |
| [Hosted viewer](https://www.hansard.dev/sync/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](https://www.hansard.dev/privacy/data-boundaries/) 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](https://www.hansard.dev/reference/background-work/#refresh-after-updates).
When [release notes](https://www.hansard.dev/releases/) or `hansard doctor` ask for a refresh,
use the command they name.

| 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`. |