Items and checkpoints
Items are the memory. Everything else (raw turns, presence) is context around them.
An item
Section titled “An item”{ "kind": "gotcha", "title": "Codex project hooks need file-based trust", "body": "Project .codex/ files load only once the repo is trusted in ~/.codex/config.toml. The -c trust_level override does not load them." }kindis one ofdecision,gotcha,convention,fact,status,todo.titleis one line. It is what the next agent scans.bodyis one to three sentences, concrete: file names, commands, values, reasons.
Each item also records provenance: which user, which agent, when. The console shows it; the agent sees the id.
| Kind | Use it for |
|---|---|
decision |
a choice made and why |
gotcha |
something that bit or will bite |
convention |
how things are done in this repository |
fact |
a stable truth about the code or environment |
status |
where the work stands (one at a time per branch) |
todo |
an agreed next step |
Checkpoints
Section titled “Checkpoints”A checkpoint is the moment an agent writes items for a branch. Harnesses nudge the agent to do it after 20 assistant replies or 60,000 characters of reply text since the later of the last checkpoint on the branch and the last nudge in the session. The nudge reads:
Meshpoint checkpoint due (20 replies since the last one). Run the meshpoint skill now, then continue.
Each harness delivers it in its own way (a blocked stop in Claude Code and Codex, an extra turn in pi, a follow-up prompt in opencode and Cursor, a bootstrap note in OpenClaw); see the harness pages. An ignored nudge is not repeated until the next twenty replies, so a user who declines is not pestered.
The meshpoint skill, installed next to the hooks, tells the agent what to do:
- Only what this session established. Never invent.
- Skip what is already listed under “Team knowledge” unless it changed; a changed decision or status gets a new item.
- Retract items the session made wrong or obsolete: a finished todo, a superseded status, a reversed decision.
- Prefer durable knowledge over moment-to-moment detail. Five to thirty items; one
statusat most. - No secrets, tokens or credentials.
Then one command:
meshpoint items put \ --item decision 'Short title' 'What was chosen and why, with file names and values.' \ --item gotcha 'Short title' 'What bit and how to avoid it.'Writing items records the checkpoint time for the branch, which resets the nudge counter for every session on it.
Why items and not a summary: in the benchmark behind this design, structured items restored a resumed session’s correctness at 0.67 against 0.60 for a free-form summary and 0.32 for a transcript tail (ceiling 0.82 with the full prefix).
By hand
Section titled “By hand”Anyone with the CLI can write items for the current repository and branch:
meshpoint items put --item fact 'CI runs on Node 22' 'The workflow pins node 22.x; local Node 20 fails the lint step with an ESM error.'meshpoint items put < items.json # a JSON array of {kind, title, body}meshpoint items put --file items.jsonRetract by id or a unique id prefix (the session-start inject shows prefixes):
meshpoint items retract 3f9c1a2b 7d0e44aaRetraction is soft: the item leaves recall and the console’s default view, and stays visible under “show retracted”. Ambiguous prefixes are refused.
Keeping memory useful
Section titled “Keeping memory useful”- Retract, do not pile. A branch with three contradicting
statusitems confuses the next agent. The skill retracts the old one; do the same by hand. - Say where. An item that names the file, flag or command is actionable; “the config is tricky” is not.
- Branches are separate. Items on
feature/authdo not show onmaster. When work merges, write the durable items on the target branch, or fork the branch’s memory from the console. - Budget. Recall fits about 3,000 tokens of items per session, newest and most confirmed first. Dozens of items are fine; hundreds of unretracted ones push the good ones out.
Credentials pasted into an item are masked before they leave the machine, the same as in captured turns. See Data and privacy.
