> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frogbot.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory

> Keep facts that people and agents save, by person, agent, team or your own scope.

Memory keeps short facts, such as "the client prefers email", so later work can use them. Turn it on once in your config with a memory adapter, then read and write memories with `frogbot.memory`.

```ts theme={"theme":"tokyo-night"}
import { buildConfig } from 'frogbot'
import { databaseMemory } from 'frogbot/memory'

export default buildConfig({
  // ...
  memory: databaseMemory(),
})
```

`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.

| Word | Means | Needs |
| - | - | - |
| `me` | The signed-in person, keyed by their user ID, never their email | A signed-in user |
| `agent` | One agent in this app | An agent slug |
| `team` | Everyone in the app | Nothing |
| Your own word | Whatever your scope function returns | Your function to return a value |

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:

```ts theme={"theme":"tokyo-night"}
memory: databaseMemory({
  scopes: {
    client: ({ chat }) => chat?.client?.id ?? chat?.client,
    team: ({ req }) => req.user?.company?.id ?? req.user?.company,
  },
}),
```

Return an ID, a string or a finite number, not a populated relationship. A function that returns `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

```ts theme={"theme":"tokyo-night"}
const memory = await frogbot.memory.save({
  scope: 'me',
  user: req.user,
  text: 'Prefers replies in Spanish',
  pinned: true,
})

const hits = await frogbot.memory.search({ scope: 'me', user: req.user, query: 'language' })

await frogbot.memory.forget({ scope: 'me', user: req.user, id: memory.id })
```

| Method | Does |
| - | - |
| `save({ text, key?, pinned? })` | Adds a memory of up to 4,000 characters. With a `key`, updates the scope's memory with that key instead. |
| `search({ query, limit? })` | Returns `{ memory, score }[]`, best first. `limit` is 1 to 100 and defaults to 10. |
| `list({ pinned?, limit?, page? })` | Returns `{ docs, hasNextPage }`, newest first. `limit` is 1 to 1,000 and defaults to 100. |
| `get({ id })` | Returns one memory in the scope. |
| `update({ id, text?, key?, pinned? })` | Changes one memory. `key: null` removes its key. |
| `forget({ id? })` | Removes one memory, or every memory in the scope without an `id`. Returns `{ deleted }`. |

Every method also takes `scope`, and these to say who the call runs as:

| Option | Type | Default | Description |
| - | - | - | - |
| `scope` | `string` | — | The scope word. |
| `agent` | `string` | — | The agent slug the `agent` scope and scope functions see. |
| `chat` | `Record<string, unknown>` | — | The chat document scope functions see. |
| `req` | `Partial<FrogBotRequest>` | — | The request to run in, for its user and transaction. |
| `user` | `TypedUser` | — | The user the `me` scope belongs to. Replaces the request's user. |
| `overrideAccess` | `boolean` | `true` | Skips `access`, like every server-side operation. |

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 sets `overrideAccess: false`:

* `me` always works for the signed-in person, and only reaches their own memories. With nobody signed in, it fails with `Forbidden`.
* `agent`, `team` and your own words need the `access` function for the kind of call: `read` for `search`, `list` and `get`, `write` for `save`, `update` and `forget`. Without one, the call fails with `Forbidden`.

```ts theme={"theme":"tokyo-night"}
memory: databaseMemory({
  access: {
    read: ({ req }) => Boolean(req.user),
    write: ({ req, scope }) => scope === 'team' && req.user?.role === 'admin',
  },
}),
```

## Agents

Set `memory: true` on an agent to let it remember. It needs the root `memory` adapter; without one, startup fails and names the fix.

```ts theme={"theme":"tokyo-night"}
agents: [{ slug: 'support', instructions: 'Help customers.', memory: true }],
memory: databaseMemory(),
```

The agent gets three tools:

| Tool | What it does | Asks first |
| - | - | - |
| `memory_search` | Searches one scope, or every scope it can use. | No |
| `memory_save` | Saves a memory, with an optional `key` and `pinned`. | No |
| `memory_forget` | Forgets one memory by ID. | Yes |

The tools take a scope word at most, never a scope ID, and FrogBot works out the scope from the run, as in [Scopes](#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`](https://docs.frogbot.ai/agents/overview#control-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`:

```ts theme={"theme":"tokyo-night"}
memory: databaseMemory({
  tools: {
    memory_save: { approval: 'required' },
    memory_forget: { approval: ({ agent }) => (agent.slug === 'admin' ? false : 'ask') },
  },
}),
```

Each turn's prompt is, in order:

1. The agent's instructions.
2. 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.
3. 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.

When the adapter has `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`](https://docs.frogbot.ai/plugins/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](#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`.

```ts theme={"theme":"tokyo-night"}
import { memoryTools } from 'frogbot/memory'

mcpPlugin({ tools: [...memoryTools] })
```

## 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](#access) decides what each person reaches.

```ts theme={"theme":"tokyo-night"}
const sdk = createFrogBotSDK({ baseURL: '/api' })

await sdk.memory.save({ scope: 'me', text: 'Prefers replies in Spanish', pinned: true })

const hits = await sdk.memory.search({ scope: 'me', query: 'language' })
```

| Request | SDK | Parameters |
| - | - | - |
| `POST /api/frogbot/memory` | `save` | JSON body: `scope`, `agent?`, `text`, `key?`, `pinned?` |
| `GET /api/frogbot/memory/search` | `search` | Query: `scope`, `agent?`, `query`, `limit?` |
| `GET /api/frogbot/memory` | `list` | Query: `scope`, `agent?`, `pinned?`, `limit?`, `page?` |
| `GET /api/frogbot/memory/:id` | `get` | Query: `scope`, `agent?` |
| `PATCH /api/frogbot/memory/:id` | `update` | JSON body: `scope`, `agent?`, `text?`, `key?`, `pinned?` |
| `DELETE /api/frogbot/memory/:id` | `forget` with `id` | Query: `scope`, `agent?` |
| `DELETE /api/frogbot/memory` | `forget` without `id` | Query: `scope`, `agent?` |

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 and `frogbot.memory` throw `MemoryAdapterError` with one of these codes:

| Code | When |
| - | - |
| `invalid` | The input is wrong, or the scope word isn't declared or has no value for the request. |
| `limit` | The scope is full, or pinned memories would pass their budget. |
| `not-found` | No memory has that ID in the scope. |
| `unavailable` | The backend or the embedding model failed. |

## The database adapter

`databaseMemory()` stores memories in a hidden collection, `frogbot-memories`, in your own database.

| Option | Type | Default | Description |
| - | - | - | - |
| `namespace` | `string` | `''` | Part of every memory's key, so apps that share a database keep their memories apart. |
| `scopes` | `Record<string, MemoryScope>` | — | Your own scope words, or a replacement for `team`. See [Scopes](#scopes). |
| `access` | `MemoryAccess` | — | `read` and `write` functions for shared scopes. See [Access](#access). |
| `maxPerScope` | `number` | `10000` | Most memories one scope may hold. A save past it fails with `limit`. |
| `embeddingModel` | `ModelId` | — | Adds meaning search with this embedding model. Nothing picks one by default. |
| `dimensions` | `number` | — | The embedding model's vector size, such as `1536`. Required with `embeddingModel`. |
| `atlasSearch` | `boolean` | `false` | MongoDB only: search with Atlas Search indexes. Needs Atlas Search on the cluster. |
| `tools` | `{ memory_search?, memory_save?, memory_forget? }` | — | Changes whether a memory tool asks first, for every agent: `{ memory_save: { approval: 'required' } }`. See [Agents](#agents). |

It keeps memories tidy without AI:

* A save with a `key` updates 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. With `embeddingModel`, it also ranks by meaning, so "how should I contact them?" finds "the client prefers email".

| Database | Word search | Meaning search |
| - | - | - |
| SQLite and Postgres | Yes | Yes, with `embeddingModel` |
| MongoDB with `atlasSearch: true` | Yes | Yes, with `embeddingModel` |
| MongoDB without Atlas Search | Substring match | No |

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`.

| Option | Type | Default | Description |
| - | - | - | - |
| `save` | `(args: MemorySaveArgs) => Promise<Memory>` | — | Adds a memory, or updates the scope's memory with the same `key`. |
| `search` | `(args: MemorySearchArgs) => Promise<MemorySearchHit[]>` | — | Returns hits for `query`, best first, at most `limit`. |
| `list` | `(args: MemoryListArgs) => Promise<MemoryList>` | — | Returns one page of the scope, filtered by `pinned` when set. |
| `get` | `(args: MemoryGetArgs) => Promise<Memory>` | — | Returns one memory, or throws `not-found`. |
| `update` | `(args: MemoryUpdateArgs) => Promise<Memory>` | — | Changes one memory, or throws `not-found`. |
| `forget` | `(args: MemoryForgetArgs) => Promise<{ deleted: number }>` | — | Removes one memory by `id`, or the whole scope without one. |
| `init` | `(args: { frogbot }) => void \| Promise<void>` | — | Runs once at startup, to open clients. |
| `afterTurn` | `(args: MemoryAfterTurnArgs) => void \| Promise<void>` | — | Runs after a finished turn of an agent with `memory: true`, to learn from it. The reply never waits for it, and a throw is logged. |
| `sync` | `MemorySync` | — | A `push(changes)` and `pull(cursor)` pair FrogBot keeps on `frogbot.memory.sync`, with no behavior of its own. |
| `collection` | `(args: { db }) => CollectionConfig` | — | A collection the adapter stores memories in, added to the app's database. |
| `namespace` | `string` | `''` | Accept it in your factory options, so apps can set it. |
| `scopes` | `Record<string, MemoryScope>` | — | Accept it in your factory options, so apps can declare scope words. |
| `access` | `MemoryAccess` | — | Accept it in your factory options, so apps can set access. |
| `tools` | `{ memory_search?, memory_save?, memory_forget? }` | — | Accept it in your factory options, so apps can change tool approval. |

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:

```ts theme={"theme":"tokyo-night"}
import { testMemoryAdapter } from 'frogbot/memory/testing'

it('passes the memory adapter kit', async () => {
  await testMemoryAdapter(adapter, {
    req: await frogbot.createRequest(),
    errors: {
      limit: (target) => adapter.save({ ...target, text: 'x'.repeat(10_000), pinned: true }),
    },
  })
})
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.