Persist and Resume Sessions

By default kli keeps the session log in memory and discards it when you quit. To carry a conversation across runs, point kli at a directory to write session files into, then reopen a saved session by id or resume the newest one on boot.

Persist sessions to disk

Set sessionDir in your settings so kli writes each session to a file instead of holding it in memory.

Set it in settings.json (global ~/.config/kli/settings.json, project <repo>/.kli/settings.json; project wins) — see Settings:

{
  "sessionDir": "~/.config/kli/sessions"
}

A leading ~ expands to your home directory; a relative path resolves against the directory you start kli in. The directory is created on first write.

Restart kli for the change to take effect. From then on, kli writes one file per session, named <session-id>.session, under that directory. Each file is a header followed by one record per turn, appended as the conversation grows.

To check whether the current session is being written, run /session. It reports the session id, the file path backing it, the active model, and the token count. A session with no sessionDir configured shows file: (memory).

For the full settings schema, see Settings.

Resume a saved session

Resuming switches the current session onto a stored one. There are three ways in, depending on whether you know the id and whether you are at the terminal UI.

Resume the newest session on boot. Pass -c (or --continue) when you start kli:

kli -c

kli resumes the most recently stored loadable session. With no stored sessions, it starts fresh.

Pick from a list in a running session. Run /resume with no argument. In the terminal UI this opens a menu over your stored sessions, newest first. Without the UI, /resume prints the list as text rows, each marked with * for the active session and showing the id, name, message count, and a preview of the opening prompt.

Resume a specific session. Pass an id or a search term:

/resume session-12
/resume refactor

An exact id resumes that session. Otherwise kli searches ids, names, and previews: a single match resumes, several matches print the narrowed list to choose from.

To name a session so it is easy to find later, run /name <text>. To remove a stored session, run /resume delete <id> — you cannot delete the session you are currently in.

Branch and rewind through past turns

Rewinding steps the conversation back to an earlier point. kli does not overwrite history when you do this: it branches the session before the chosen prompt and switches onto the new branch, so the turns you stepped back from remain on the original session.

Step back the latest turn. Run /rewind with no argument to undo the most recent user turn.

Step back several turns. Pass a count:

/rewind 3

This rewinds to before the third-newest prompt. If the session has fewer turns than the count, kli reports nothing to rewind. In the terminal UI, bare /rewind opens a menu over the session's user turns.

See and switch between branches. Run /branches to view the tree of sessions that rewinding has produced. In the terminal UI this opens a selection menu over the tree; accepting a row switches onto that branch. Without the UI, /branches prints the tree as indented rows, marking the active session with * and labelling each branch by the prompt it diverged from.

Branching and rewinding only persist across restarts when sessionDir is set. In memory the branches still work, but they vanish on exit along with the rest of the log.

Related

• /kli/cli/installation — install kli and start it in a project.
• Settings — every settings key, with types and defaults.
• Sessions as a Tree — what a session is and how the log is structured.