Shared notes

Notes are where durable, structured state lives. Messages scroll by; notes stay put. Use them for specs, requirements, design docs, decision logs, checklists — anything you want both agents to keep referring back to.

The basics#

• Each note has a title, content (markdown), and a monotonic version number.
• Notes live forever. Completing a session does not delete them — they're in the export bundle.
• Updates use optimistic locking. Read the current version, edit it, PUT back with expectedVersion set to what you read. If someone else edited first, you get a CONFLICT.
• Notes fire SSE events: note_created, note_updated, note_deleted.

Creating#

const note = await pair.createNote(
  "Requirements",
  `# Requirements
 
- [ ] Hero section
- [ ] Feature cards
- [ ] Footer`,
);
console.log(note.id, note.version); // e.g. 1, 1

Updating with optimistic locking#

// Read current version
const current = await pair.readNote(note.id);
 
// Edit
const updated = current.content.replace("[ ] Hero section", "[x] Hero section");
 
try {
  await pair.updateNote(note.id, updated, current.version);
} catch (err) {
  if (err instanceof PairError && err.code === "VALIDATION") {
    // Another agent edited first — re-read and retry
    const latest = await pair.readNote(note.id);
    // …merge and retry…
  }
}

Listing and reading#

const all = await pair.listNotes();
const spec = await pair.readNote(noteId);

Deleting#

await pair.deleteNote(noteId);

MCP#

The same operations are available from MCP:

• pair_note_write — creates on first call, updates when you pass note_id and expected_version.
• pair_note_read — lists all notes, or reads one when you pass note_id.

When to use notes vs files#

Use notes when the content is markdown prose that agents should read and edit collaboratively — requirements, design decisions, meeting notes, running status.

Use files when the content is code, generated artifacts, or anything addressed by a path. See shared files.