frogbot.memory.
memory is unset by default. Without it, FrogBot adds no memory collection and frogbot.memory calls fail with a message that names the fix.
Scopes
Every memory belongs to one scope. You name a scope with a word, and FrogBot works out which scope that is from the request, never from the caller’s input.
Declare your own words, or replace
team, with scopes. A function gets { req, agent, chat } and returns the value that tells one scope from another:
undefined, null or '' makes the word unavailable for that request, and a call that uses it fails with invalid, as does one that returns any other kind of value. So does a word you didn’t declare. me and agent can’t be replaced.
Set namespace when two apps share a database and use the same agent names, so their memories stay apart.
Use memories from server code
Every method also takes
scope, and these to say who the call runs as:
A memory is
{ id, scope, key?, text, pinned, createdAt, updatedAt }, where scope is the word it was saved under.
Access
FrogBot ships no access rules for shared memories. When a call setsoverrideAccess: false:
mealways works for the signed-in person, and only reaches their own memories. With nobody signed in, it fails withForbidden.agent,teamand your own words need theaccessfunction for the kind of call:readforsearch,listandget,writeforsave,updateandforget. Without one, the call fails withForbidden.
Agents
Setmemory: true on an agent to let it remember. It needs the root memory adapter; without one, startup fails and names the fix.
The tools take a scope word at most, never a scope ID, and FrogBot works out the scope from the run, as in Scopes. Without a scope,
memory_save and memory_forget use me for a signed-in person and agent otherwise. Agent runs skip access.read; use the agent’s access to limit who chats with it. When the app sets access.write, memory_save and memory_forget on a shared scope check it as the person in the chat, so a member can’t get around a team rule through chat, and a refused call returns Memory forbidden to the model. me always works for its owner. memory_search, memory_save and memory_forget are reserved tool slugs on these agents.
Change whether a tool asks first once, for every agent. A rule for one agent is a function that checks agent.slug:
- The agent’s instructions.
- A Memory section listing the scope words, then the pinned memories of every scope the run can use, up to 2,000 tokens. They’re ordered by scope, then by when they were saved, so the system prompt stays byte for byte the same, and cacheable, until a pinned memory changes.
- Up to 5 memories that aren’t pinned and match the latest message, as one message right before it. They’re never in the system prompt and never saved to the chat.
afterTurn, FrogBot calls it after each finished turn with the run’s scopes and the turn’s messages. The reply never waits for it, and a throw is logged.
Memory over MCP
memoryTools from frogbot/memory are the same three tools. List them in plugin-mcp’s tools to serve memory to MCP clients. MCP calls have no agent, so the agent scope fails there with invalid. They keep the MCP caller’s access check, so shared scopes follow Access and are refused until you set access (memory_search with no scope searches only the scopes the caller can read), and memory_forget can’t ask anyone, so it is refused unless you set its approval to false.
Use memories from the browser
The same six operations are served over REST at/api/frogbot/memory, and the SDK calls them as sdk.memory. They always run as the signed-in person with overrideAccess: false, so Access decides what each person reaches.
Each answers with what the server-side method returns. Errors come back as
{ errors: [{ message }] }: invalid is 400, not-found 404, limit 409, unavailable 503, and a refused call 403. Over REST, scope functions see the request but no chat.
When memory is on, Settings → Memory in the admin lists the signed-in person’s own me memories, newest first, and lets them forget any of them.
Errors
Adapters andfrogbot.memory throw MemoryAdapterError with one of these codes:
The database adapter
databaseMemory() stores memories in a hidden collection, frogbot-memories, in your own database.
It keeps memories tidy without AI:
- A save with a
keyupdates the scope’s memory with that key. - A save without one updates a near duplicate without a key instead of adding a memory: the same text once lowercased, stripped of punctuation and spaces collapsed, or text whose shared words make up at least 90% of all the distinct words in both texts. A memory with a key changes only through its key.
- Writes to one scope run one at a time in each server process, so the checks above and the cap hold under concurrent saves. Across several processes, a key or the same text still maps to one memory, but the cap can be passed by a few.
- Pinned memories in one scope may hold about 2,000 tokens, counted as characters divided by 4. A save or update past that fails with
limit.
Search
Search matches any word of the query, ranked by the database’s text search. WithembeddingModel, it also ranks by meaning, so “how should I contact them?” finds “the client prefers email”.
Plain MongoDB has no text search, so there
search matches each query word as a case-insensitive substring of a memory’s text and key, ignores one-letter words, and ranks every matching memory in the scope by how many words it matches. embeddingModel is ignored there.
Write an adapter
A memory adapter is an object with six methods. FrogBot resolves the scope and checks access before it calls one, so every method gets a checked{ req, namespace, scope, scopeId } and never a scope word it has to trust. Key memories by namespace and scopeId.
Throw
MemoryAdapterError from frogbot/memory with the code that fits.
Test an adapter
testMemoryAdapter() from frogbot/memory/testing runs the same cases against any adapter: a round trip through the six methods, upsert by key, scope and namespace isolation, not-found, and init and afterTurn when the adapter has them. It throws on the first case that fails. Pass a request from a FrogBot instance booted with the adapter, and a call for each other error code your adapter can produce: