---
title: Context, memory and the agent runtime
description: How a session keeps its context small (masking, compaction, recall), carries memory between sessions, undoes file changes, and runs its agents as processes you can signal and suspend.
section: harness
order: 80
audience: [builder, agent]
sources: [packages/harness/src/context, packages/harness/src/memory, packages/harness/src/runtime, packages/harness/src/checkpoints, packages/harness/src/codeindex, packages/harness/src/lessons, packages/harness/src/edit, packages/harness/src/patch, packages/harness/src/format, packages/harness/src/lsp, packages/harness/src/guards, packages/harness/src/todo, docs/runtime-and-memory.md]
features: [harness.context, harness.memory, harness.runtime, harness.runtime-and-memory, harness.checkpoints, harness.codeindex, harness.lessons, harness.edit, harness.patch, harness.format, harness.lsp, harness.guards, harness.todo]
---

Long agent runs fail in predictable ways: the context fills with old tool output, the agent loops, an edit breaks the build, or the process dies mid-task. The harness handles each of these by default. This page says what runs, what to configure, and which subpath exposes it.

## Context management {#context}

Context is kept small in layers, all on by default:

| Layer | What it does | Configure |
|---|---|---|
| Output caps | long command output and huge files are cut, with the full text spilled to a file the agent can `read` | always on |
| Masking | old tool results are replaced by a stub once the window passes a share of its size; the original goes to a content-addressed blob store | `compaction.minMaskChars` (600) |
| Compaction | when the window passes `compaction.triggerRatio` (0.55), older turns are summarised on the `fast` tier; the last `keepTurns` (10) stay verbatim | `compaction`, or `false` for pi's own compaction only |
| Pinned facts | facts marked as pins survive every summary word for word | `/pin` in the CLI |
| `recall` | a tool that finds text compaction moved out of view | loads with compaction |
| Focus | a `focus` argument on `read`, `grep` and `bash` keeps only matching parts | loads with memory |

`@venom/harness/context` exposes the token estimates and masking plans (`estimateTranscriptTokens`, `planMasking`, `analyzeMemory`); `@venom/harness/memory` holds the types of the memory layer (blob handles `blob:sha256:<hex>`, pins, working sets, the copy-on-write context descriptor that lets a subagent share the parent's context without copying it). `/context` in the CLI, or `cost.contextBreakdown`, shows what fills the window.

The system prompt and tool list are built once per session and never change per turn, so the model server's prompt cache keeps hitting.

## Memory across sessions {#memory}

| Layer | Where | Who writes it |
|---|---|---|
| Instruction files | `AGENTS.md`, `CLAUDE.md` (and `CLAUDE.local.md`, `.claude/CLAUDE.md`, `@imports`) from `/` down to the working directory, `~/.claude/CLAUDE.md`, `~/.venom/agent/AGENTS.md` | people, committed with the code |
| Auto-memory | `~/.venom/projects/<slug>/memory/` (`MEMORY.md` index plus one file per memory; Claude Code's directory is read too) | the agent, through the `memory` tool |
| Lessons | `<dir>/lessons.json` | code only (`lessons.addLesson`): a lesson is admitted only with a cue, an action and evidence from a closed task |
| Org memory | Venom Cloud, cached locally | with `HarnessOptions.orgMemory`: facts for this checkout join the prompt once per session |

All load once at session start. Lessons are guidance, never a permission: nothing reads one to allow or deny a call. `@venom/harness/lessons` has `admit`, `addLesson`, `loadLessons`, `rejectLesson` and `renderLessons`.

## Checkpoints and undo {#checkpoints}

Before each turn that may change files, the harness snapshots the workspace into a shadow git store under `<venomHome>/checkpoints` (never your repository's `.git`). `harness.checkpoints` then gives:

| Method | Does |
|---|---|
| `list(sessionId?)` | this branch's turn checkpoints, oldest first |
| `undo()` / `redo()` | the last run's files back to before it, and forward again |
| `preview(entryId)`, `restore(entryId, { position: "before" \| "at" })` | look at, then go back to, any turn |
| `turnChanges(entryId)` | one turn's files with before and after text (secrets, binaries and large files omitted) |
| `sessionFiles()` | every file the session changed, with added and removed line counts |
| `gc()` | apply retention |

| `checkpoints` option | Default |
|---|---|
| `maxFileBytes` | 2 MiB |
| `maxTotalBytes` | 512 MiB |
| `maxFiles` | 50000 |
| `retention` | `{ maxCount: 1000, maxAgeDays: 14 }` |
| `dir` | `<venomHome>/checkpoints` |
| `exclude` | `[]` (plus built-in excludes such as `node_modules`) |

Checkpoints need git on the machine; `checkpoints.enabled` and `disabledReason` say why they are off. `@venom/harness/checkpoints` exports `Checkpoints`, `ShadowStore` and the record types for hosts with their own session store.

## Editing tools {#edits}

| Feature | What it does | Option, subpath |
|---|---|---|
| Edit recovery | when an `edit` misses (whitespace, a stale view), it finds the intended spot or explains why it failed | `@venom/harness/edit` |
| `apply_patch` | the patch format some models are trained on, applied all files or none | `editTool` (`auto` picks per model); `@venom/harness/patch` (`parsePatch`, `planPatch`, `commitPlan`) |
| Formatting | after an edit, the formatter the project declares (Prettier, Biome, gofmt, ruff, rustfmt, …) runs on the file | `format`; `@venom/harness/format` (`detectFormatter`, `runFormatter`) |
| Diagnostics | after an edit, a language server reports new errors in the file and, when its surface changed, in files that depend on it | `lsp` (`timeoutMs` 1500, `maxServers` 4, `idleMs` 600000); `@venom/harness/lsp` (`LspManager`) |
| Code index | in large git repositories, a `code_search` tool over definitions, references, BM25 text and a PageRank repo map | `@venom/harness/codeindex` (`CodeIndex`); stored under `<venomHome>/index/` |

Formatters and language servers run only when the project declares them and the binaries exist; they run inside the sandbox when bash does.

## Runaway guards {#guards}

| Guard | Default | Effect |
|---|---|---|
| `repeatThreshold` | 3 | the same call repeated: the agent is told to change course |
| `maxRereads` | 6 | the same file region re-read |
| `maxToolCalls` | 200 per run | the run is wrapped up |
| `maxTurns` | unbounded | turn cap |
| `maxSeconds`, `maxCost` | unbounded | wall-clock and spend caps per run |
| `bashTimeout` | 120 s (max 3600) | per-command timeout |
| `overthink` | on (`reasoningBudget` 6000, `idleTurns` 3, `maxNudges` 3) | nudges a model that reasons for turns without acting |

Each firing is a `guard` event. `@venom/harness/guards` has the trackers (`RepeatTracker`, `RereadTracker`) and defaults (`DEFAULT_MAX_TOOL_CALLS`, `DEFAULT_BASH_TIMEOUT_SECONDS`).

## The todo list {#todo}

With `planning` on, the agent keeps a checklist with the `todo` tool; each write sends the full list. `@venom/harness/todo` normalises it (`normalizeTodos`: ids, statuses `pending`, `in_progress`, `completed`, `cancelled`, one in progress at a time), and the `todos` event carries it to your UI. After `TODO_REMINDER_TURNS` (10) turns without an update, the agent is reminded of open items.

## Agents as processes {#runtime}

Every agent of a session (the main one and each subagent) is a process in a small runtime with a pid, a state and a usage meter. Pids are unique in the whole Node process; the main agent's pid is its tree id.

```ts
const s = await createVenomSession({ cwd: "/work/repo", persist: true });
const h = s.harness;
h.agents();                                 // the process tree: state, model, turns, tokens, cost, last action
h.signal("SIGSTOP", { pid: childPid });     // park a subagent at its next turn boundary
h.signal("SIGCONT", { pid: childPid });
h.signal("SIGTERM", { tree: true });        // stop the whole tree at the next safe point
```

| Signal | Effect |
|---|---|
| `SIGINT` | stop now; subagents return a partial report (Esc in the CLI) |
| `SIGTERM` | stop at the next turn boundary |
| `SIGKILL` | stop now, waiting at most 5 s for a file write in progress |
| `SIGSTOP` / `SIGCONT` | park and resume, no request in flight while parked |
| `SIGUSR1` | write a checkpoint of the agent into its session file |
| `SIGUSR2` | emit its process row as an event |

A checkpointed agent resumes in another process that opens the same session (`sessionFile`): the model, board notes, todos and pins come back; the mode only if it is no more permissive than the new process's. Agents share a fair scheduler (pass one `kernel` to several harnesses to share it across sessions) and quotas (`runtime.quotas`). `@venom/harness/runtime` exports the types (`ProcInfo`, `Signal`, `RuntimeOptions`, `RUNTIME_DEFAULTS`). Over HTTP the same controls are `GET …/agents` and `POST …/agents/{pid}/signal` ([server API section](/docs/server-api.md)).

## Related {#related}

- [Sessions, events and cost](/docs/harness/sessions.md)
- [Subagents and model tiers](/docs/harness/subagents.md)
- [CLI section](/docs/cli.md), for `/context`, `/compact`, `/undo`, `/ps`
