Skip to docs content
Browse documentation
On this page

Shared memory

What a Minion memory is, why it lives on the account instead of in one host's chat, how memories surface automatically on search and execute, the verify-first rule for writes, and what does not belong in memory (package state, config, credentials). Load this when someone asks what their agents remember about them or how memory travels between agents.

A memory is a durable fact or preference attached to your Minion team. Say it once in one agent and every other agent connected to the same team can use it. That is the whole point: memory follows the person, not the product.

Facts saved only inside an app — Claude's memory, Codex notes, Cursor rules that are not also Minion memories — are invisible to your other agents. Minion is the system of record for the assistant state you want to keep.

What a memory is for

Memories hold information worth carrying between conversations and between agents:

  • who you are and how you like things done (preference, profile)
  • names, ids, and handles you keep re-typing (identifier)
  • people and relationships that give tasks context (relationship)
  • how a recurring piece of work should go (workflow, project)

Categories are freeform strings; those are suggestions, not a closed list.

What a memory is not for

Minion has a home for each kind of state, and memory is only one of them:

  • A durable fact or preference about you — Memory
  • A credential — Secrets
  • A cursor, checkpoint, or runtime knob — packageStorage() inside the package
  • A plan, research, or progress log — a note
  • Versioned configuration — the package itself
  • An OAuth login — An integration

If the fact is about a package's job rather than about you, it does not belong in memory.

How memories surface

Your agent does not have to ask for memories. When it calls search with a query, Minion retrieves the one or two most relevant active memories and adds them to the response as a memories list: subject and summary. execute does the same, using its code and params as the context. Weak matches stay out, and a search with no memories saved adds nothing.

That auto-surface is deliberately small. Details stay behind minion.memories.get. A different conversation, or a completely separate agent for the same team, sees the same list. That is portability in one screen.

Writing memory: verify first

Memory writes are explicit. Before creating, updating, or deleting a memory the agent should:

  1. call minion.memories.verify to see what already exists on the topic
  2. review the related memories it returns
  3. decide to upsert, delete, do both, or do nothing

Minion retrieves the related memories; the agent decides what they mean. Agents should say what they saved — the value of memory is that you can see it move.

Capabilities

All through execute:

  • minion.memories.verify — required first step before any write
  • minion.memories.upsert — create (no id) or update (with id, or a matching dedupeKey)
  • minion.memories.delete — soft-delete by default; force: true deletes for good
  • minion.memories.get — load one memory by id
  • minion.memories.search — browse or search stored memories directly

A memory has a subject (up to 200 characters), a summary (500), optional details (8 KB), a category, up to 20 tags, an optional dedupeKey, and a status of active, stale or archived. Memories can carry up to 12 sourceUris — canonical document URLs such as a GitHub file or a Notion page — so a later agent can go to the source.

Your copy

You can see and edit memories on the Memories page (/app/memories). Team owners can download everything the team owns as JSON from Team settings, or call minion.account.export. Credentials are left out.

Where to go next