> ## Documentation Index
> Fetch the complete documentation index at: https://www.plungeai.com/guide/llms.txt
> Use this file to discover all available pages before exploring further.

# Session ledger and export

> A long session in most coding agents grows an ever-larger context until it slows down, costs more per step and finally has to be summarized. oceancode keeps the session ledger instead: the model sees a bounded window of the newest turns, and everything older is kept verbatim on disk, never …


A long session in most coding agents grows an ever-larger context until it slows down, costs more
per step and finally has to be summarized. `oceancode` keeps the **session ledger** instead: the
model sees a bounded window of the newest turns, and everything older is kept verbatim on disk,
never summarized away. The session ledger is the subject of a US provisional patent application;
the technology is patent pending. The story in user terms is
[Sessions that keep the thread](/ocean-code/tideline); this page is the
operator's reference.

## What the ledger is

- **A window of the raw conversation.** The model always sees the newest part of the real
  conversation, up to a bounded size — by default **40% of the model's context** (400k on a 1M
  model, 80k on a 200k model), measured in the provider's real tokens after every step.
  `tokens: 0` instead tracks the model's own ceiling — its context window minus the output
  allowance; 120k only when the route reports no limit. A *turn* is your message plus the model's
  full answer, tool outputs included.
- **Per-turn transcripts on disk.** Every step is written verbatim to its turn's transcript file as
  it ends. When the oldest turns move past the tideline they are already on disk, so nothing is
  lost and no model call is made; `recall` reads them back, and a tool output that left the window
  points at its transcript line.
- **`SESSION.md`, the ledger page.** Goal, decisions, environment facts, errors and their fixes, a
  code map, open questions, and the next step — each line stamped with the turn it came from.
  Facts the database already holds (files touched, commands and exit codes, tasks, the log) are
  written by the engine; the model adds what it learns through validated edits. Reversed decisions
  keep the old text struck through rather than deleted.
- **Skills survive a cut.** Clearing old tool output leaves the newest load of a skill alone
  whatever its size (a skill is at most 25,000 tokens, see
  [09 · Capabilities](/oceancode/capabilities#how-much-of-a-skill-the-model-gets)). When a cut does take
  one from a finished turn, the note the model sees names it (`reload with skill_<name>`). A skill
  loaded in the turn still running is carried over the cut whole, as long as the loads fit into
  25,000 tokens together; one that does not fit is named for reloading. No skill is carried in part.

The ledger ships **enabled** (`ledger.enabled: true`), so every session is ledgered from its first turn with no setup; its per-turn transcripts are kept as long as the session is: `retention.days` (default 7 days idle) removes a session and its ledger directory together — see [18 · Operations](/oceancode/operations#retention-and-vacuum). See [02 · Configuration](/oceancode/configuration) to change either. **Ocean Code never summarizes a session** — the legacy compaction (summarization) path runs only when `ledger.enabled` is `false`.

**How an open session is stored.** An open session lives in memory: every step reads its history from there, and its rows in `oceancode.db` are written *behind* the step, in batches, by the one database writer — a step never waits on the disk, however long the session grows. Anything that reads the database rather than the open session (an export, opening a session that already left memory, the retention sweep) first **settles** the writer: it waits for every queued write, so it sees the step that just ended. A session idle for 15 minutes leaves memory and is reloaded from the database on its next use. **What a crash loses:** only the writes still queued when the process died — normally the last few milliseconds (`oceancode_writer_lag_ms` on the metrics endpoint, see [18 · Operations](/oceancode/operations#metrics-oc_metrics_addr)). What is on disk is always an in-order prefix of the session — no gap in its event log, no row ahead of the event it came from — so a resume continues from the last committed step.

Find a session's ledger directory with:

```bash
oceancode ledger path <session-id>
```

## Recall across sessions

`recall` is how the model searches what left its window: a case-insensitive phrase, up to `limit`
excerpts (default 5, at most 10), each with an absolute `path:line` it opens with `read`. It never
writes.

- **This session** (the default scope): `SESSION.md`, then the transcripts newest turn first,
  `LOG.md`, then the notes.
- **A sub-agent** searches its own ledger first (a long one has turns past its own tideline), then
  each ledger above it up to its lead's, where the decisions it works under were made, following the
  `PARENT` file the ledger writes for every sub-agent; the hit limit is shared along the way
  (2026-11-05). `ledger_note`, the tool that writes the page, stays with the lead.
- **`scope: "project"`** searches the ledger page (`SESSION.md`) of every session under the ledger
  root, ranked by relevance in an index built in memory for the one query and dropped after; nothing
  is stored. The default root, `<data dir>/session-ledger`, holds every session on the machine, so
  this also reaches sessions that ran in other folders; `ledger.dir` in a project's config gives the
  project a root of its own. A hit points at a ledger page, never at another session's transcript,
  and a session has a page only once its agent recorded a note or turns were merged past the
  tideline: a short session has none.

The `sessions` tool is the other half: what each session on the machine is doing now
([12 · Session peers](/oceancode/permissions-and-sandbox#session-peers)).

## The tideline — `/tideline`

You set **one number**: the share of the model's context where the tideline sits
(`ledger.tideline.percent`, default `40`) — the **line** — or a fixed limit (`ledger.tideline.tokens`).
After every step the ledger measures the window in the provider's real tokens; when it reaches the
line, the oldest turns move past the tideline and the window shrinks, inside a long turn too.
`ledger.tideline.block` sets how much one cut removes, as a token count or a share of the line
(`"35%"`; unset = 70% of the line). Smaller cuts keep more recent turns in view and happen more
often; between cuts every step only appends, so the provider's prompt cache keeps hitting.

After a cut the window opens with one line that says earlier content is past the tideline and
names the ledger directory, so the model reads back rather than guesses. A turn whose every row is
past the tideline is merged into `SESSION.md`. When the model's context is unknown the fixed
`tokens` (default `300000`) is the line; a line above what the model can hold is clamped to that,
with one note in the log.

Every turn counts at its real size: what the provider says the request grew by since the previous
turn's last step — the prompt, the page copy the turn carries, the date line — so short turns fill
a block too. When the window is over the line and no block is closed, the open block is cut at the
next step; and when the provider refuses a request as too long, every closed block is cut, or the
open one when none is closed, so the retry is always smaller. The status bar names the one state
left: `tideline stuck (+N over M, nothing closed)` is the engine's own verdict that it has nothing
to cut. It clears at the next step unless what the window can never cut — the system prompt, the
pinned rules, the ledger page — is itself over the line; then every step cuts only its own growth
and the word stays, which is the sign to raise the line (`/tideline 60%`) or start a new session.

A directory's rule files (`CLAUDE.md`, `AGENTS.md`, `.oceancode/rules/*`) are pinned when a tool
first touches it and ride every later cut (`context.durable_rules`). A pinned rule can never leave
the window, so it is bounded: one directory pins at most 32 000 characters — a longer guide rides
as its head plus one line naming the files and the omitted size — and all pinned rules together at
most 160 000; a directory touched past that is announced but not pinned. Rules pinned before a build
with these limits are carried as they were.

The status bar's context row measures against the model's own context (`…/1.0M` on
`claude-fable-5-1[1m]`); the `┃` on its gauge sits at the tideline — `tideline @40% (400k): 238k to go`, or `tideline
@300k: 138k to go` under a fixed limit — and it reads `tideline off` when the ledger is disabled.

Config examples (`ledger.shelve` and `ledger.window` are still read as aliases):

```json
{ "ledger": { "tideline": { "percent": 50 } } }
{ "ledger": { "tideline": { "tokens": 500000, "block": 20000 } } }
```

`tokens: 0` means the model's own ceiling. The older keys — the floor (`low`), `reserve`, the
`profile` presets (`wide` · `narrow` · `strict` · `auto`) and `ledger.hard_tokens` — were removed
with the band geometry: an old config still loads, they are ignored, and the load logs one warning
naming them.

Change the tideline for a session at runtime with `/tideline`:

| Command | Effect |
|---|---|
| `/tideline` | Show the current tideline state. |
| `/tideline now` | Move the tide now (a cut). |
| `/tideline 50%` | Set the limit as a percent of the model's context. |
| `/tideline 500k` | Set a fixed limit. |
| `/tideline default` | Restore the configured limit. |

Minimum fixed limit 20k; `k` and `m` suffixes are accepted. The floor and the presets were removed;
a second number or a preset word is refused with the usage line. A change applies from your next
message on, which the confirmation says. Headless, the same set is
`--tideline "<percent>% | <limit> | default"`. A sub-agent (child) session inherits its parent's
`/tideline` override — the percentage, or the limit.

The meter's denominator is the model's context window, or the fixed limit when one is set.

## The session meter

Ocean TUI has no cockpit panel; its status bar and `/context` show the session meter:

- the **context meter** — what the current window costs against the session's window size;
- **token counts** — input and output for the session;
- **spend** — `$spent / $cap` on a metered route. On the Claude Pro/Max subscription route the
  bill is a list-price *estimate*, shown as `≈$spent list · subscription`; a `limits` row
  appears when a step or time bound is set.

On the Claude Code route the meter's **context** number is Claude Code's own real context — its
system prompt, `CLAUDE.md` files and MCP schemas, ~100k+ before any turn. When it reaches the limit the
session continues from the ledger, so the number restarts near that baseline and climbs again.

## Recovering a step — `/undo` and `/redo`

`/undo` (`/rewind`) reverts the conversation to a previous message and puts back every file that
turn and the later ones changed through the file tools (`edit`, `write`, `apply_patch`, sub-agents'
included); `/redo` re-applies both. It steps a bookmark through the session, so you can back out a
bad turn without losing the history. As in Claude Code, changes a `bash` command made are not
tracked.

## Exporting a session

Write a whole session out as one file:

```bash
oceancode export <session-id> --md   [--out <path>|-]   # one Markdown document
oceancode export <session-id> --atif [--out <path>|-]   # one ATIF-v1.8 trajectory (JSON)
```

Pass exactly one of `--md` or `--atif`. `--out -` (the default) writes to stdout; `--out <path>`
writes a file. The Markdown export carries frontmatter, every turn, and a `## Summary`
table, and is built from the ledger's own transcript files when they exist.

## Rebuilding the ledger

If a ledger directory is lost or a session predates the ledger, rebuild it from the database:

```bash
oceancode ledger rebuild <session-id>            # mechanical: transcripts, indexes, page
oceancode ledger rebuild <session-id> --merge    # also fold the merge backlog (model calls; asks y/N)
oceancode ledger rebuild <session-id> --merge --yes   # skip the confirmation
```

The plain rebuild makes no model calls; `--merge` does, so it is never implied.

## See also

- [02 · Configuration](/oceancode/configuration) — the `ledger` and `database` config sections.
- [08 · Bounding a long run](/oceancode/bounding-a-long-run) — spend and clock bounds.
