Notes vs memories: where an agent's work should live

Say Claude Code is halfway through a billing migration when the session gets too long. It has a plan, a list of tables it has moved, and two open questions about refunds. You start a fresh session to carry on, and the new one has no idea what you're talking about.

The plan is in the old chat. So is the research, and the fact that you've told it twice you want small PRs. You spend twenty minutes pasting it back in. The agent isn't the problem. Where the work is kept is. When people ask for shared memory for AI agents, they're usually asking for two different things at once, and it helps to pull them apart.

Why chat history isn't shared memory for AI agents

Chat history feels like memory because everything is in there. But it's a transcript, not a store. You can't open it from another agent. You can't search it from Cursor when the conversation happened in Claude. The useful part is buried between forty tool calls and a stack trace, and when the context window fills up, the oldest stuff quietly falls off the front.

Some agents have their own memory features now, and they help inside that one app. Claude's memory, Cursor rules, a Codex notes file: each one is invisible to the others. If you use more than one agent, or you switch next year, you're back to pasting.

What's worth keeping from that billing session comes in two shapes:

• A few short facts that should be true in every conversation: you want small PRs, the billing service is the one in services/billing, Sam owns the Stripe webhook.
• One long working document: the plan, what's done, what's next, what you learned about refunds along the way.

Those want different homes. Minion has one for each.

Memories: short facts every agent can search

A memory in Minion is one durable fact or preference, a line or two long, stored on your team rather than inside an app. Say it once to one agent and every other connected agent can use it.

Writing one is deliberately a two-step thing. The agent checks what's already saved on the topic first, so you don't end up with five slightly different versions of the same preference:

const { related } = await minion.memories.verify({
  subject: 'PR size',
  summary: 'Prefers short PRs, one change each',
})
if (related.length === 0) {
  await minion.memories.upsert({
    subject: 'PR size',
    summary: 'Prefers short PRs, one change each',
    category: 'preference',
    dedupeKey: 'preference:pr-size',
  })
}

The part I like is that agents don't have to remember to look. When an agent calls Minion's search or execute, Minion pulls the one or two most relevant memories and attaches them to the response, subject and summary only. Weak matches stay out. So when Cursor goes to open a PR next week, "prefers short PRs" is just there, without anyone saying it again.

You can also see and edit every memory at /app/memories, which matters more than it sounds. Memory you can't inspect is memory you can't trust.

What doesn't belong in a memory: credentials (those are secrets), a job's cursor (that's package storage), and anything long. Plans, research and progress logs are notes.

Notes: where an agent's plan, research and handoffs live

A note is a markdown document of up to 64 KB with a title, tags and an optional key. That key is the bit that matters most. Instead of hunting for an id, an agent names the note something you could guess:

await minion.notes.upsert({
  key: 'plan:billing-migration',
  title: 'Billing migration plan',
  body: '## Steps\n- Export invoices\n- Import into new schema\n- Backfill refunds',
  tags: ['billing'],
})

// next week, in a different agent
const plan = await minion.notes.get({ key: 'plan:billing-migration' })

Any connected agent can search notes or open one by key, and your team can read and edit the same notes at /app/notes. That's the fix for the billing afternoon. The plan doesn't live in a chat. It lives in a note that Claude Code wrote and Codex can finish.

A few more things notes do that memories don't:

• Append for shared logs. notes.append adds a line atomically and creates the note if the key is new, so several agents, or every run of a nightly job, can write to one log without clobbering each other.
• Scratchpads that clean up. Give a note a ttlSeconds or expiresAt, up to 90 days out, and it deletes itself. Expired notes drop out of search. Good for the triage mess you'll never read again.
• Comments. People and agents can comment on a note without rewriting it. Leave "skip the refunds backfill until Sam replies" as a comment, and the next agent checks comments when it picks the plan up.
• History and undo. Every edit keeps the version it replaced, with who wrote it and which agent run. If an agent flattens a good plan with a worse one, notes.restore rolls it back. Owners and admins can purge old versions if something sensitive got pasted in.

await minion.notes.append({
  key: 'log:billing-migration',
  text: '- invoices table exported, 0 errors',
})

Agent handoff notes: picking up where the last session stopped

The case I care about most is the one this post started with: a long task that doesn't fit in one conversation. Before an agent stops mid-task, it leaves a handoff note. What's done, what's next, where things are.

await minion.notes.handoff({
  key: 'handoff:billing',
  title: 'Billing migration: halfway',
  body: '- Done: export\n- Next: import step, see plan:billing-migration',
})

When a new MCP session starts for your team, Minion's server instructions include a short pointer to the latest open handoff: its id, how old it is, whether an agent or a teammate wrote it, and the title. Not the body. The agent asks you before loading it, then closes it once it has picked the work up, so the session after that doesn't trip over a stale one.

Two small rules I'd keep. Never put a secret in a handoff; refer to secrets by name. And link the handoff to the plan by key instead of copying the plan into it. The handoff says where you are. The plan note says where you're going.

Notes or memories: a quick way to choose

When an agent is about to save something, I ask one question: will this still be true and useful in every conversation, or is it about a piece of work?

• "Sam owns the Stripe webhook." Memory.
• "We're moving invoices first because refunds depend on them." Note, inside the plan.
• "Prefers short PRs." Memory.
• "Import failed on row 4,812, retrying with a smaller batch." Note, appended to the log.
• "Here's where I stopped." Handoff note.

If it's one line and it's about the people or how the team works, it's a memory. If it has headings, steps or a date in it, it's a note. That's the whole rule, and it lines up with the comparison on the notes feature page .

None of this needs Minion to think for you. Minion makes zero inference calls. Your agent decides what's worth saving; Minion just keeps it somewhere every agent can reach. I wrote more about that idea in Your assistant's home , and the Shared memory docs cover the verify-first rule and how memories surface on their own.

Try it

Connect your agent, then give it one of each. Ask it to remember one preference you're tired of repeating, and to write the plan for whatever you're working on as a note with a key like plan:something. Then open a different agent and ask it what the plan is. If you haven't connected one yet, First steps walks you through it, and the Memory feature page shows how the two fit together. Or just create a free account .