HX/ the human experience framework
The format · v0.1

PSFthe Portable Session Format

PDF made documents portable: the same file opens anywhere, decades later. PSF does that for AI work sessions — one open JSON shape for the session record, so the second codebase can move between tools, vendors, and years. Custody never means lock-in.

See an example →The JSON Schema
PSF
Design goals

Four properties, none negotiable

The format exists to make one sentence true for every organization: whichever system holds your record, you can take it — whole, verbatim, and checkable — somewhere else.

Tool-agnostic

One session per document, whatever agent produced it. Assistants change yearly; the archive shouldn't burn on each switch.

Verbatim, with shape

Turns and tool calls as they happened. Where content must be withheld, a redaction marker keeps the conversation's shape.

Scope-aware

The workspace block carries the repository — the boundary that makes a record a work record in the first place.

Provenance built in

Source system, export time, and a content hash, so a re-export can be compared and a claim can be checked.

The shape

One session, one document

{ "psf": "0.1", "session": { "id", "startedAt", "workspace": { "repository", "branch" }, "agent": { "name", "model" }, "author": { "id" } }, "turns": [ { "role", "at", "content" | "redacted", "toolCalls": [ … ] } ], "artifacts": [ { "kind": "commit" | "pull-request" | …, "ref" } ], "provenance": { "source", "exportedAt", "contentHash" } }
  • sessionIdentity and context: id, times, workspace (repository, branch, path), agent, and a pseudonymous author reference.
  • turns[]The conversation, verbatim: role, timestamp, content — or a redaction marker (secret / pii / policy / author-request) — plus tool calls with inputs and outputs.
  • artifacts[]Links to what the session produced: commits, pull requests, issues, documents.
  • provenanceWho emitted this document, when, and a hash of the canonicalized turns.

The normative definition is the JSON Schema; the example shows a full session, including a redacted turn, rendered the way a reader would actually want it. v0.1 is published for comment — the shape is deliberately small, and additions are expected to come from implementations. Comments to [email protected].

Why the record is worth keeping →Who gets to read it