Overview

Cushion is a documentation library whose first reader is an agent. Keep your specs, ADRs, runbooks, meeting notes and glossaries in one place: your team gets a notification when something changes, and an agent reads and writes only the piece it needs over MCP.

The point is to stop burning tokens re-loading the same document in every session.

Why it exists

The usual way to let an agent read a spec is to drop the whole file into its context. But a single task usually needs one section, and the next session loads that same document from scratch again. The bigger the document, the more this cost scales with the number of tasks.

Cushion turns that into one outline, then one section at a time. The outline is fetched once per session, so the gap widens as tasks pile up.

Measured against Cushion's own docs. Compared with loading every document in full, that is under 20% of the tokens — more than a 5× saving.

The thing being measured is this project's own documentation, so the number moves as the docs grow. pnpm acceptance re-measures it each time.

How it works

PersonWeb editorAgentdoc_get · doc_putCushiondocumentssource of truthdocument_versionshistory · append-onlysync_eventschange summaryTeam channelMattermost · DiscordAgent (next call)[stale] → deltaeditMCP read/writenotifyone [stale] line

The source of truth lives here. The web editor and an agent's doc_put edit the same document, and either way you get a version in the history and a change summary.

One and the same summary feeds both the team channel notification and the agent's [stale] delta.

There is history, which keeps the previous body before anything is overwritten; concurrent-edit protection, which hands you a sha when you read and rejects the write if it no longer matches; and export, which is the only backup. Usage covers all three.

Three properties

In one place
Every change lands in the history and can be restored — deletions included.
A piece at a time
Read the outline first, then pull only the ## section you need. Ask again for a document that has not changed and you get the single word unchanged instead of the body.
Only when you are behind
No polling, no standing connection. When a document changes, one [stale] line is appended to the next tool response, and the team channel gets a notification saying what changed and why.

What it deliberately leaves out

These were rejected, not forgotten. The reasoning is in the decision log.

  • LLM-written change summaries: a summarizing model only sees the prose, so “which code does this affect” becomes a guess. Instead we build a structural summary out of the path, the sections and the line delta
  • Auto-merge and a conflict-resolution UI: there are no branches, so there is nothing to merge against. A mismatched base_sha is simply rejected
  • Embeddings and a vector database: at a scale of a few dozen specs, substring scoring is enough
  • Polling and always-on subscriptions: replaced by a cursor and one [stale] line on the response