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 '{}'komrad rpc get-memory-use{
"name": "get_memory_use",
"arguments": {}
}Offered by the komrad MCP server to writer, reviewer, orchestrator agents.
Request#
Empty#
No fields.
Response#
GetMemoryUseResponse#
| Field | Type | Description |
|---|---|---|
limit_bytes | int64 | The memory limit. Zero when no limit is set. |
total_bytes | int64 | What komrad and its agents cost in the latest sample. |
projected_bytes | int64 | The total plus what agents launched or resumed in the last 30 seconds are still expected to grow by. |
margin_bytes | int64 | How far under the limit komrad goes when it makes agents dormant. |
sampled_at | timestamp | When komrad took the sample. |
owners | MemoryOwner[] | Every owner in the sample. |
made_dormant | DormantAgent[] | The agents komrad made dormant since midnight, newest first. |
to_resume | ResumeListEntry[] | The agents on the resume list, which komrad resumes once there is room again, the next to resume first. |
today | MemorySummary | What komrad and its agents cost across today's samples. Unset before the first sample. |
reasons | SampleReason[] | What the latest sample couldn't read. Empty when it read everything. |
incomplete_since | timestamp | When the run of blind or incomplete samples began. Unset when the latest sample is complete. |
is_warned | bool | Whether that run has lasted thirty seconds, long enough for komrad to warn. |
source | MemorySource | How komrad counts memory this run. |
scanner_reason | string | Why komrad counts memory with the process scanner. Empty under cgroups. |
pressure | LimitPressure | How close the latest sample stands to the memory limit, with |
Types#
MemoryOwner#
MemoryOwner is an agent or a part of komrad's own share, with the processes that count toward it.
| Field | Type | Description |
|---|---|---|
| one of | Who the processes count toward. | |
part | KomradPart | The part of komrad's own share. |
agent | AgentOwner | The agent. |
footprint_bytes | int64 | What the owner's processes cost together. |
processes | Process[] | The processes that count toward the owner, largest first. |
DormantAgent#
DormantAgent is an agent komrad made dormant to keep under the memory limit.
| Field | Type | Description |
|---|---|---|
agent_id | string | The agent's id. |
name | string | The agent's name. |
rule | CandidateRule | The rule that put the agent at the top of the candidate list. |
freed_bytes | int64 | What the agent's processes cost when komrad closed its pane. |
made_dormant_at | timestamp | When komrad made the agent dormant. |
ResumeListEntry#
ResumeListEntry is a dormant agent waiting on the resume list for room under the memory limit.
| Field | Type | Description |
|---|---|---|
agent_id | string | The agent's id. |
name | string | The agent's name. |
expected_cost_bytes | int64 | What komrad expects the agent to cost once it is resumed. |
listed_at | timestamp | When the agent went on the resume list. |
has_unread_mail | bool | 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.
| Field | Type | Description |
|---|---|---|
since | timestamp | When the first sample counted was taken. |
peak | MemorySample | The sample with the highest total. |
low | MemorySample | The sample with the lowest total. |
average_bytes | int64 | The average total across the samples. |
programs | ProgramSummary[] | Every program counted, the most held on average first. |
largest | ProcessPeak[] | The processes that held the most at once, the most first, five at most. |
AgentOwner#
AgentOwner is an agent that processes count toward.
| Field | Type | Description |
|---|---|---|
agent_id | string | The agent's id. |
name | string | The agent's name. |
candidate | Candidate | The agent's place in the candidate list. Unset while the agent is setting up, and on a process peak. |
resting_footprint_bytes | int64 | 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_bytes | int64 | The highest the agent held in the last ten minutes. |
Process#
Process is one process komrad counts toward its memory use.
| Field | Type | Description |
|---|---|---|
pid | int32 | The process's id. |
command | string | The process's command name, such as |
cost_bytes | int64 | What the process costs, with shared memory split between the processes that map it. |
corrected_at | timestamp | When komrad last split the process's shared memory. |
parent_pid | int32 | 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.
| Field | Type | Description |
|---|---|---|
sampled_at | timestamp | When komrad took the sample. |
bytes | int64 | What it cost at that sample. |
ProgramSummary#
ProgramSummary is what one program's processes held together across a day's samples.
| Field | Type | Description |
|---|---|---|
program | string | The program, such as |
average_bytes | int64 | What the program's processes held together on average across the samples. |
peak | MemorySample | The sample where the program's processes held the most together. |
seen | int32 | How many of the program's processes komrad saw, each counted once. |
ProcessPeak#
ProcessPeak is one process at the most it held at once.
| Field | Type | Description |
|---|---|---|
program | string | The program the process runs, such as |
peak | MemorySample | When the process held the most, and what it held then. |
| one of | Who the process counted toward then. | |
part | KomradPart | The part of komrad's own share. |
agent | AgentOwner | The agent, with the name it had then. |
pid | int32 | The process's id. |
Candidate#
Candidate is an agent's place in the candidate list.
| Field | Type | Description |
|---|---|---|
place | int32 | Where the agent stands in the list, from 1 for the agent komrad makes dormant first. |
rule | CandidateRule | The rule that put the agent there. |
quiet_since | timestamp | 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.
| Value | Description |
|---|---|
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.
LimitPressure#
LimitPressure is how close komrad stands to a memory or storage limit.
KomradPart#
KomradPart is one part of komrad's own share of memory.
| Value | Description |
|---|---|
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.
| Value | Description |
|---|---|
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. |