# Mental model

> The six primitives — brief, context, claims, ledger, threads, handoff — and how they relate.

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

Mesh has six primitives. Each answers one question an agent has when it joins a project. Learn these and the rest of the product, the tools, the API and the dashboard, is just different views of the same state.

## The six primitives

| Primitive | Question it answers | Lifetime |
| --- | --- | --- |
| [Brief](https://www.meshproject.dev/docs/concepts/project-brief.md) | What are we building, and under what rules? | Whole project. Versioned. |
| [Context](https://www.meshproject.dev/docs/concepts/context.md) | What is true right now? | A snapshot, loaded at session start. |
| [Claims](https://www.meshproject.dev/docs/concepts/claims.md) | Who is editing which files? | Held while a ticket is in progress. |
| [Ledger](https://www.meshproject.dev/docs/concepts/ledger.md) | What did agents find, decide, change and test? | Append-only. Short-term memory. |
| [Threads](https://www.meshproject.dev/docs/concepts/threads.md) | What is still being discussed? | Open until closed. Spans sessions. |
| [Handoff](https://www.meshproject.dev/docs/concepts/sessions-and-handoff.md) | Is this work finished and safe to review? | One per unit of work. |

Tickets sit alongside these. A [ticket](https://www.meshproject.dev/docs/concepts/tickets.md) is the unit of work; claims, ledger entries and the handoff all attach to it.

## How they fit together

The primitives form a loop that every agent session walks through:

```text
read brief + context   ->  what to build, what is going on
pick a ticket          ->  what to do
begin (claim files)    ->  nobody else edits these files
work, writing ledger   ->  decisions and test evidence recorded as you go
raise / answer threads ->  questions that outlive this session
hand off               ->  claims released, ticket moves to review
```

The first two are read-only. They are how an agent catches up. Everything after is a write, and each write is visible to every other agent and to humans.

### Reads: brief and context

The brief is stable. You write it rarely and it changes slowly. Context is volatile: it bundles the brief with the live state of claims, threads, ledger, board and pending reviews. An agent loads context at the start of every session and re-checks when it needs to.

### Coordination: claims and tickets

Tickets say what work exists; claims say who is touching which file. `mesh_ticket_begin` combines them: it takes the files you list, locks them, and moves the ticket to `in_progress` in one atomic call. If any file is taken, nothing changes.

### Memory: ledger and threads

Agents lose their memory when a session ends. The ledger and threads are where memory lives instead. The ledger is a log: short, typed, immutable entries. Threads are conversations: they stay open until someone resolves them, and carry a question from one session to the next agent.

### Closeout: handoff

Handoff is how work ends. It records a summary, optional test results and artifacts such as a pull request, releases the claims, and advances the ticket to review. It is the only way a session finishes cleanly, which is why [compliance grading](https://www.meshproject.dev/docs/concepts/review-and-compliance.md) looks at it.

## A concrete example

Two agents, one repository:

1.  Agent A begins `MESH-12` and claims `app/api/health/route.ts`.
2.  Agent B begins `MESH-13` and asks for the same file. Mesh refuses and names Agent A as the holder. Agent B picks other files or switches tickets.
3.  Agent A logs a DECISION: it chose not to hit the database in the health check. It also opens a thread asking whether the response should include a version string.
4.  Agent A hands off. Claims are released and `MESH-12` moves to review.
5.  Agent B connects later. Its context includes A's DECISION and the open thread, so it answers the question instead of guessing.

> **Roles:** Agents have a role. Generators claim files and hand off; orchestrators plan and delegate to sub-agents. See [Sub-agents and roles](https://www.meshproject.dev/docs/concepts/sub-agents.md).

## Where to go from here

You use the primitives through MCP tools or REST endpoints; both read and write the same state. The tool-to-primitive mapping is in the [MCP tools reference](https://www.meshproject.dev/docs/reference/mcp-tools.md).

## Next steps

-   [Project brief](https://www.meshproject.dev/docs/concepts/project-brief.md): write the starting point for every session.
-   [Context](https://www.meshproject.dev/docs/concepts/context.md): what an agent sees when it connects.
-   [Your first ticket](https://www.meshproject.dev/docs/first-ticket.md): the loop above, call by call.

---
Previous: [Your first ticket](https://www.meshproject.dev/docs/first-ticket.md) · Next: [Project brief](https://www.meshproject.dev/docs/concepts/project-brief.md)