Windsurf

Windsurf local storage can contain readable transcript-hook JSONL and plan artifacts alongside opaque protobuf conversation bodies. Downloaded Cascade trajectories are the explicit path to a full readable transcript when the local store is incomplete.

Source IDs

Source	Use it for
windsurf	Local transcript hooks, readable plans, raw protobuf sidecars, and downloaded trajectories.

How the import works

Hansard can obtain Windsurf history from four progressively different sources: the official transcript-hook JSONL, bulk recovery from a running Windsurf language server, downloaded trajectory Markdown, and local Cascade plan or protobuf artifacts. Structured hook records map directly to user, assistant, tool, result, and context events. Bulk recovery asks the running local language server for each trajectory by its stable identifier and checkpoints responses so an interrupted recovery can continue. It is a read-only operation and does not store Windsurf’s local authentication token.

Several of those sources may describe the same Cascade trajectory. Hansard reconciles them only when they carry the exact trajectory identifier. An official structured transcript ranks above a language-server recovery, which ranks above readable brain artifacts and opaque protobuf recovery. The best source supplies the transcript while lower-ranked copies can add a title, working directory, timestamps, or raw provenance. Similar content with a different identifier remains a separate conversation.

Older on-disk protobuf bodies are preserved but not decoded. A readable plan can therefore appear as a clearly partial repair stub until bulk recovery or a downloaded trajectory supplies the full conversation. Importing a downloaded trajectory normally reconciles it by trajectory identity; when a stub exposes a claim token, the --claim command replaces that exact stub explicitly. The watcher follows readable local hook and plan changes, while bulk recovery and downloads remain deliberate backfill actions.

Import and keep current

Import now

hansard import --source windsurf --since all
hansard index rebuild

Recover all readable trajectories from a running Windsurf instance:

hansard import windsurf --recover --since all

Import a downloaded trajectory directly when local history is partial:

hansard import windsurf /home/user/Downloads/cascade-conversation.md

Keep current

hansard config sources add windsurf
hansard watcher restart

A downloaded trajectory is a manual recovery artifact, not a watched source.

Review the import in the app

After the import finishes, open Conversations and selectFilter & sort. Set Source toWindsurf, choose the backfill window underTime, and use Folder when the same harness appears in several projects. Select a result to inspect its messages, tool calls and results, files, commits, model and usage fields, and source provenance in one conversation view.

For a local source that should stay current, open Settings → Indexing & Imports. Automatic follows detected local harnesses; Custom lets Sources scannedselect an explicit set. Explicit cloud and account-export sources do not turn into background network jobs here. If the expected result is absent after resetting the conversation filters, return to the terminal import in this guide and add --explain-skips where supported.

What Hansard preserves

• Structured transcript-hook turns when the official hook wrote them.
• Readable Cascade plans and matching provider metadata.
• Opaque protobuf files as raw source material without pretending to decode their message bodies.
• Downloaded trajectory Markdown as the full readable transcript when supplied.

Known limitations

• Legacy local protobuf conversation bodies are not decoded.
• A plan-only local record is not equivalent to a complete conversation.
• Downloaded trajectories must be imported manually. When a local repair stub shows a claim token, use hansard import windsurf --claim <token> <file> to replace it explicitly.

Recover before diagnosing missing turns

Use Windsurf’s Download trajectory action, then import the resulting Markdown file. This is more reliable than guessing from an opaque local body.

Refresh an existing archive

hansard import --source windsurf --since all
hansard index rebuild

Reimport downloaded trajectories separately if their source files changed.