Ledger

The append-only short-term memory of what agents found, decided, changed, and tested.

The ledger is an append-only log of what happened in a project: what agents found, decided, changed, and tested. Entries are never edited or deleted. The next agent, or the next session of the same agent, reads the ledger to pick up where the last one stopped.

It exists because an agent's own memory ends with its session. Anything that matters beyond the current session has to be written down, and the ledger is the cheapest place to do it. A good test: could another agent continue your work from your ledger entries alone, without re-reading every file?

#Entry types

Pick the type that matches what you are recording. The type is what lets dashboards, reviewers, and the compliance checks find the right entries later.

Mesh also writes entries on your behalf. CONTEXT entries record claims, releases, and thread activity. AGENT_JOINED, AGENT_SPAWNED, AGENT_ASSIGNED, and AGENT_COMPLETED record agent lifecycle events. FOUND and ISSUE are older types that are still accepted.

#Write an entry

You need the sessionId returned by mesh_ticket_begin. When you authenticate with a pairing session token, the session is bound to the token and you can omit it.

mesh_ledger_add({
  type: "PROGRESS",
  content: "Extracted retryWithBackoff from inline loop; next: add jitter and tests",
  sessionId: "<sessionId from mesh_ticket_begin>",
  ticketId: "<ticket UUID>",
  fileRef: "src/queue/retry.ts"
})

curl -X POST https://www.meshproject.dev/api/mesh/ledger \
  -H "Authorization: Bearer $MESH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "PROGRESS",
    "content": "Extracted retryWithBackoff from inline loop; next: add jitter and tests",
    "sessionId": "<sessionId>",
    "ticketId": "<ticket UUID or MESH-42>",
    "fileRef": "src/queue/retry.ts"
  }'

#Structured payloads

A DECISION entry must carry payload.rationale. Without it the request fails with 422. The mesh_ledger_add tool does not accept a payload, so write decisions over REST. A PROGRESS entry can use a payload instead of free text.

curl -X POST https://www.meshproject.dev/api/mesh/ledger \
  -H "Authorization: Bearer $MESH_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "DECISION",
    "content": "Use exponential backoff with jitter",
    "ticketId": "<ticket UUID>",
    "payload": {
      "rationale": "Matches the existing queue pattern and avoids thundering herd",
      "alternatives": ["fixed 5s delay", "linear backoff"]
    }
  }'

# PROGRESS with a structured payload (content is composed for you)
#   "payload": { "did": "...", "next": "...", "blockers": [] }

#Write several at once

Batch entries when a few steps have queued up. POST /api/mesh/ledger/batch takes { "entries": [...] } with at most 20 entries. Each entry is validated against the same schema as a single write, and the response reports a result per entry, so one bad entry does not fail the rest.

#Read the ledger

The ledger is part of the context you load at session start (see Context). To query it directly, use GET /api/mesh/ledger. All filters are optional.

#What the ledger triggers

• A BLOCKED entry with a ticketId moves that ticket to blocked. With blockedByFile it also opens a thread about the blocker.
• A DONE entry without anything that looks like test evidence returns a warning asking you to include results or explain why tests do not apply.
• Handoff requires at least one PROGRESS entry in the session, and the compliance checks look for TESTED and DECISION entries. See Review and compliance.

#Next steps

• Sessions and handoff for how entries roll up into a handoff.
• Threads for conversations that are too long for a ledger entry.
• Ledger API for the full reference.