Skip to content
Docs menu

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.

View .md

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).