Memory

All endpoints take a bearer token and name the workspace they act on. Required capability is listed per endpoint. Errors follow the shared error format.

Share, explain, change feed, quarantine review and evaluations are on Memory governance.

Append a memoryCopy Anchor Link

POST /v1/memory/append — store one memory. Supports Idempotency-Key.

curl -s -X POST "$AGENT_MEMORY_BASE_URL/v1/memory/append" \
  -H "Authorization: Bearer $AGENT_MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c0c9e-2b7a-4d43-9a0f-8f6d2a1b3c4d" \
  -d '{
    "workspaceId": "'"$AGENT_MEMORY_WORKSPACE_ID"'",
    "runId": "run-1",
    "layer": "Workspace",
    "type": "decision",
    "content": "All entity IDs are GUIDs, never ints",
    "tags": { "facet": "persistence" }
  }'

BodyCopy Anchor Link

ResponseCopy Anchor Link

{ "id": "8b0c1c0e-…", "merged": false, "contentReplaced": false, "operationId": "3e5f…" }

• id is always the surviving memory. When the content is a near-duplicate of an existing memory, the write is merged into it, merged is true and id is the existing memory's ID; contentReplaced says whether the existing text was replaced.
• operationId is the ingestion receipt.

Content that looks like prompt injection or data exfiltration is stored quarantined and never recalled until reviewed — see Review a quarantined memory.

Retrieve contextCopy Anchor Link

POST /v1/memory/retrieve — recall a ranked, token-budgeted context. Every option and section is described in Retrieval.

curl -s -X POST "$AGENT_MEMORY_BASE_URL/v1/memory/retrieve" \
  -H "Authorization: Bearer $AGENT_MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "'"$AGENT_MEMORY_WORKSPACE_ID"'",
    "runId": "run-1",
    "semanticQuery": "how are entity IDs typed?",
    "tokenBudget": 2000
  }'

Key fields: workspaceId, runId, semanticQuery, applicationId, agentId, userId, topN, tokenBudget, mode, rerank, minScore, tags, includeSuperseded, asOf, asOfAxis, temporalBefore, temporalAfter, temporalAnchor, expandSessions, expandSessionCount, expandSessionWindow, raw, explain, overrides.

Response: a MemoryContext with receiptId, blocks, userProfile, platformEntries, tenantFloors, tenantEntries, workspaceEntries, procedures, relevantEpisodes, fileDocs, sessionSummary, sessionEntries, omittedWorkspaceCount, supersededHiddenCount, compilation and (with explain) diagnostics.

Errors specific to retrieve: 400 for an invalid mode, asOfAxis or overrides value, or for mode: "deterministic" with rerank: true; 422 CONTEXT_BUDGET_TOO_SMALL when the budget cannot hold non-negotiable policy.

Get a memoryCopy Anchor Link

GET /v1/memory/{id}?workspaceId=…

Returns the memory entry, including version, provenance, temporal and policy fields and trust. 404 when it does not exist or is not visible to the subject. Use this for artifact_ref memories, which semantic search does not surface.

Update a memoryCopy Anchor Link

PUT /v1/memory/{id} — replace a memory's content in place. Supports Idempotency-Key and If-Match.

{ "workspaceId": "…", "content": "All entity IDs are GUIDs (v7)", "applicationId": null, "agentId": null, "userId": null }

The content is screened and re-embedded; an update row is written to the change feed. See Updating and forgetting.

Delete a memoryCopy Anchor Link

DELETE /v1/memory/{id}?workspaceId=…[&cascade=true] — soft-delete the memory and run the erasure cascade. Supports Idempotency-Key.

See Updating and forgetting.

Erasure statusCopy Anchor Link

GET /v1/memory/{id}/erasure?workspaceId=… — where a memory's erasure stands.

{ "memoryId": "8b0c1c0e-…", "status": "pending", "attempts": 2, "erasedAt": null }

status is none, pending, complete or dead. Takes the same optional applicationId, agentId, userId query parameters. 404 when the memory is unknown or was never visible to the caller.

Ingestion receiptCopy Anchor Link

GET /v1/memory/operations/{operationId}?workspaceId=… — what became of an append. An append is durable when it returns, but some effects (embedding, when the workspace defers it, and the webhook event) can finish afterwards.

{
  "operationId": "3e5f…",
  "memoryId": "8b0c1c0e-…",
  "merged": false,
  "contentReplaced": false,
  "status": "indexed",
  "createdAt": "2026-10-01T09:00:00Z",
  "effects": [ { "kind": "event", "state": "succeeded", "attempt": 1, "lastError": null } ]
}

status is pending, indexed or failed. Each effect has a kind (embed or event), a state (pending, failed, succeeded or dead), the attempt count and the last error. A receipt from another workspace answers 404.

Consolidate a runCopy Anchor Link

POST /v1/memory/consolidate — end a run: create its episode, extract facts, learn procedures and clear its session memory. Supports Idempotency-Key.

{
  "workspaceId": "…",
  "runId": "run-1",
  "applicationId": null,
  "goal": "Add vegetarian filtering to the menu service",
  "extractionInstructions": "Only keep decisions about the public API."
}

Response: {"status":"consolidated"}. goal and extractionInstructions are optional. Idle runs are consolidated automatically by the background worker. See Runs and consolidation.