# User Memories

> Give your agents long-term memory across conversations.

## Overview [#overview]

AG-UI Streams remember a conversation. User Memory remembers a person. Save a
fact about a signed-in user once, and your agent can recall it in later
conversations.

If you are looking for the persistence architecture beneath a single
conversation, read [AG-UI Streams & Framework Threads](/vue/openai-agents-python/intelligence/threads-explained)
instead.

## Start with your coding agent [#start-with-your-coding-agent]

Copy this prompt into your coding agent to inspect your existing CopilotKit app and configure long-term memory for your users. Prefer to work through the setup yourself? Follow the manual steps below.

<MemorySetupPrompt />

## What is a memory? [#what-is-a-memory]

A memory is a short, durable statement about a user or a project, stored outside
any single thread. "Prefers concise status updates" is a memory. The forty
messages that revealed the preference are a thread.

The distinction matters because the two have different lifetimes. A thread is
finished when the conversation is. A memory is meant to outlive it, and to be
recalled into a conversation that has not happened yet.

Memories are stored as text plus a vector embedding, so recall is semantic
rather than a keyword match. Asking for "how does this user like updates" can
surface "prefers concise status updates" without sharing a word with it.

## Set up User Memories [#set-up-user-memories]

When you are done, your app will be able to save a memory for a signed-in user and recall it in a later conversation.

<Steps>
  <Step>
    ### Connect CopilotKit Intelligence [#connect-copilotkit-intelligence]

    Complete the [Intelligence quickstart](/vue/openai-agents-python/intelligence/quickstart#set-it-up-manually). That page signs you in with the CLI, selects the project, and configures server-side user identity. Your existing app and agent stay in place.
  </Step>

  <Step>
    ### Confirm memory access [#confirm-memory-access]

    Check your deployment's memory entitlement and embedding configuration using [Activating memory](#activating-memory) below. Cloud-hosted deployments require no embedder configuration on your side. Self-hosted deployments need both a memory-enabled license and a configured embedder. In a TypeScript runtime, also set `memory.access` (see [Limiting access per request](#limiting-access-per-request)).
  </Step>

  <Step>
    ### Save and recall a memory [#save-and-recall-a-memory]

    In a React app:

    1. Render `useMemories()` in a component. See [React](#react) below.
    2. Ask the agent to remember a preference. The new memory appears in the `useMemories()` list.
    3. In a new conversation, ask about that preference. Make sure that the reply uses the saved memory.

    For other frontends and REST, see [Reading and writing memories](#reading-and-writing-memories).
  </Step>
</Steps>

## Key concepts [#key-concepts]

### The three kinds [#the-three-kinds]

Every memory is one of three kinds. The kind is supplied by whoever saves it and
is never inferred.

| Kind | What it holds |
|------|---------------|
| `topical` | A durable fact about the subject matter, independent of when it was learned. |
| `episodic` | Something that happened, anchored to an occasion. |
| `operational` | A preference or working instruction about how to behave. |

The kind is not cosmetic. Deduplication and supersession are same-kind
operations, so a `topical` fact and an `operational` preference with identical
text are two memories, not one.

### User and project scope [#user-and-project-scope]

A memory is scoped to a single user or shared across a project.

- **`user`** is the platform default. Omit `scope` and you get it. This is the
  only scope delivered over realtime today.
- **`project`** is shared, and must be requested explicitly.

Scope is enforced per request against the caller's grant, so a client holding
read-only access to project scope cannot write to it.

### Saving a near-duplicate absorbs it [#saving-a-near-duplicate-absorbs-it]

If you save content that closely matches a live memory in the same tenant,
scope, and kind, the platform does not create a second row. It absorbs the new
content into the existing memory, unions the source threads, and refreshes
recency.

The save still succeeds, and the result tells you which happened, so a UI or an
agent can say "absorbed into an existing memory" rather than implying something
new was written.

### Updating is a full replacement, not a patch [#updating-is-a-full-replacement-not-a-patch]

Updating a memory supersedes it: the old memory is retired and a new one is
created with a new `id`. The change set you supply is the complete definition of
the new memory.

<Callout type="warn">
Omitting `sourceThreadIds` on an update does not preserve the previous value, it
resets the new memory's source threads to empty. Re-send `content`, `kind`, and
any `sourceThreadIds` you want to keep.
</Callout>

### Removing is a retirement, not a delete [#removing-is-a-retirement-not-a-delete]

Removing a memory retires it rather than erasing it. Retired memories are
excluded from recall and from the default list, and can be surfaced again by
asking for invalidated rows explicitly.

## Activating memory [#activating-memory]

<Callout type="info">
Memory is not a feature flag. There is no `MEMORY_ENABLED` environment variable
and no `memory.enabled` Helm value. Access is granted by entitlement, and the
embedder is configured separately at startup.
</Callout>

Three things must be true before a caller can use memory:

1. The deployment or organization is **entitled** to memory.
2. app-api has valid **embedder configuration**.
3. A TypeScript runtime sets **`memory.access`**. Without it, and without the deprecated options described below, the browser memory routes return 404 and agent runs get no memory tools. See [Limiting access per request](#limiting-access-per-request).

Entitlement resolution fails closed. An unresolved entitlement, an inactive one,
or a dependency outage all deny memory rather than allowing it.

### Self-hosted [#self-hosted]

This section is for operators who run [self-hosted Intelligence](/vue/openai-agents-python/intelligence/self-hosting). On cloud-hosted Intelligence, skip to [Cloud-hosted](#cloud-hosted).

The signed deployment license is the authority. Memory is available when that
license carries the `memory` feature, which today ships in the enterprise plan.
If your license does not include it, no amount of configuration will mount the
surfaces, and the correct next step is to talk to us about the license rather
than to keep editing values files.

The embedder is configured through these variables, which the chart templates
for you:

| Variable | Purpose |
|----------|---------|
| `MEMORY_EMBEDDINGS_URL` | Base URL of an OpenAI-compatible embeddings endpoint. Required. |
| `MEMORY_EMBEDDING_MODEL` | Embedding model id sent to that endpoint. Required. |
| `MEMORY_EMBEDDINGS_API_KEY` | Optional bearer token. Leave unset for the bundled in-cluster embedder. |
| `MEMORY_EMBEDDINGS_DIMENSIONS` | Optional. Must be `1024`, because storage is a 1024-dimension half-precision vector. |

Two consequences worth knowing before you deploy:

- **app-api refuses to start** if a required variable is missing or invalid.
  This is deliberate. Entitlements can change while the process is running, so
  it must never come up with memory routes and no embedder behind them.
- **pgvector must be installed on the database server.** The migration that
  creates the memory table also creates the extension, and the migration job
  fails without it.

By default the chart deploys an in-cluster text-embeddings-inference workload
and points app-api at it. To use a hosted provider instead, set an external
embeddings URL and model, at which point the in-cluster workload is not
rendered:

```yaml title="values.yaml"
embeddings:
  external:
    url: https://api.openai.com
    model: text-embedding-3-small
    dimensions: 1024
    apiKey:
      existingSecret: openai-embeddings
      secretKey: api-key
```

<Callout type="warn">
Changing the embedding model or provider changes the vector space. Existing
memories were embedded in the old space and are not comparable in the new one,
so recall quality degrades until they are re-embedded. Treat a model change as a
migration, not a config tweak.
</Callout>

### Cloud-hosted [#cloud-hosted]

On cloud-hosted Intelligence, memory is resolved per organization from that
organization's effective entitlement, combining its plan features with any
enterprise override. Nothing needs configuring on your side.

## Limiting access per request [#limiting-access-per-request]

The runtime configuration shown here uses the TypeScript API. Python, Go, Ruby, and C#/.NET have different policy callbacks; see [Memory policies in other runtime languages](#memory-policies-in-other-runtime-languages).

Entitlement decides whether memory exists for a deployment. `memory.access`
decides what one request may do with it. It is a single policy on the
Intelligence runtime, and it governs **both** memory surfaces: the tools an
agent gets during a run, and the browser routes behind `useMemories()`.

<Callout type="warn">
Without `memory`, both surfaces are off. Two deprecated options can still turn
a surface on with no policy. That surface then gets `read-write` on both scopes
for every authenticated request:

- The deprecated `enableEnterpriseLearning` option on `CopilotKitIntelligence`
  gives agent runs all three memory tools, subject only to your organization's
  entitlement. Use `memory.access` instead.
- The deprecated `exposeMemoryRoutes: true` flag mounts the browser routes with
  no policy behind them.

This is the opposite of Channels, where a run gets no memory unless it asks.
Configure `memory.access` whenever either surface is on.
</Callout>

```ts title="runtime.ts"
const runtime = new CopilotRuntime({
  intelligence,
  identifyUser: async (request) => resolveUser(request),
  memory: {
    access: ({ user, consumer }) => {
      // Tenants on the free plan get recall, but record nothing new.
      if (isFreePlan(user)) return { user: "read", project: "none" };

      // The browser inspector is read-only; the agent may write.
      return consumer === "client"
        ? { user: "read", project: "read" }
        : { user: "read-write", project: "read-write" };
    },
  },
});
```

The callback runs once per request, after `identifyUser` has resolved, and
receives:

| Field | Meaning |
|-------|---------|
| `request` | The incoming `Request`, if the decision needs a header, cookie, or path. |
| `user` | The application user `identifyUser` returned. |
| `consumer` | `"agent"` for an agent run, `"client"` for the browser memory routes. |

Return a grant naming both scopes, or `null`. Each scope takes `"none"`,
`"read"`, or `"read-write"`. The policy may be async.

### What each outcome does [#what-each-outcome-does]

`null` and a grant with every scope at `"none"` are one outcome, not two. Both
mean "this request gets no memory". What that costs depends on what the caller
asked for:

| The policy returns | Agent run | Browser `/memories/*` |
|--------------------|-----------|------------------------|
| A grant with any scope above `"none"` | Memory tools attach, filtered to the granted scopes | The request proceeds |
| `null`, or every scope `"none"` | **The run proceeds with no memory tools** | **403** |
| Nothing (`undefined`), or an access level outside the three | 500 | 500 |
| A thrown error | 500 | 500 |

The asymmetry is deliberate. A conversation asked for something other than
memories, so switching memory off must not cost the user their assistant. The
browser routes exist only to serve memories, so "you may not have them" answers
the question actually asked. An empty list would falsely imply none exist.

A missing return is treated as a broken policy rather than a restrictive one,
so a branch that forgets to `return` fails loudly instead of quietly switching
memory off.

A grant that allows one scope and not the other is honoured exactly: a
`{ user: "read", project: "none" }` grant registers `recall_memory` alone,
scoped to user memory, and leaves `save_memory` and `forget_memory` unregistered
so the agent never sees a tool it may not call.

<Callout type="info">
`memory.access` is a memory policy, not an authorization gate on the request.
To reject a request outright, use `beforeRequestMiddleware`, which can refuse
before any of this runs.
</Callout>

### It also mounts the browser routes [#it-also-mounts-the-browser-routes]

Configuring `memory` turns on `/memories`, `/memories/recall`,
`/memories/subscribe`, and `/memories/:id`. Without it those routes 404 as if
they did not exist, so an un-opted-in deployment reveals nothing about memory
even when Intelligence is configured.

The older `exposeMemoryRoutes: true` flag did the mounting without the policy
and is deprecated. `memory.access` replaces it: one option that both exposes
the surfaces and bounds what they may do.

### Channels grant memory per run instead [#channels-grant-memory-per-run-instead]

A Channel run carries its own grant on `runAgent`, using the same three access
levels, rather than consulting `memory.access`. See
[Identity and Memory](/slack/identity-and-memory) for that path, including
how to choose the memory subject in a group conversation.

### Memory policies in other runtime languages [#memory-policies-in-other-runtime-languages]

After [connecting your runtime](/vue/openai-agents-python/intelligence/quickstart#connect-your-runtime), configure its callback from trusted application policy:

| Runtime | Configuration | Callback inputs |
| --- | --- | --- |
| Python | `IntelligenceRuntime(memory_policy=...)` | User, then Starlette request |
| Go | `Config.MemoryAccess` | HTTP request, then user |
| Ruby | `Runtime.new(memory_access: ...)` | User, then Rack environment |
| C#/.NET | `RuntimeOptions.MemoryGrant` | HTTP context, user, cancellation token |

These callbacks govern the native runtime's Memory routes. They do not implement the TypeScript `consumer` callback or its automatic agent-tool registration described above. Each grant names `user` and `project`, using `none`, `read`, or `read-write`. Without a callback, the native runtimes delegate to Intelligence's Memory policy; omitting it does not disable access.

## Reading and writing memories [#reading-and-writing-memories]

### Vue [#vue]

`@copilotkit/vue/v2` does not yet export a reactive memory controller equivalent
to React's `useMemories()`. Use the REST routes below from a trusted backend, or
let an agent use the MCP tools; do not put a project API key in the browser.

### REST [#rest]

The memory routes are available to any backend or script holding a runtime
credential. Authentication is the runtime tuple: a project API key as a bearer
token, plus the app user's id in a header.

| Route | Purpose |
|-------|---------|
| `GET /api/memories` | List the caller's memories. Pass `includeInvalidated=true` to include retired ones. |
| `POST /api/memories` | Save a memory. |
| `POST /api/memories/recall` | Semantic recall against a query. |
| `PATCH /api/memories/:id` | Supersede a memory with a full replacement. |
| `DELETE /api/memories/:id` | Retire a memory. |
| `POST /api/memories/subscribe` | Mint a realtime subscription for memory metadata. |

A save takes the content, the kind, an optional scope, and optional provenance:

```bash
curl -X POST https://your-deployment/api/memories \
  -H "Authorization: Bearer cpk-<project>_<short>_<long>" \
  -H "X-Cpki-User-Id: <app-user-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Prefers concise status updates.",
    "kind": "operational",
    "sourceThreadIds": ["<thread-id>"]
  }'
```

`content` is capped at 8192 characters and `sourceThreadIds` at 100 entries.
Unknown fields are rejected rather than ignored, so a typo in a key is an error
instead of a silent no-op.

Recall takes a query and an optional result limit, which defaults to 5 and is
capped at 20:

```bash
curl -X POST https://your-deployment/api/memories/recall \
  -H "Authorization: Bearer cpk-<project>_<short>_<long>" \
  -H "X-Cpki-User-Id: <app-user-id>" \
  -H "Content-Type: application/json" \
  -d '{ "query": "how does this user like updates", "limit": 5 }'
```

Every route returns memories in the same shape: `id`, `kind`, `scope`,
`content`, and `sourceThreadIds`. Recall results additionally carry a `score`,
and the list route carries `invalidatedAt` when retired rows are requested.

### Agent tools over MCP [#agent-tools-over-mcp]

Three tools let an agent manage its own memory: `save_memory`, `recall_memory`,
and `forget_memory`.

They register on the MCP server only when that surface is mounted, which is a
prerequisite for MCP generally rather than a memory setting. Registration is
still checked per request against the caller organization's memory entitlement,
so mounting MCP does not grant memory.

Registration is then narrowed again by the run's grant, so an agent is only ever
offered tools it may actually call: a readable scope registers `recall_memory`,
a writable one adds `save_memory` and `forget_memory`, and a grant of nothing
registers none of them. See
[Limiting access per request](#limiting-access-per-request) for where that grant
comes from.

## How recall works [#how-recall-works]

Recall is hybrid. A query is embedded and compared against stored vectors, and
the result is fused with other signals into a single score, which is what the
`score` field on a recall result reports. Retired and superseded memories are
excluded.

This is why the embedding space matters so much. Comparability is a property of
the space, not of the text, so memories written under one model cannot be
meaningfully ranked against a query embedded under another.
