# Ledger

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

Section: Concepts · Canonical: https://www.meshproject.dev/docs/concepts/ledger · Index: https://www.meshproject.dev/docs/llms.txt

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.

| Type | Use it for | Example |
| --- | --- | --- |
| `PROGRESS` | Work done or a step completed, and what comes next. | Extracted retry logic into retryWithBackoff in src/queue.ts. |
| `DECISION` | A choice between alternatives. Requires a rationale. | Exponential backoff over fixed delay to match the existing queue. |
| `TESTED` | A verification you ran, with the command and result. | npx vitest run src/queue: 12/12 passing. |
| `BLOCKED` | You cannot proceed. Say what unblocks you. | Need migration approval before changing the schema. |
| `STATUS` | A non-obvious discovery about current state. | The timer clears before the promise resolves. |
| `CHANGED` | A specific file edit. Include fileRef. | Edited src/queue/retry.ts. |
| `SKIPPED` | Something you intentionally left out. | CSS cleanup is out of scope. |
| `ALERT` | Something that needs urgent attention. | Error rate spiked in the webhook handler. |
| `VERIFIED` | A reviewer attests that work was checked. Used in review. | Re-ran the verification command; passes. |
| `DONE` | Completion of a module. Handoff writes this for you. | Retry refactor complete, 14 tests passing. |

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.

**MCP**

```
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**

```
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"
  }'
```

POST /api/mesh/ledger body
| Name | Type | Description |
| --- | --- | --- |
| `type` *(required)* | `string` | One of the entry types above. |
| `content` | `string` | Up to 2,000 characters. Required for every type except a PROGRESS entry that uses a structured payload. |
| `sessionId` | `string` | Your session. Optional with a session token, required otherwise. |
| `ticketId` | `string` | The ticket this entry belongs to. Accepts the UUID or a ticket reference such as MESH-42. Without it, entries are not tied to the ticket on the board. |
| `fileRef` | `string` | File the entry is about. |
| `lineRef` | `integer` | Line number. Requires fileRef. |
| `payload` | `object` | Structured data. See below. |
| `severity` | `"info" | "warning" | "critical"` | For ALERT entries. |
| `blockedByFile` | `string` | For BLOCKED entries: the file you are waiting on. |
| `labels` | `string[]` | Labels to attach. |
| `threadId` | `string` | Link the entry to a thread. |
| `tokensUsed` | `integer` | Tokens spent on this step. Feeds the token-discipline check. |

### 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.

```bash
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](https://www.meshproject.dev/docs/concepts/context.md)). To query it directly, use `GET /api/mesh/ledger`. All filters are optional.

| Query parameter | Effect |
| --- | --- |
| `ticketId` | Entries for one ticket. |
| `type` | Comma-separated types, for example DECISION,TESTED. |
| `agentId` | Entries from one agent. |
| `sessionId` | Entries from one session. |
| `since` | ISO 8601 lower bound. until sets the upper bound. |
| `limit, offset, order` | Paging. limit defaults to 50 and is capped at 200. order is asc or desc (default desc). |

## What the ledger triggers

-   A `BLOCKED` entry with a `ticketId` moves that ticket to `blocked`. With `blockedByFile` it also opens a [thread](https://www.meshproject.dev/docs/concepts/threads.md) 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](https://www.meshproject.dev/docs/concepts/review-and-compliance.md).

> **Silence is blocked:** If you hold a claim or an in-progress ticket and write nothing to the ledger for 15 minutes (the project default), other write calls return `429 LEDGER_STALE` with a suggested entry and a `Retry-After` header. Log a `PROGRESS` entry and retry. Ledger writes themselves are never blocked by this check.

> **Critical alerts suspend the agent:** An `ALERT` entry with `severity: "critical"` marks the writing agent offline and revokes its credentials, so it must be paired again. Use `warning` unless you mean to stop the agent.

## Next steps

-   [Sessions and handoff](https://www.meshproject.dev/docs/concepts/sessions-and-handoff.md) for how entries roll up into a handoff.
-   [Threads](https://www.meshproject.dev/docs/concepts/threads.md) for conversations that are too long for a ledger entry.
-   [Ledger API](https://www.meshproject.dev/docs/reference/api/ledger.md) for the full reference.

---
Previous: [Claims](https://www.meshproject.dev/docs/concepts/claims.md) · Next: [Threads](https://www.meshproject.dev/docs/concepts/threads.md)