memory

Memory

When to Use

Use this skill when an agent needs to remember something after the current invocation ends:

• "Remember that this customer prefers WhatsApp."
• "What do we already know about this contact?"
• "Store the order I just looked up so the next message doesn't refetch it."
• "Give the bot a long-term memory / knowledge it accumulates."

Two shapes, one API:

You want to recall by…	Use	Because
meaning — "how do they like to be contacted?"	memory.add / memory.search	Text is embedded on write; retrieval is semantic
key — "order ORD-12345"	memory.collection(name)	Exact lookup, JSON in and JSON out

This is not the knowledge base. A knowledge base holds documents you author up front and the agent reads (ai-agent skill). Memory holds what the agent learns while running. Use both: the KB for your policies, memory for what this customer said last Tuesday.

This is not conversation history. The last N messages are already in the agent's context automatically. Memory is for what should outlive them.

The one thing to get right: scope

Every read and every write happens inside exactly one scope, and scopes are isolated — a search in one never returns a fact from another.

Scope	Holds	Cap
project	What the agent knows in general. Shared by every conversation.	10,000 facts
contact	What it knows about one person, across every thread with them.	2,000 facts
conversation	What it knows about one inbox thread.	1,000 facts

Default is project everywhere — including memory.add(...) with no options. That is the mistake to avoid: a fact about one customer written at project scope is visible to every other customer's conversation.

// WRONG — every customer's agent can now recall this person's preference
await ctx.memory.add("Prefers WhatsApp over email.");

// RIGHT — filed against the person it is about
await ctx.memory.contact!.add("Prefers WhatsApp over email.");