●ctx0.1.0

Agents

Agents meet ctx three ways: the keys that matter to them arrive in their system prompt, tools let them read, write and search the store, and subscriptions bring them changes as messages, waking them when they are idle.

Where things go

The store enforces no layout, so agents share one. These prefixes are what the default preload reads and what the agent skill teaches.

PrefixHolds
global.*Fleet-wide facts everyone should know. Keep it tiny: it is in every prompt.
project.<repo>.*Per-repository state: status, decisions, conventions, open questions. <repo> is the checkout's directory name.
machine.<node>.*Per-host facts: services, quirks, maintenance. <node> is the short host name.
agent.<id>.*An agent's own working state, readable by everyone else.
flow.<name>.*State machines: .state, .log, inputs and outputs.
user.*The operator's preferences and standing instructions.

Invent sub-keys freely, but extend an existing subtree before starting a new one.

Context in the prompt

When a session starts, the Pi plugin or the pi-daemon module runs ctx prompt for it and puts the result in the ctx section of its system prompt. The keys come from pi.keys, with placeholders filled in for that session.

From pi.keys to a system promptLeft: the default pi.keys templates global, project.{project}, machine.{machine} and agent.{agent}. Middle: the placeholders filled in for a session: project from the git repository or directory of its working directory, lighthouse; machine from CTX_MACHINE or the host name, atlas; agent from CTX_AGENT or CACO_AGENT_ID, wren. A key whose placeholder is unknown is skipped. Right: ctx prompt reads those subtrees, drops entries older than 30 days, marks those older than 7 days stale, keeps the whole under 8000 bytes and renders Markdown that becomes the ctx section of the agent's system prompt, refreshed every 10 minutes. PI.KEYS FILLED IN FOR THIS SESSION SYSTEM PROMPT global global project.{project} project.lighthouse git repo of the cwd machine.{machine} machine.atlas CTX_MACHINE or host agent.{agent} agent.wren CTX_AGENT, CACO_AGENT_ID ## ctx: global (1 entry) - global.freeze (ci) ## ctx: project.lighthouse - …conventions (heron) - …decisions (heron) - …status (wren) ## ctx: machine.atlas - …quirks (heron) ## ctx: agent.wren - …task (wren) the ctx section ≤ 30 days old · stale after 7 days · ≤ 8000 bytes, oldest dropped first · refreshed every 10 minutes
The preload.One agent's view of the store, sized for a prompt. A placeholder that cannot be filled skips its key.

Run it yourself to see exactly what an agent will get. This is wren's preload in the lighthouse checkout on atlas:

CTX_AGENT=wren ctx prompt# Shared context (ctx)Live entries from the fleet's ctx store. Read more with ctx_get/ctx_search; record durable facts and state with ctx_set/ctx_update.## ctx: global (1 entry)- `global.freeze` (46s ago, ci): false## ctx: project.lighthouse (3 entries)- `project.lighthouse.conventions` (46s ago, heron): "Tests: cargo nextest; never commit generated fixtures"- `project.lighthouse.decisions` (46s ago, heron): [{"what":"Retry ingest twice, then fail the batch","by":"heron"}]- `project.lighthouse.status` (46s ago, wren): {"state":"review","pr":31,"branch":"wren/flaky-ingest"}## ctx: machine.atlas (1 entry)- `machine.atlas.quirks` (46s ago, heron): "Nix builds capped at 8 jobs; /scratch is wiped nightly"## ctx: agent.wren (1 entry)- `agent.wren.task` (46s ago, wren): {"bead":"bd-41c2","doing":"fix flaky ingest test"}

The preload is read again when it is more than ten minutes old, before the agent's next turn; /ctx refresh reads it now. ctx prompt --key and the pi settings change what is read and how much: see the configuration reference.

Tools

ctx mcp stdio is an MCP server for any agent harness. Its tool descriptions carry the conventions above, so agents use the store well without extra instructions.

ToolFor
ctx_getA key and its subtree as one tree; max_age, stale_after, max_bytes, rev, meta.
ctx_listWhat exists below a prefix, with counts, ages and writers.
ctx_searchContext whose key you do not know, by keyword or meaning.
ctx_set, ctx_update, ctx_append, ctx_deleteWrites, each with an optional if_rev.
ctx_batchSeveral writes, all or none.
ctx_history, ctx_changesA key's past versions; changes after a revision, for polling.
ctx_promptThe preload text a Pi session would receive.
ctx_guideThe full agent guide, for agents adopting ctx in a new workflow.
ctx_statusHead revision, counts, size and watchers.

The server also exposes the configuration tools every ctx config command has. The agent skill in the repository, skills/ctx/SKILL.md (also ctx guide), teaches the same conventions to agents that load skills.

Subscriptions wake agents

An agent can follow a pattern instead of polling. ctx_subscribe takes the pattern, an optional delivery and an optional since_rev; from then on, matching changes made by anyone arrive as a message.

A subscription wakes an idle agentA sequence with four lifelines: agent heron, the ctx plugin in heron's session, the ctx daemon, and a CI job. Heron calls ctx_subscribe with the pattern flow.deploy.**; the plugin starts a watch on the daemon from the current revision, with previous values. Heron finishes its turn and goes idle. The CI job sets flow.deploy.state three times; the daemon streams each change to the plugin, which collects them for one and a half seconds and delivers one message listing all three. Because heron was idle, the message starts a new turn; a busy agent would get it after its turn, or at once as steering. agent heron ctx plugin ctx daemon CI job subscribe flow.deploy.** watch --with-prev turn ends, idle "building" "deploying" "done" rev 14, 15, 16 + prev collect 1.5 s one message: new turn
A subscription.The plugin follows the pattern with an ordinary watch, so it resumes from its last revision after any interruption.
[ctx] 3 changes to `flow.deploy.**`:- rev 14 `flow.deploy.state` set by ci: "building"- rev 15 `flow.deploy.state` set by ci: "deploying" (was "building")- rev 16 `flow.deploy.state` set by ci: "done" (was "deploying")(From your ctx subscription to `flow.deploy.**`, now at rev 16. It stays active for later changes; keep it unless you no longer need these updates.)
DeliveryThe agent is idleThe agent is working
follow-up (default)The message starts a new turn: the agent wakes.The message waits until the current turn ends.
steerThe message starts a new turn.The message interrupts the turn.

In Pi

The repository is a Pi package. Add git:github.com/harryaskham/ctx to Pi's packages and every session gets the preload, the three subscription tools and the /ctx command. It drives the ctx binary on PATH (or CTX_BIN), so configuration, transport and semantics stay in one place.

CommandDoes
/ctxHead revision and entry count, what the preload holds, and how many subscriptions are active.
/ctx refreshReads the preload again.
/ctx get KEYShows a key's value.

In pi-daemon

For pi-daemon sessions, add the module the Nix package ships at share/ctx/pi/pi-daemon/ctx.mjs to a profile's extensions, alongside the MCP server for the tools.

Good citizenship

Everything is shared and nothing expires, so the store stays useful only if writers keep it tidy.