Archive layout

Hansard stores local state under ~/.hansard by default. The normalized archive defaults to ~/.hansard/data/hansard, but initialization can configure another storage root.

Find the active paths rather than assuming the defaults:

hansard status
hansard config path
hansard config get storage.root

Home and archive roots

~/.hansard/
├── config.json
├── redaction.yaml
├── state/
├── spool/
├── cache/
├── logs/
└── data/
    └── hansard/
        ├── sessions/
        ├── memory/
        ├── raw/
        ├── raw-sources/
        ├── indexes/
        └── received/

HANSARD_HOME can relocate the Hansard home for an isolated process. Storage configuration can independently place the archive on another local path.

Session partitions

Repository sessions are partitioned by canonical repository. Web conversations and other non-repository records use a canonical scope instead.

sessions/
└── repo=<encoded-repository>/
    └── provider=<provider>/
        └── year=YYYY/
            └── month=MM/
                └── day=DD/
                    ├── session=<session-id>.metadata.json
                    ├── session=<session-id>.transcript.jsonl
                    ├── session=<session-id>.events.jsonl
                    ├── session=<session-id>.conversation.md
                    ├── session=<session-id>.view.json
                    ├── session=<session-id>.view.pages/
                    ├── session=<session-id>.attachments/
                    ├── session=<session-id>.artifacts/
                    └── session=<session-id>.raw/

The .view.pages, attachments, artifacts, and raw directories are created only when needed. A scope partition has the same shape but begins with scope=<encoded-scope>.

The five session files

File	Role
*.metadata.json	Session identity, provider/source, project or scope, timestamps, counts, models, usage, normalized tool summaries, version fields, and sidecar paths.
*.transcript.jsonl	Normalized and redacted messages, one JSON object per line.
*.events.jsonl	Provider-independent canonical events derived from the transcript or supplied by the importer.
*.conversation.md	Human-readable Markdown rendering used by terminal and export surfaces.
*.view.json	Prebuilt viewer payload with display-time correction and deduplication. Large sessions can use *.view.pages/ as a compressed window cache.

Metadata and normalized transcript/events are the durable contract for listing, search, stats, and re-derivation. The viewer payload is derived and can be rebuilt from archived normalized data.

Sidecars and source preservation

Raw

*.raw/manifest.json records every original provider file the importer touched, including hashes, source paths, and timestamps. Small files can be copied into the session raw directory. Large multi-session stores are copied once under raw-sources/ and referenced by multiple manifests.

Attachments

*.attachments/ stores user and tool attachment bytes by content hash with an attachments.json manifest. Normalized messages keep compact descriptors instead of inline base64 data.

Artifacts

*.artifacts/ is an optional, bounded capture of referenced images and PDFs. Artifact capture is disabled by default and is distinct from provider raw preservation.

Web account exports are preserved once under raw/web-exports/ and referenced from their imported conversations, avoiding a complete export copy per session.

Raw data is not redacted

Redaction applies to normalized transcripts, events, Markdown, and viewer data. Raw sources preserve original bytes and remain sensitive. Protect raw backups and export --include-raw output like the provider history itself.

Memory archive

Memories are first-class archive objects alongside sessions:

memory/
└── repo=<encoded-repository>/
    └── provider=<provider>/
        └── source=<source>/
            └── item=<memory-id>/
                ├── item.json
                └── snapshots/
                    └── <timestamp>.<extension>

Global memories use scope=global instead of repo=.... item.json stores provenance, origin, content hash, current metadata, and snapshot history. A new full-copy snapshot is written only when the content hash changes.

Indexes and received archives

indexes/ contains derived session-list, keyword, FTS, and memory-search data. These files accelerate history, recall, viewer lists, and memory search; they can be recreated with:

hansard index rebuild

Remote receive operations mirror other device namespaces under received/devices/. Received session and memory records are treated as read-only local mirrors rather than provider source histories.

Versioned derivation

Session metadata records separate version boundaries:

• the archive schema describes the folder and metadata contract;
• the view schema gates *.view.json and *.view.pages/;
• canonical event schema identifies the normalized event shape; and
• per-source parser versions identify the importer logic used for a session.

Choose the refresh that matches the changed boundary:

Change	Refresh
Viewer contract or stale view payload	hansard rebuild
Search or list index state	hansard index rebuild
Provider parser semantics	hansard import --source <source> --since all
Complete local refresh after an upgrade	Preview hansard update --dry-run, then run hansard update.

Hansard creates private archive directories and normalized files with owner-only permissions by default. Files copied elsewhere inherit the security boundary of their new location.