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. Onlist 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,createdAtandprojectId(ornull).LongTermMemoryEntry(layer: "longterm"):id,agentId,content,memoryType,sourceType,sourceChannelId,sourceSessionId,sourceTimestamp,createdAt,lastRetrievedAt,retrievalCount,status(ACTIVEorFORGOTTEN),summary,tagsandprojectId. Absent optional values arenull;tagsis[].
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
ACTIVEentries, newest first. - Channel memory by
agentIdlists inchannelIdorder; bychannelIdalone it lists in creation order across agents; with both it names at most one entry, in a single page.
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}, withstatus: "FORGOTTEN", so a caller can observe the delete; - answers
410 gone(“Memory is forgotten”) toPATCH /api/v3/memory/{memoryId}; - answers
200with{ "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) 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.
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’sagentIdis refused withAGENT_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/memorywithlayer: "longterm"records the writing app in an optionalprincipalExternalApplicationIdfield. Those entries are soft-deleted (status: "FORGOTTEN").
What is redacted
Before a long-term memory is embedded or stored, Forge replaces secrets, payment card numbers and US Social Security numbers in itscontent 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 holdmemory: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
channelIdalone 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 — one page of memory entries; optionallayer(channelby default, orlongterm),agentId,channelId,limitandcursorquery params.agentIdis required forlayer=longterm, and for External App callers onlayer=channel.GET /api/v3/memory/{memoryId}— getMemory — fetch a single memory entry by ID; optionallayer, defaultchannel. A missing memory, one outside the caller’s reach, and one at a company the caller can’t read all answer 404.
POST /api/v3/memory— createMemory — write a new entry (or replace a channel summary); body must includelayer. AnagentIdoutside the caller’s reach (an External App’s owner-scope chain; for an API key,memory:writeat the agent’s home) answers 403, and so does aprojectId, or achannelId/sourceChannelIdin 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 — partial update of a long-term entry (summary, tags); body must includeidandlayer: "longterm". A forgotten entry answers 410gone.DELETE /api/v3/memory/{memoryId}— deleteMemory — forget a long-term entry; body{ "layer": "longterm" }. Answers{ "data": { "id": "<memoryId>", "status": "FORGOTTEN" } }, and the same again for an entry already forgotten. Any otherlayeranswers 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:Related
- Agent memory on workflow nodes — how an agent recalls and stores memories during a run
- Native HTTP quickstart — call these endpoints with
fetchand a bearer token

