Use
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 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; 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: 0instead 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;
recallreads 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). 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. See 02 · 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). 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:
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
PARENTfile 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.dirin 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).
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):
{ "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 / $capon a metered route. On the Claude Pro/Max subscription route the bill is a list-price estimate, shown as≈$spent list · subscription; alimitsrow 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:
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:
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 confirmationThe plain rebuild makes no model calls; --merge does, so it is never implied.
See also
- 02 · Configuration — the
ledgeranddatabaseconfig sections. - 08 · Bounding a long run — spend and clock bounds.