Memory and storage limits
How komrad stays inside the memory and disk space you give it, which agents it makes dormant first, and which worktrees it deletes first.
Komrad runs as a guest on your machine. You give it a memory limit and a storage limit, and it keeps itself and every agent inside them. To get under the memory limit, komrad makes agents dormant. To get under the storage limit, it deletes the worktrees of archived tasks. Each limit works from a ranked queue, and the system view shows every queue as it stands.
The memory limit#
Set limit under [performance.memory], as a size such as "12GiB". The default "0" sets no limit.
Komrad measures what it and each agent cost once a second. An agent’s footprint is the memory its processes hold that the system can’t drop, with shared memory split between the processes that share it. Komrad’s own share covers the server, the embedded Postgres, tmux, the language servers, hooks and the panel.
When the total passes the limit, komrad makes agents dormant from the top of the dormancy queue until it is a margin under. Making an agent dormant closes its pane and stops every process it started. The agent keeps its conversation and any draft in its input box.
Before komrad launches or resumes an agent, it makes room for that agent’s expected cost in the same way. Making room takes resting agents, and for a launch or resume you asked for, any agent with an overage that isn’t in use. When they can’t make room, a launch or resume you asked for fails and says komrad is at its memory limit.
The dormancy queue#
The dormancy queue holds every live agent with a pane, in the order komrad makes them dormant. Komrad ranks each agent by the first rule it matches. Resting means idle or errored, without a draft and off screen.
- A reviewer whose review is released, resting.
- An agent on a task whose pull requests have all merged or closed, resting.
- An agent resting without unread mail.
- An agent resting with unread mail.
- An agent other than an orchestrator waiting on you, off screen.
- An agent other than an orchestrator working, or whose pane reads as uncertain, off screen.
- An orchestrator that isn’t resting, or that holds unread mail, off screen.
- An agent whose pane holds a draft or is on screen.
Agents under the same rule go longest quiet first. An agent went quiet at the latest of its last state change, its newest transcript entry and the newest mail it read. Under rules 6 and 7, the largest footprint goes first instead, since a working agent loses its turn wherever it sits.
An orchestrator that is idle without mail falls under rule 3 like any other resting agent. Opening an agent’s pane moves it to rule 8. Mailing a resting agent moves it to rule 4, or to rule 7 for an orchestrator. Each move lands at the next rebuild a few seconds later.
Each agent’s allowance is its fair share of the limit: the limit less komrad’s own share, divided among the agents with panes, and never less than the estimate for a new agent. An agent’s overage is its footprint past its allowance. It counts once it lasts five seconds, or once it has lasted since the total last rose past the limit or past a margin under it. To get under the limit, komrad makes agents with an overage dormant before every other agent, largest overage first, whatever rule they match. An agent whose pane holds a draft or is on screen keeps its place under rule 8. An agent launched or resumed in the last two minutes is settling. Komrad makes a settling agent dormant only for its own overage, or when the total runs a margin past the limit.
The recovery queue#
Komrad puts each agent it made dormant to get under the limit on the recovery queue, so it comes back once the pressure passes. It leaves out released reviewers, agents on merged tasks and resting orchestrators, since none of them has work waiting.
An agent made dormant for its overage waits behind every agent made dormant for another reason. Otherwise agents with unread mail come off first, then the last agent on comes off first. Once komrad has made no agent dormant for a minute, it resumes the first agent whose expected cost fits under the limit. An agent never expects more than its allowance. Komrad resumes one agent at a time. Once an agent has waited ten minutes on the queue without fitting, komrad resumes nobody behind it until it fits, even when agents made dormant later move ahead of it. An agent made dormant within ten minutes of its last resume waits a minute before komrad resumes it again, and twice as long each time in a row this happens, up to thirty minutes.
An agent leaves the recovery queue when it resumes by any path, or when it is archived or deleted. An agent without unread mail also leaves once it has been quiet longer than idle_agent_max_age.
An agent made dormant mid-turn gets a mail when it resumes. The mail tells it that its last step may not have finished and that every process it started has stopped.
The storage limit#
Set limit under [performance.storage], as a size such as "100GiB". Komrad measures its state directory, its cache directory and every worktree each disk_space_check_interval. When the total passes the limit, komrad deletes worktrees from the top of the deletion queue until it is under. Deleting a worktree keeps the task’s records.
The deletion queue#
The deletion queue holds the worktree of every task archived longer than archived_worktree_min_age. Komrad ranks each worktree by the first rule it matches.
- Landed: nothing uncommitted, and the base branch holds every commit.
- Merged: nothing uncommitted, and a pull request on the task merged.
- Committed: nothing uncommitted, with commits the base branch lacks.
Worktrees under the same rule go longest archived first. Komrad keeps a worktree that git can’t read, or that holds uncommitted changes or a rebase or merge part way through, and says why. Before it deletes a worktree, komrad asks git once more whether deleting it loses work. It keeps a worktree git refuses for an hour, or until the worktree changes.
Other limits on age#
Three more settings make room on a timer, whatever the limits say, and "0" turns each off. idle_agent_max_age makes an agent dormant once it has been idle that long, and mail resumes it. merged_task_max_age archives a task once its last pull request merged and its agents stopped working. archived_worktree_max_age deletes the worktree of a task archived that long.
Reading the queues#
The system view draws the dormancy queue, the recovery queue, the agents komrad made dormant today and the deletion queue.
Agents read the same thing through get_memory_use and get_storage_use. In the API, the dormancy queue is the candidate list, the recovery queue is the resume list, and the deletion queue is the storage candidate list. Each agent on the candidate list carries its place, the rule it matched and when it went quiet, which together say why it sits where it does.