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

# Memory

> Read and write agent memory entries across the channel and long-term layers.

Agent memory is the durable knowledge layer that survives session boundaries. The Memory domain exposes two of the three layers: `channel` (per-channel institutional memory) and `longterm` (RAG-indexed durable archive). Session memory is internal to an active turn and not exposed by the API.

## Resource shape

Each call targets one layer; the API never spans layers in one call. On `list` and `get`, the `layer` query parameter is optional and defaults to `channel`. `create` takes `layer` in the body; `update` and `delete` require `layer: "longterm"`, because only long-term memory can be patched or forgotten over the API.

A memory entry is one of two explicit shapes, told apart by `layer`:

* **`ChannelMemoryEntry`** (`layer: "channel"`): `id`, `agentId`, `channelId`, `summary`, `summaryTokenCount`, `maxSummaryTokens`, `sessionCount`, `lastUpdatedAt`, `createdAt` and `projectId` (or `null`).
* **`LongTermMemoryEntry`** (`layer: "longterm"`): `id`, `agentId`, `content`, `memoryType`, `sourceType`, `sourceChannelId`, `sourceSessionId`, `sourceTimestamp`, `createdAt`, `lastRetrievedAt`, `retrievalCount`, `status` (`ACTIVE` or `FORGOTTEN`), `summary`, `tags` and `projectId`. Absent optional values are `null`; `tags` is `[]`.

No other stored field crosses the API: not the embedding, the companies an entry is stamped with, its content hash, or the app that wrote it.

## Paging

`GET /api/v3/memory` pages with a cursor. Pass `limit` (1 to 100, default 50; a larger value is `400` `too_big`) and, after the first page, `cursor` set to the previous page's `meta.nextCursor`. Continue while `meta.hasMore` is `true`; `meta.nextCursor` is `null` on the last page.

* Long-term memory lists one agent's `ACTIVE` entries, newest first.
* Channel memory by `agentId` lists in `channelId` order; by `channelId` alone it lists in creation order across agents; with both it names at most one entry, in a single page.

A page can be short, or even empty, before the end: entries are omitted after the page is read when the caller may not read them (a Personal Agent's rows in a listing by channel, or an entry at a company the caller can't read). Always follow `hasMore`, never the page size. A cursor is valid only for the same layer and filters it was issued for.

`limit` of `0`, a negative or non-integer value, a repeated `limit` or `cursor`, and a cursor that is malformed or was issued for another listing all answer `400 bad_request`, and so does a malformed `channelId`.

## Forgotten memory

Forgetting a long-term memory (`DELETE /api/v3/memory/{memoryId}`) sets its `status` to `FORGOTTEN`. A forgotten entry:

* is no longer listed;
* is still returned by `GET /api/v3/memory/{memoryId}`, with `status: "FORGOTTEN"`, so a caller can observe the delete;
* answers `410 gone` ("Memory is forgotten") to `PATCH /api/v3/memory/{memoryId}`;
* answers `200` with `{ "id": "<memoryId>", "status": "FORGOTTEN" }` to a repeated delete.

## Write semantics and retries

`POST /api/v3/memory` reads only the documented fields of the body's `layer` (see [createMemory](https://docs.gloo.com/forge/reference/http-api/memory/create.md)) and ignores any other field. A documented field of the wrong type, or an id that is not an id of its kind (`channelId`, `sourceChannelId`, `projectId`, `sourceSessionId`), answers `400` naming the field. A successful create answers `{ "id": "<memoryId>", "layer": "channel" | "longterm" }`. A channel memory is one entry per agent and channel: a create for an existing pair replaces its summary and answers the same `id`.

Send an `Idempotency-Key` header to make a create, update or delete safe to retry. A repeat with the same key and body within 24 hours never writes twice: it returns the stored response with `Idempotency-Replayed: true` only while you still hold `memory:write` and `memory:read`, may read the memory as `get` would, and may still write that agent's memory. Otherwise it answers `403` for a missing permission or `409 idempotency_result_unavailable`. See [Memory write replay](https://docs.gloo.com/forge/reference/idempotency.md#memory-write-replay).

## External App memory isolation

When an External App is deactivated, the platform purges its memory:

* **Channel memory** belongs to the agent that holds it, so the channel memory of every agent the app owns is hard-deleted, including agents the deactivation archives. An agent the app deletes through `DELETE /api/v3/agents/{agentId}` has its channel memory hard-deleted with it. Large memory is deleted in batches shortly after the delete; until the last batch runs, creating an agent with the deleted agent's `agentId` is refused with `AGENT_ID_CHANNEL_MEMORY_NOT_PURGED`, so a new agent never inherits the old memory.
* **Long-term memory** that an External App writes through `POST /api/v3/memory` with `layer: "longterm"` records the writing app in an optional `principalExternalApplicationId` field. Those entries are soft-deleted (`status: "FORGOTTEN"`).

App deactivation never touches the channel memory of agents the app doesn't own, or long-term memory without that field, such as shared project memory and human-authored entries.

Forgetting a long-term memory also deletes any knowledge entry an agent or a retrieval threshold promoted from it, so the forgotten content can't be found through knowledge search. An entry a person promoted stays. See [Knowledge — Deletion](https://docs.gloo.com/forge/reference/http-api/knowledge#deletion).

## What is redacted

Before a long-term memory is embedded or stored, Forge replaces secrets, payment card numbers and US Social Security numbers in its `content` and `summary` with placeholders such as `[REDACTED_API_KEY]`, `[REDACTED_CREDIT_CARD]` and `[REDACTED_SSN]`. Secrets are provider API keys, `Bearer` tokens, JWTs and credential assignments such as `client_secret=…`. A card number is redacted only when it passes the Luhn check and is written as one digit run or in card-style groups (such as `4111 1111 1111 1111`), so a date range is kept. A reference number is kept unless it is a single 13–19 digit run that passes the Luhn check. The same applies to the episodes and facts an agent records after each chat turn or workflow node, to the text of a failed or completed factory step, and to any other text indexed as a workflow embedding, such as a failed step's error. The content hash is computed over the redacted text, so the stored row, its hash and its embedding never hold the removed value.

Email addresses and phone numbers are kept: memory legitimately holds contact details. Redaction does not refuse the write; it removes the value and logs which kinds it removed, never the content. A channel-layer memory's `summary`, a session summary and a long-term memory's `tags` are redacted the same way, and so are the chat turn an agent's memories are extracted from and the session messages and summary a session summary is compacted from, before they reach the model. Rows stored before redaction was introduced are not rewritten. When Forge re-embeds them after an embeddings model change, it embeds their redacted text, so the new vector never holds the removed value.

A long-term memory an agent writes during a run also records that run's id as `sourceRunId`. Rows written before this field existed, and rows written through this API, have none.

## Which agents' memory the API reaches

An External App reaches the agents in its owner-scope chain. An API key reaches an agent's memory at the agent's home: its role grants must hold `memory:read` at the agent's home org unit to read it and `memory:write` there to write it, and an agent with no home is unreachable. A key granted at the deployment root or the platform scope reaches every homed agent; a key granted only at one organization no longer reaches other organizations' agents.

Within that reach, the API follows the same rules as the Console's agent Knowledge tab, whatever scopes the credential holds:

* **Personal Agents:** their memory is managed only by their owner, from **Settings → Personal Agents**. The API never reads or writes it. A list for a Personal Agent is empty, a listing by `channelId` alone leaves out its rows, a read or an update answers 404, and a write answers 403.
* **Platform agents:** their memory is managed centrally, so the API reads it but never changes it. A create, update or delete answers 403.

## Operations

Reads:

* `GET /api/v3/memory` — [listMemory](https://docs.gloo.com/forge/reference/http-api/memory/list.md) — one page of memory entries; optional `layer` (`channel` by default, or `longterm`), `agentId`, `channelId`, `limit` and `cursor` query params. `agentId` is required for `layer=longterm`, and for External App callers on `layer=channel`.
* `GET /api/v3/memory/{memoryId}` — [getMemory](https://docs.gloo.com/forge/reference/http-api/memory/get.md) — fetch a single memory entry by ID; optional `layer`, default `channel`. A missing memory, one outside the caller's reach, and one at a company the caller can't read all answer 404.

Writes:

* `POST /api/v3/memory` — [createMemory](https://docs.gloo.com/forge/reference/http-api/memory/create.md) — write a new entry (or replace a channel summary); body must include `layer`. An `agentId` outside the caller's reach (an External App's owner-scope chain; for an API key, `memory:write` at the agent's home) answers 403, and so does a `projectId`, or a `channelId`/`sourceChannelId` in a project, that the caller may not write knowledge into (a project in an External App's owner chain; none for a platform API key)
* `PATCH /api/v3/memory/{memoryId}` — [updateMemory](https://docs.gloo.com/forge/reference/http-api/memory/update.md) — partial update of a long-term entry (summary, tags); body must include `id` and `layer: "longterm"`. A forgotten entry answers 410 `gone`.
* `DELETE /api/v3/memory/{memoryId}` — [deleteMemory](https://docs.gloo.com/forge/reference/http-api/memory/delete.md) — forget a long-term entry; body `{ "layer": "longterm" }`. Answers `{ "data": { "id": "<memoryId>", "status": "FORGOTTEN" } }`, and the same again for an entry already forgotten. Any other `layer` answers 400; a missing memory, or one whose agent is outside the caller's reach (an External App's owner-scope chain; for an API key, neither memory permission at the agent's home), answers 404.

## Common workflows

Write a long-term memory entry, then page through the agent's long-term memory:

```bash theme={null}
curl -X POST "$FORGE_BASE/api/v3/memory" \
  -H "Authorization: Bearer $FORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: acme-prefs-2026-09-30" \
  -d '{
    "layer": "longterm",
    "agentId": "support-agent",
    "content": "Customer prefers async-first communication",
    "memoryType": "semantic",
    "sourceType": "session_close",
    "tags": ["customer-prefs", "acme-corp"]
  }'

curl "$FORGE_BASE/api/v3/memory?layer=longterm&agentId=support-agent&limit=20" \
  -H "Authorization: Bearer $FORGE_TOKEN"

# While meta.hasMore is true, pass meta.nextCursor back:
curl "$FORGE_BASE/api/v3/memory?layer=longterm&agentId=support-agent&limit=20&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $FORGE_TOKEN"
```

## Related

* [Agent memory on workflow nodes](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md#agent-memory-on-workflow-nodes) — how an agent recalls and stores memories during a run
* [Native HTTP quickstart](https://docs.gloo.com/forge/quickstart.md#raw-http) — call these endpoints with `fetch` and a bearer token


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