Skip to content

How it works

Meshpoint has a small vocabulary. Learn these terms once and every page in these docs reads the same way.

Organization. The account that owns everything: members, projects, billing. You get a personal organization at first sign-in. A team shares one. See Teams and organizations.

Project. One repository. Its id comes from the clone URL of the origin remote, flattened to host--owner--repo, so git@github.com:acme/web.git and https://github.com/acme/web are the same project github.com--acme--web. A directory without an origin remote is not a project and is ignored.

Branch. Memory is kept per git branch inside a project. A session on feature/auth recalls that branch’s items; master keeps its own. Branch names are taken from the checkout at session start.

Item. A short note about the repository written by an agent or a person. Six kinds: decision, gotcha, convention, fact, status, todo. Each item has a title, a one-to-three-sentence body, and provenance: which user, which agent, when. Items are the memory. See Items and checkpoints.

Raw turn. A prompt or a reply captured during a session, with the file paths the agent touched. Raw turns are not shown in the console or returned by any API route, and expire by plan. They are evidence, not memory; recall never includes them.

Capture. One request from an adapter carrying a batch of raw turns and, at a checkpoint, the checkpoint body. The console counts captures per hour on a project; one capture usually holds several turns.

Checkpoint. The moment an agent writes items for a branch. The time of the last checkpoint is shown to the next session and drives the nudge.

Recall. The ranked set of a branch’s items that fits a token budget (3,000 by default), delivered at session start. Served from the edge; can be up to a minute stale at a distant region.

Presence. Who is live on a branch right now: agent name, user, and the files touched in the last five minutes.

  1. Start. The harness runs the Meshpoint hook (or loads the plugin). It derives the project from origin and the branch from the checkout, fetches recall and presence, and injects both into the agent’s context: a “Team knowledge” list with item ids, the time of the last checkpoint, and the teammates active on the branch.
  2. Prompt. The user’s prompt is written to a local spool file as a [user] turn.
  3. Reply. When the agent stops, its reply is spooled as an [assistant] turn with the paths it edited. Credentials in either are masked before the write; see Data and privacy.
  4. Send. Once the oldest spooled turn is sixty seconds old, the spool is sent in one request. A session costs about one request a minute. A failed send keeps the spool for the next event.
  5. Nudge. After twenty replies, or 60k characters of reply text, since the later of the last checkpoint and the last nudge, the harness asks the agent once to run the meshpoint skill. The agent writes items with one command and continues. An ignored nudge is not repeated until the next twenty replies.
  6. End. Session end and context compaction send whatever is still spooled.

Every step fails open. A network error, an expired token, a missing login: the hook answers with nothing and the harness carries on.

The platform stores items, raw turns and presence per project, ranks each branch’s items into a recall blob, and serves that blob from the edge. It verifies bearer tokens signed with your organization’s key, enforces plan limits on growth, and runs no model. Distillation is the agent’s job, which is why the skill is installed next to the hooks.

On your machine On the platform
~/.config/meshpoint/config.json: login (mode 600) items, with provenance
~/.local/state/meshpoint/spool/: turns waiting to be sent raw turns, for the plan’s retention period
~/.local/state/meshpoint/checkpoints/ and nudges/: timestamps presence, five-minute expiry
the harness’s hook or plugin entry and the meshpoint skill organization, members, sessions, keys, billing ids