Agent Mesh working memory

Agent Mesh is the coordination layer for multi-agent work. In plain terms: it is how agents remember what they are doing, avoid overwriting each other, and resume work after a context reset.

Working memory is one part of that layer. It stores the current plan, checkpoint, handoff note, and lease state outside the model context window.

Ships behind a flag

The working-memory feature is opt-in and ships behind MESH_DATABASE_URL (managed Postgres). The tools described here (mesh_task_checkpoint, mesh_task_plan_set, mesh_task_step_update, mesh_task_resume, and the lease resume_note enrichment) land via the skill-plugin PR and are not yet live on the default mcp.passo.build deployment. Discover the live catalog with tools/list.

What it is

The Agent Mesh is passo.build's shared coordination layer: a backing store exposed as mesh_* MCP tools where agents claim tasks, hold leases, and read project context. Working memory is the part of that store that holds a coding agent's live work state — what it is doing, what it has decided, and what comes next — outside the model's context window.

Instead of carrying its plan and progress inside the conversation (where it is fragile), the agent writes a small, rewritable record to the mesh and reads it back when it needs to. The context window stops being the agent's memory; the mesh is.

Why it exists

The feature is a direct response to a well-known failure mode of coding agents: they do not reliably close a non-trivial loop on their own. The root causes are all the same underlying problem — the working state lives in the context window, and the context window is the bottleneck.

• The context window is the real constraint. Working on a subtask, the agent loses the bigger picture. It is a context-window problem before it is a reasoning problem.
• Harness compaction is unreliable. The agent does not automatically keep a document that serves as memory of the workflow — what it is doing and what it still needs to do — unless explicitly told to. And when it does, compaction behaves badly: sometimes it grows the summary instead of compacting it, so the turn after compaction the agent re-reads everything.
• It needs human steering and decomposition. Left alone, the agent struggles; it needs a plan broken into ordered steps to follow.
• The durable human value is organization and convergence. The human's job is to give the agents structure while they work and steer them toward a technologically better solution.
• It produces unnecessary complexity. Without a convergence check, output drifts toward over-engineered solutions.

Every one of these is a working-memory and coordination problem that should live outside the context window. The mesh is the right place for it: it becomes the external working memory that is compaction-proof, plus the persisted steering that a single agent — or a team of agents sharing the mesh — otherwise lacks.

Why this matters

When the workflow state is not in the context window, compaction can no longer destroy it. The agent can be compacted, restarted, or replaced mid-task and still pick up exactly where the work was, because the plan, the current checkpoint, and the decisions already made are durable in the mesh. The steering a human would otherwise repeat to every agent is written once and reused. And handoff between agents becomes informed rather than blind.

How a coding agent uses it

The working-memory surface is four tools plus an enrichment on the lease/lock handoff. The design principle throughout is compact: a checkpoint is a few lines, not a second log.

mesh_task_checkpoint — the compact working state

The agent writes a small, rewritable snapshot of its current work state. This is the "automatic workflow memory" that the critique says is missing — except the agent maintains it deliberately, in a few lines, every turn.

{
  "taskId": "TASK-123",
  "currentStep": "wiring the Postgres store behind MESH_DATABASE_URL",
  "done": ["schema migration", "config flag"],
  "next": ["port upsert to ON CONFLICT", "hermetic tests"],
  "decisions": ["use advisory locks for claim atomicity (no single-writer)"],
  "openQuestions": ["does the MCP SG already reach RDS?"],
  "fenceToken": 42
}

• It is an upsert: one current checkpoint per task, rewritten — not an append-only log. That keeps it small by construction (the antidote to "it grows the summary instead of compacting it").
• It is validated against the lease's fence token, so a stale agent (one that was compacted or whose lease expired) cannot overwrite fresh state.
• decisions records key choices and why, so a resumed agent does not re-derive them.

Keep entries short: a one-sentence currentStep, brief lists. The tool is for the compact state of work, not a transcript — the mesh already has an append-only event stream for audit.

mesh_task_plan_set / mesh_task_step_update — persisted steering

The step-by-step decomposition a human would otherwise repeat to each agent is written once and persisted on the task, where any agent on the mesh can read and resume it.

// mesh_task_plan_set
{
  "taskId": "TASK-123",
  "steps": [
    { "text": "Add schema migration", "acceptance": "tables created idempotently" },
    { "text": "Wire store behind flag", "acceptance": "no-op when flag unset" },
    { "text": "Hermetic tests", "acceptance": "green with in-memory pg" }
  ]
}

// mesh_task_step_update
{ "stepId": 2, "status": "DOING" }

Each step carries an acceptance criterion (its definition of done) and a status (TODO / DOING / DONE / SKIP). The plan survives compaction and is shared, so steering becomes a reusable asset instead of something re-typed every session.

mesh_task_resume — minimal rehydrate, not re-read everything

After a compaction or a fresh claim, an agent calls one tool to rehydrate instead of re-ingesting the whole context. It returns a minimal bundle:

{
  "title": "Mesh Postgres working memory",
  "plan": [ { "text": "...", "status": "DOING" } ],
  "checkpoint": {
    "currentStep": "...",
    "done": ["..."],
    "next": ["..."],
    "decisions": ["..."],
    "openQuestions": ["..."]
  },
  "deps": ["unresolved-dep-ids"],
  "resumeNote": "left mid-test; pg-mem fixture needs the jsonb cast",
  "gates": { }
}

This is the direct fix for "the turn after compaction it re-reads everything." The agent pulls the plan, the current checkpoint, unresolved dependencies, and the prior holder's resume note — and continues, without re-reading the repository or the conversation history.

Informed handoff via lease resume_note

The mesh's leases and global locks carry a resume_note. An agent records, at heartbeat or on release, what it was doing. When a lease expires and another agent claims the task (mesh_task_claim / mesh_task_next / mesh_lock_acquire), that note comes back with the claim.

The classic failure — an agent dies or is compacted mid-task and the next one starts blind — is replaced by a handoff that reads the previous holder's resume_note plus the task checkpoint. The new agent knows where the work stood.

Usage walkthrough

A typical loop for an agent working a mesh task with working memory:

1. Claim the task (mesh_task_claim / mesh_task_next) and read the returned resume_note from any prior holder.
2. Rehydrate with mesh_task_resume — get the plan, checkpoint, deps, and gates in one call instead of re-reading everything.
3. If there is no plan yet, set one with mesh_task_plan_set; mark the active step DOING with mesh_task_step_update.
4. Work the step. Each turn, write a short mesh_task_checkpoint (currentStep, done, next, decisions) carrying the lease's fenceToken.
5. On heartbeat or release, leave a one-line resume_note so the next agent — or the next instance of you after compaction — is not blind.
6. Complete the task with evidence once the step acceptance criteria pass; the normal mesh evidence-and-approval gates still apply.

The result: the context window holds only what the agent needs right now, while the durable plan, decisions, and progress live in the mesh — compaction-proof, steerable, and shareable across the agent fleet.

Storage and rollout

• The mesh data store moves from SQLite to managed Postgres (dogfooding the PyxCloud "managed Postgres" thesis). The working-memory store activates via MESH_DATABASE_URL; the opt-in behavior is otherwise unchanged.
• Upserts use ON CONFLICT ... DO UPDATE; fence tokens come from a sequence; claim atomicity uses Postgres advisory locks / SELECT ... FOR UPDATE SKIP LOCKED rather than SQLite's single-writer guarantee.
• Tests are hermetic (in-memory Postgres), so no external database is required to run them.
• Rollout is gated. The working-memory tools land via the skill-plugin PR; the Postgres networking and secret wiring deploy via the existing pipelines under owner approval. Until then, treat this page as the design and target behavior, and rely on tools/list for what is live.