---
title: Sessions, history & transcripts
description: Where Nori keeps session state on disk, and the documented JSONL transcript format.
status: verified
sidebar:
  order: 3
---

A Nori session is a conversation with an agent plus everything that happened
in it — messages, tool calls, patches, and approvals. Nori records it all on
the host side, independent of whatever the agent stores for itself.

## On-disk layout

Everything lives under the Nori home directory: `$NORI_HOME` if set,
otherwise `~/.nori/cli`. Transcripts are organized by project:

```text
~/.nori/cli/transcripts/by-project/{project-id}/
  ├── project.json            # project metadata
  └── sessions/
      └── {session-id}.jsonl  # one file per session
```

Message history — every prompt you've typed, recallable from the composer in
any session — is a separate global file, `~/.nori/cli/history.jsonl`.

Transcripts are what make sessions durable: `nori resume` (or `/resume` in
the TUI) brings one back, and `/fork`, `/compact`, and `/undo` rewind and
reshape it — see the [sessions guide](/cli/guides/sessions/).

## The transcript format

Each session file is JSONL: one JSON object per line, each carrying a
timestamp, a schema version (currently `2`), and one of seven entry types —
`session_meta`, `user`, `assistant`, `tool_call`, `tool_result`,
`patch_apply`, and `client_event`. The format is documented as a stable
contract, so external tools — analysis scripts, other hosts, other ACP
implementations — can read and write Nori transcripts without depending on
Nori's internals.

:::note
The full schema, field-by-field, lives in the repo:
[`docs/reference/transcript-format.md`](https://github.com/tilework-tech/nori-cli/blob/main/docs/reference/transcript-format.md).
:::

## Next steps

- [Sessions guide](/cli/guides/sessions/) — resume, fork, compact, and undo
  in practice
- [Architecture](/cli/develop/architecture/) — where transcripts sit in the
  `nori-harness` runtime layer