Skip to content

Items and checkpoints

Items are the memory. Everything else (raw turns, presence) is context around them.

{ "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." }
  • kind is one of decision, gotcha, convention, fact, status, todo.
  • title is one line. It is what the next agent scans.
  • body is 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

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 status at 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).

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

Retract by id or a unique id prefix (the session-start inject shows prefixes):

meshpoint items retract 3f9c1a2b 7d0e44aa

Retraction is soft: the item leaves recall and the console’s default view, and stays visible under “show retracted”. Ambiguous prefixes are refused.

  • Retract, do not pile. A branch with three contradicting status items 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/auth do not show on master. 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.