komrad

get_memory_use

Read what komrad and each agent cost in memory, against the memory limit, with each agent's place in the candidate list, the agents komrad made dormant today, and the highest, lowest and average total today.

read-onlyidempotentMCP toolSystem

Calling it#

curl -X POST http://127.0.0.1:8787/komrad.system.v1.SystemService/GetMemoryUse \
  -H 'Content-Type: application/json' \
  -d '{}'

Request#

Empty#

No fields.

Response#

GetMemoryUseResponse#

FieldTypeDescription
limit_bytesint64

The memory limit. Zero when no limit is set.

total_bytesint64

What komrad and its agents cost in the latest sample.

projected_bytesint64

The total plus what agents launched or resumed in the last 30 seconds are still expected to grow by.

margin_bytesint64

How far under the limit komrad goes when it makes agents dormant.

sampled_attimestamp

When komrad took the sample.

ownersMemoryOwner[]

Every owner in the sample.

made_dormantDormantAgent[]

The agents komrad made dormant since midnight, newest first.

to_resumeResumeListEntry[]

The agents on the resume list, which komrad resumes once there is room again, the next to resume first.

todayMemorySummary

What komrad and its agents cost across today's samples. Unset before the first sample.

reasonsSampleReason[]

What the latest sample couldn't read. Empty when it read everything.

incomplete_sincetimestamp

When the run of blind or incomplete samples began. Unset when the latest sample is complete.

is_warnedbool

Whether that run has lasted thirty seconds, long enough for komrad to warn.

sourceMemorySource

How komrad counts memory this run.

scanner_reasonstring

Why komrad counts memory with the process scanner. Empty under cgroups.

pressureLimitPressure

How close the latest sample stands to the memory limit, with margin_bytes as its margin.

Types#

MemoryOwner#

MemoryOwner is an agent or a part of komrad's own share, with the processes that count toward it.

FieldTypeDescription
one of

Who the processes count toward.

partKomradPart

The part of komrad's own share.

agentAgentOwner

The agent.

footprint_bytesint64

What the owner's processes cost together.

processesProcess[]

The processes that count toward the owner, largest first.

DormantAgent#

DormantAgent is an agent komrad made dormant to keep under the memory limit.

FieldTypeDescription
agent_idstring

The agent's id.

namestring

The agent's name.

ruleCandidateRule

The rule that put the agent at the top of the candidate list.

freed_bytesint64

What the agent's processes cost when komrad closed its pane.

made_dormant_attimestamp

When komrad made the agent dormant.

ResumeListEntry#

ResumeListEntry is a dormant agent waiting on the resume list for room under the memory limit.

FieldTypeDescription
agent_idstring

The agent's id.

namestring

The agent's name.

expected_cost_bytesint64

What komrad expects the agent to cost once it is resumed.

listed_attimestamp

When the agent went on the resume list.

has_unread_mailbool

Whether mail is waiting for the agent.

MemorySummary#

MemorySummary is what komrad and its agents cost across the samples since midnight, or since the server started when that was later.

FieldTypeDescription
sincetimestamp

When the first sample counted was taken.

peakMemorySample

The sample with the highest total.

lowMemorySample

The sample with the lowest total.

average_bytesint64

The average total across the samples.

programsProgramSummary[]

Every program counted, the most held on average first.

largestProcessPeak[]

The processes that held the most at once, the most first, five at most.

AgentOwner#

AgentOwner is an agent that processes count toward.

FieldTypeDescription
agent_idstring

The agent's id.

namestring

The agent's name.

candidateCandidate

The agent's place in the candidate list. Unset while the agent is setting up, and on a process peak.

resting_footprint_bytesint64

The lowest the agent held in the last ten minutes after resting for thirty seconds. Unset when it hasn't rested that long in that time.

highest_footprint_bytesint64

The highest the agent held in the last ten minutes.

Process#

Process is one process komrad counts toward its memory use.

FieldTypeDescription
pidint32

The process's id.

commandstring

The process's command name, such as claude or postgres.

cost_bytesint64

What the process costs, with shared memory split between the processes that map it.

corrected_attimestamp

When komrad last split the process's shared memory.

parent_pidint32

The id of the process that started this one. Zero when that process counts toward another owner.

MemorySample#

MemorySample is what something cost in memory at one sample.

FieldTypeDescription
sampled_attimestamp

When komrad took the sample.

bytesint64

What it cost at that sample.

ProgramSummary#

ProgramSummary is what one program's processes held together across a day's samples.

FieldTypeDescription
programstring

The program, such as postgres or gopls, without any title its processes set.

average_bytesint64

What the program's processes held together on average across the samples.

peakMemorySample

The sample where the program's processes held the most together.

seenint32

How many of the program's processes komrad saw, each counted once.

ProcessPeak#

ProcessPeak is one process at the most it held at once.

FieldTypeDescription
programstring

The program the process runs, such as postgres or gopls.

peakMemorySample

When the process held the most, and what it held then.

one of

Who the process counted toward then.

partKomradPart

The part of komrad's own share.

agentAgentOwner

The agent, with the name it had then.

pidint32

The process's id.

Candidate#

Candidate is an agent's place in the candidate list.

FieldTypeDescription
placeint32

Where the agent stands in the list, from 1 for the agent komrad makes dormant first.

ruleCandidateRule

The rule that put the agent there.

quiet_sincetimestamp

When the agent last went quiet, the latest of its last state change, its newest transcript entry and the newest mail it read. Agents under one rule go longest quiet first, except working agents and working orchestrators, which go largest footprint first.

SampleReason#

SampleReason is one fact a memory sample couldn't read. A sample missing any is incomplete, and one whose panes tmux couldn't list is blind.

ValueDescription
panes_unlisted

Tmux couldn't list its panes, so the sample can't tell which agent owns each pane or which is on screen.

postgres_unread

Komrad couldn't find the embedded Postgres.

counter_unread

Komrad couldn't read what a running process holds.

liveness_unread

The database couldn't say whether the agents behind tagged processes are live, so those processes count as leftover agent processes.

cgroup_unread

Komrad couldn't read a file of a cgroup that still exists.

MemorySource#

MemorySource is how komrad counts memory.

ValueDescription
cgroups

Komrad reads what the kernel charges each cgroup it holds itself and its agents in.

scanner

Komrad finds its processes and its agents' by walking the process tree, and reads what each costs.

LimitPressure#

LimitPressure is how close komrad stands to a memory or storage limit.

ValueDescription
under

Komrad takes less than the limit less its margin, or no limit is set.

near

Komrad takes more than the limit less its margin, and less than the limit.

over

Komrad takes the limit or more.

KomradPart#

KomradPart is one part of komrad's own share of memory.

ValueDescription
server

The server process.

postgres

The embedded Postgres and its backends.

tmux

The tmux server on komrad's socket.

language_servers

The language servers komrad runs over checkouts.

hooks

The hooks and scripts komrad runs.

panel

The panel.

leftover_agent_processes

The processes left running by archived agents.

unattributed

What komrad's cgroup holds outside the cgroups of its parts and its agents, such as what the server held before komrad split its cgroup.

CandidateRule#

CandidateRule is the rule that places an agent in the candidate list. The rules run from the agent komrad makes dormant first to the one it makes dormant last.

ValueDescription
released_reviewer

A reviewer whose review is released, resting.

merged_task

An agent on a task whose pull requests have all merged or closed, resting.

resting

An agent resting without unread mail.

resting_with_mail

An agent resting with unread mail.

waiting

An agent waiting on the person, off screen.

working

An agent working, or whose pane reads as uncertain, off screen.

working_orchestrator

An orchestrator working or holding unread mail, off screen.

in_use

An agent whose pane holds a draft or is on screen.