# OpenHands

> Import OpenHands CLI, SDK, Agent Canvas, legacy application, and cloud conversation history.

Hansard imports local OpenHands conversations and explicitly requested cloud
history. OpenHands remains the harness identity; routed models retain their
own model-company identity in Stats.

## Source IDs

| Source            | Use it for                                                          |
| ----------------- | ------------------------------------------------------------------- |
| `openhands`       | Local SDK conversation folders and legacy application event stores. |
| `openhands-cloud` | Explicit cloud history import with an API key.                      |

## How the import works

The CLI, SDK, Agent Canvas, and agent server share conversation folders with
`base_state.json` and numbered event files. Hansard preserves those files,
normalizes messages and tools, and updates a resumed conversation in place.
Legacy application folders with numeric event files are also supported.

Default discovery covers `~/.openhands/conversations`,
`~/.openhands/agent-canvas/dev_conversations`, and legacy `sessions/` and
`users/*/conversations/` under the provider root. `HANSARD_OPENHANDS_ROOTS`
accepts a path-separated list of provider roots. `OPENHANDS_PERSISTENCE_DIR`,
`OH_PERSISTENCE_DIR`, and `OH_CANVAS_SAFE_STATE_DIR` are honored.

For an arbitrary SDK directory, copied trajectory, or mounted container store,
set `OPENHANDS_CONVERSATIONS_DIR` or `OH_CONVERSATIONS_PATH` to the folder
containing the conversation directories. Original files remain unchanged.

Cloud conversations use a separate, explicit API import. Their persistent event
history remains available when a runtime is paused, while model usage comes
from combined snapshots. Hansard keeps cloud and local source labels distinct
and preserves the richer local SDK archive when both represent the same
conversation.

## Import and keep current

**Conversation history**

```sh
hansard import --source openhands --since all
hansard config sources enable openhands
```

The watcher observes local state, metadata, and event files. A stable snapshot
is required; files changed during capture are retried on the next import.

Set `OPENHANDS_API_KEY`, then run:

```sh
hansard import openhands-cloud --since all
```

Use `--session <uuid>` for one conversation. `OPENHANDS_ORG_ID` selects an
organization; `OPENHANDS_CLOUD_URL` selects a self-hosted HTTPS origin. The
default is `https://app.all-hands.dev`.

Only the persistent app API is read. Hansard requires complete pagination, never
starts a sandbox, and never forwards the API key to a runtime URL. Matching
local SDK archives take precedence over cloud refreshes. Turn on **OpenHands
Cloud** in **Settings → Imports → Cloud agents** to have the watcher refresh it
every six hours.

**Memories and instructions**

```sh
hansard memory backup
```

Backups include personal memory, project `.openhands/memory`, the always-on
`microagents/repo.md` instructions, and supported instruction files such as
`AGENTS.md`. Skill folders and knowledge microagents are not memories and are
not backed up. The working directory and nearest Git
root come from imported local conversations. Nested instruction discovery checks up to 50 directories; symlinks are not followed. Cloud memories are not fetched.

## Review the import in the app

1. When the import finishes, open **Conversations** and select **Filter & sort**.
2. Set **Source** to **OpenHands** 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.

Review tool arguments, error results, and numbered edit diffs. Check the
OpenHands provider and recorded models in Stats, then open Memories to verify
captured instructions. Delegated and automated prompts do not count as human
activity.

## What Hansard preserves

- Prompts, replies, reasoning, injected context, tools, errors, rejections, and edits.
- SDK active branches, recorded fork ancestry, child links, titles, and workspaces.
- Measured response tokens, cache and reasoning splits, and recorded cost estimates.
- Inline images, captured observation files, and raw source files.
- Legacy event JSON and auxiliary state files, including opaque pickle bytes.

SDK usage includes spending on inactive branches. Copied child and fork usage
is excluded when the source provides enough identity evidence. Latest model
settings do not assign a model to older responses. ACP input/cache semantics
are handled separately, and repeated ACP response IDs retain each turn.

## Known limitations

- Native verification covers released CLI read, edit, resume, and instruction
  creation. Current SDK branches/ACP, legacy stores, children, and cloud APIs
  have fixture coverage. Live delegation, the Agent Canvas/server UI, and
  authenticated cloud service access have not received separate native trials.
- Cloud returns combined usage snapshots without historical model attribution.
  Those tokens remain under Unknown model. Returned events lack an active branch
  pointer. Runtime files, ZIP downloads, and cloud memories are not fetched.
- Plain SDK forks can omit their parent identity. Copied history remains when its
  owner cannot be established. Missing child stores leave copied usage in the
  parent. Inconsistent cloud parent/child snapshots require a later retry.
- Legacy pickles are never executed or deserialized. Fields available only
  inside them cannot supply normalized metadata or usage.
- Remote attachment URLs remain references. Local files outside captured
  conversation stores are not fetched. Unsupported record shapes are counted
  and retained in raw preservation.
- Native API credentials, environment configuration, runtime caches, installed
  binaries, and derived indexes are not separate conversation or memory sources.

## Refresh an existing archive

```sh
hansard import --source openhands --since all
hansard memory backup
```

Original sources are required for a parser refresh. SDK sessions with a known
local conversations root can be resumed through the viewer's copied command.

Official references: [OpenHands](https://openhands.dev/),
[Software Agent SDK](https://docs.openhands.dev/sdk), and
[CLI source](https://github.com/OpenHands/OpenHands-CLI).