# gptme

> Import gptme local conversation logs with recorded reply metadata and preserved branches.

Hansard reads gptme's local conversation store. The source shape has been
validated with the official gptme 0.34.0 CLI. The records themselves do not
declare a producer version or reliably identify the originating interface.
Web UI, desktop, and hosted service acceptance remain separate work.

## Source IDs

| Source  | Use it for                                                                |
| ------- | ------------------------------------------------------------------------- |
| `gptme` | Local `conversation.jsonl` histories, branches, views, and recovery logs. |

## How the import works

The main transcript supplies prompts, replies, reasoning, and native JSON tool
calls. Tool results keep their recorded call identifiers. Reply metadata
provides model, resolved model, reasoning effort, and token counts; current
config settings never fill missing historical reply values. Cache tokens are
separate from uncached input, and reasoning tokens remain part of output.
gptme's cost field is a price estimate, not evidence of a billed charge.

The working folder comes from the chat config. A local checkout can establish
its repository; no historical remote or commit is inferred. Session identity
uses the source directory path because gptme does not record a portable unique
conversation ID. Moving or copying a store to a different path creates a
separate identity.

Each capture validates stable source bytes and agreement with the recovery
log. Backup branches preserve edits and undo history. A shorter main branch
can replace the archive only when earlier retained messages remain in the
source bundle. Older recovery sequences and missing history are rejected.
Recovery checkpoints can compact events while retaining conversation history.

## Import and keep current

**Import now**

```sh
hansard import --source gptme --since all
hansard index rebuild
```

**Keep current**

Automatic source selection includes `gptme`. For a custom list:

```sh
hansard config sources enable gptme
hansard watcher restart
```

`HANSARD_GPTME_LOGS_DIR` takes precedence over `GPTME_LOGS_HOME`. Otherwise,
discovery follows `XDG_DATA_HOME/gptme/logs`, an existing
`~/.local/share/gptme/logs`, or the native platform directory: macOS
`~/Library/Application Support/gptme/logs`, Windows
`%LOCALAPPDATA%/gptme/gptme/logs`, and Linux `~/.local/share/gptme/logs`.

## Review the import in the app

1. When the import finishes, open **Conversations** and select **Filter & sort**.
2. Set **Source** to **gptme** and set **Time** to the window you imported. Use **Folder** to narrow the list when you use this harness in several projects.
3. Select a conversation to check its messages, tool calls, files, commits, model, and token usage.

To keep archiving new sessions from a local harness, open **Settings → Imports**. **Automatic** follows every supported harness installed on this computer. **Custom** lets you turn individual harnesses on or off. Cloud sources and account exports never run from here; each needs its own import command. If a conversation you expect is missing after you reset the filters, run the import command on this page again with `--explain-skips` where the source supports it.

Compare the main transcript and its tools with gptme. Check the capture
metadata for raw-only branches and views. A recorded wall-clock date with no
timezone remains explicitly marked; it must not be interpreted as UTC.

## What Hansard preserves

- Main-branch prompts, replies, recorded reasoning, JSON tool arguments, and results.
- Recorded model, resolved model, effort, usage, cost estimates, and timing metadata.
- Exact conversation, branch, view, and recovery-log bytes with SHA-256 hashes.
- A copy of selected chat settings, labeled as a filtered copy rather than
  an exact copy of `config.toml`.
- Original timestamp strings, file references, hashes, and unknown field counts.

## Known limitations

- Alternate branches and compacted views remain raw-only. Markdown and XML
  tool syntax stays in transcript text; it is not converted into tool calls.
- Attachment references remain visible in metadata, but referenced file bytes
  are not collected. External URLs are not fetched.
- Config environment variables, MCP configuration, system prompts, and
  unrecognized settings are deliberately excluded from the config copy.
  System messages recorded in the conversation remain transcript history.
- Naive timestamps retain their wall-clock range under a timezone-unknown
  status. Message clocks use ordering-only recovery or session fallbacks.
  Recovery append time is not an exact message creation time. Checkpoint
  compaction does not reset the session date to the checkpoint date.
- Native user-role `<system>` envelopes are treated as system reminders and
  retain their original role in metadata.
- Account, organization, remote history, historical Git identity, and subagent
  linkage are not established by this route. Do not infer them from model names
  or directory labels.
- The native CLI trial used a local synthetic model endpoint. Hosted model
  billing and other client surfaces remain unverified.
- Files larger than 128 MiB, bundles larger than 256 MiB, and bundles with more
  than 2,048 components or 200,000 top-level records are rejected. Unknown
  recovery event kinds, incomplete saves, and invalid counters require review.

## Refresh an existing archive

```sh
hansard import --source gptme --since all
hansard index rebuild
```

If the source has regressed, restore its full retained history before retrying.
Reimporting cannot reconstruct missing source records or excluded config data.