Context, memory and the agent runtime
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.
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 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
| 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
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
| 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
| 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
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
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.
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).
Related
- Sessions, events and cost
- Subagents and model tiers
- CLI section, for
/context,/compact,/undo,/ps