Sessions & strands

Every ka session is a strand: one append-only JSONL file, a tree of records with a single live tip. The strand is the session’s state: replaying records to the tip reproduces everything, including the model, effort, and permission mode in use.

Where strands live

~/.local/share/ka/strands/<encoded-cwd>/<timestamp>_<id>.jsonl
spills:     ~/.local/share/ka/spills/<id>          (oversized tool output)
snapshots:  per-session journals under the data dir (file undo)
waypoints:  $TMPDIR/ka/<tty-hash>                  (strand id + tip per terminal)

Use KA_DATA_DIR to relocate the whole tree (handy for dev/prod separation).

Record kinds

Record	Meaning
header	First line: id, timestamp, cwd, versions, and a repo snapshot (branch + dirty list)
message	User, assistant, or tool traffic
change	A settings change (model / effort / mode) with the role that made it
name	A memorable alias set with /name <word>; the last one wins
digest	A compaction record: summary + the kept-tail boundary
boundary	A clear-context marker
custom	Namespaced extensions (x.<vendor>.<name>); the engine reserves x.ka.*

Offshoots, forks, and waypoints

• An offshoot moves the tip to an earlier record (branching in place). /rewind (or ka rewind N) works this way, dropping the last N user turns.
• A split copies a strand’s prefix into a new strand file with a parent link: a true fork.
• A transfer (/transfer [focus]) digests the live context into a fresh child strand that carries only the summary, with the parent link set: a clean handoff when the old context is mostly noise.

Resuming

ka -c                       # this terminal's latest strand
ka --session 3f9c2a81       # by id prefix
ka --session auth-rework    # by name (/name <word>)
ka serve → POST /sessions {"resume":"latest"}   # over HTTP/SSE

On resume, ka streams-parses the strand, replays change records to restore settings, and synthesizes an aborted stop for any dangling turn (a killed process leaves nothing inconsistent; the log just ends). Names resolve exact-first (newest wins), then by unique prefix, identically in the TUI, ka serve, and ACP; ka sessions shows name · title.

Exporting and searching

ka sessions              # list ids, titles, message counts, cost
ka export -o session.md  # newest strand for this cwd, as markdown
ka export --html         # or as a self-contained offline HTML page
ka search "auth middleware"   # FTS5 across all strands (index feature)

File snapshots and undo

edit and write park the target’s current bytes under the data dir before every mutation; if the snapshot fails, the change is refused. /undo (or ka undo) restores the most recent one; undoing a file creation deletes it. Snapshots are journaled per session.