---
title: "Sessions and context"
---

# Sessions and context

How the CLI saves, resumes, undoes and exports sessions, and how it keeps long sessions inside the model's context window.

## Sessions are saved

Every conversation is saved as it goes, in `~/.neuralinverse/projects/<workspace>/sessions/*.jsonl` (mode 0600). Saved sessions older than `sessionRetentionDays` (default 30; `0` keeps them forever) are deleted.

| To | Use |
|---|---|
| List saved sessions in this folder | `neuralinverse sessions`, or `/history` in a session |
| Continue the latest session in this folder | `neuralinverse --continue` (`-c`) |
| Continue a given session | `neuralinverse --resume <id>` (`-r`); any unique prefix of the id works |
| Pick a session from a list | `neuralinverse --resume` |
| Continue a saved session from inside a session | `/open` |
| Not save a session | `--no-session-persistence` |

Sessions started in an editor over ACP are saved the same way, so a conversation can move between the terminal and the editor with `--resume`.

### Organise sessions

| Command | What it does |
|---|---|
| `/rename` | Give the conversation a title, shown in `/history` |
| `/tag <name>`, `/tag -<name>` | Tag or untag it; `/history --tag <name>` lists only tagged ones |
| `/fork [title]` | Copy the conversation into a new session and continue there; the original stays as it was |
| `/new` | Start a fresh conversation; settings stay |

## Checkpoints, undo and restore

Every prompt is a checkpoint. Before the agent changes a file, its original contents are kept in `~/.neuralinverse/projects/<workspace>/checkpoints/`.

- `/undo` takes back your last message and the file changes it caused.
- `/restore` returns to the point before an earlier message.

## Export and share

| Command | Output |
|---|---|
| `/export` | The full transcript as Markdown |
| `/share [file]` | One self-contained HTML page: no external requests, tool calls folded, keys and tokens redacted. Default `~/.neuralinverse/exports/<id>.html` |
| `neuralinverse sessions export <id> --html [--out file]` | The same HTML page, from the shell |

## Project instructions and memory

The agent reads `AGENTS.md` (or `NEURALINVERSE.md`) at the start of every session, from your global configuration folder and from every folder between the repository root and the working folder. `/instructions` shows what is loaded, `/bootstrap` drafts a first version and `/remember <note>` adds a line. See [Instructions, commands and skills](https://neuralinverse.com/docs/cli/extending/).

Separately, notes the CLI remembers between sessions are kept in `~/.neuralinverse/projects/<workspace>/memory.md` when `services.memory` is enabled (`services.memory.maxNotes` bounds them).

## Keep long sessions inside the context window

Long sessions keep the request small without losing work. Only the request sent to the model changes; the saved session keeps everything.

| Setting | Default | Effect |
|---|---|---|
| `context.clearToolResultsAfterTokens` | 40% of the model's window | Once the conversation is estimated above this, older tool results are sent as one-line stubs, for example ``[output of run_shell `npm test` from turn 3 cleared to save context — 2,340 lines; re-run if needed]`` |
| `context.keepRecentToolResults` | 6 | The most recent tool results are always sent in full. Results the agent used afterwards (it mentioned a path or identifier from them) are kept too |
| `context.spillThresholdChars` | 50000 | A longer tool result is saved to `~/.neuralinverse/projects/<workspace>/spill/<id>.txt`; the model sees its head, tail and the path, and can read the rest with `read_file`. Spill files are removed after 7 days |
| `context.awaySummary.enabled` | true in interactive sessions | When you return after a break, or resume an old session, a short recap of where things stand and the next step is shown before your next prompt |
| `context.awaySummary.afterMinutes` | 30 | Idle time before a recap is offered |
| `compaction.auto` | true | Summarise the history automatically when it gets too long |
| `compaction.threshold` | 0.85 | Fraction of the context window at which automatic compaction starts |

Clearing is friendly to prompt caching: cleared results keep identical stubs, and when more must be cleared the boundary jumps to 75% of the limit at once, so the cached prefix changes in occasional steps.

To act by hand:

- `/window` shows how full the context window is, the estimated split of the next request (system prompt, tool definitions, memory and instructions, messages, tool results, images) and how many results are stubbed.
- `/condense` replaces the history with a summary to make room.
- `/summary` and `/aside` answer without changing the conversation.

A `compact.before` [hook](https://neuralinverse.com/docs/cli/hooks/) can block automatic compaction.

## Files the CLI writes

| Path | Contents |
|---|---|
| `~/.neuralinverse/projects/<workspace>/sessions/*.jsonl` | Saved conversations (mode 0600) |
| `~/.neuralinverse/projects/<workspace>/checkpoints/` | Original file contents for `/undo` |
| `~/.neuralinverse/history.jsonl` | Prompt history (`Ctrl+R`) |
| `~/.neuralinverse/projects/<workspace>/memory.md` | Notes remembered between sessions |
| `~/.neuralinverse/projects/<workspace>/index/` | Code index |
| `~/.neuralinverse/projects/<workspace>/spill/*.txt` | Full text of very long tool outputs |
| `~/.neuralinverse/exports/<id>.html` | Shared conversations |
| `.neuralinverse/plans/<date>-<slug>.md` | Plans written by `/deep-plan` |

`NEURALINVERSE_CONFIG_DIR` moves `~/.neuralinverse` elsewhere.