Updating and forgetting

Memories change. A user corrects the agent, a decision is reversed, or a person asks to be forgotten. Agent Memory gives you four tools, from lightest to heaviest:

Update in placeCopy Anchor Link

PUT /v1/memory/{id} replaces a memory's content without creating a new memory. The new content is trimmed, screened like an append and re-embedded; an UPDATE history row and an update change-feed row are written.

Updates use optimistic concurrency. Every memory has a version, returned when you read it (GET /v1/memory/{id}):

• Send If-Match: "<version>" to make the update conditional. If the memory changed since you read it, the server answers 412 with code precondition_failed and the currentVersion, and writes nothing.
• Without If-Match (or with *), the last writer wins.
• A successful update answers 200 { id, version } with an ETag header carrying the new version.

curl -s -X PUT "$AGENT_MEMORY_BASE_URL/v1/memory/<id>" \
  -H "Authorization: Bearer $AGENT_MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "7"' \
  -d '{"workspaceId":"'"$AGENT_MEMORY_WORKSPACE_ID"'","content":"Alex is vegan (not just vegetarian)"}'

Over MCP, update_memory(memoryId, content, version?) does the same; get_memory reports the version.

SupersedeCopy Anchor Link

Superseding keeps both memories but marks the old one as no longer current: it stops being canonical, its valid time closes, a REPLACES relationship is recorded, and memories derived from it are flagged for review. Superseded memories are hidden from recall by default (see Retrieval) and explain shows what replaced them.

There are three ways a memory becomes superseded:

• When writing the replacement — the MCP tool add_memory(..., supersedes=<id>) stores the new memory and supersedes the old one in one step. If the target is not visible or already superseded, nothing is written and the reply says what replaced it.
• Linking two existing memories — the MCP tool supersede_memory(memoryId, supersededBy), for example when two corrections disagree and the user says which one is current. Needs the write capability.
• During consolidation — of two correction memories on the same topic, one at least 24 hours newer supersedes the older. Closer pairs are not guessed at: they are recorded as an open contradiction (visible in explain_memory) for you to resolve with supersede_memory.

MCP tools that take a memory ID accept either the full GUID or the short form (the first 8 or more characters) that search and explain print, as long as it is unambiguous in the workspace.

DeleteCopy Anchor Link

DELETE /v1/memory/{id}?workspaceId=… needs the delete capability. The memory's text is destroyed in the delete's own transaction, then an erasure cascade removes every copy derived from it: session entries, episode events, procedure and abstraction references, history.

The SDKs return these as { status } values.

Dependents and cascadeCopy Anchor Link

A delete is refused while live, not-yet-stale memories derive from the target — through DERIVED_FROM, BUILDS_ON or DEPENDS_ON relationships, or tenant conventions promoted from its lineage. You decide:

• Retry with cascade=true to flag those dependents for review (reviewState: "stale") and proceed. Dependents are never deleted for you.
• A leaf memory, or one whose dependents are already stale, needs no cascade.

Deletes never cascade unless you ask — on REST, MCP and every SDK. After a delete, GET /v1/memory/changesets?memoryId=<id>&action=delete shows which dependents were flagged.

Erasure statusCopy Anchor Link

When a delete answers pending, poll the erasure status:

curl -s "$AGENT_MEMORY_BASE_URL/v1/memory/<id>/erasure?workspaceId=$AGENT_MEMORY_WORKSPACE_ID" \
  -H "Authorization: Bearer $AGENT_MEMORY_API_KEY"
# {"memoryId":"…","status":"complete","attempts":1,"erasedAt":"…"}

The response contains IDs and state only, never content.

RetentionCopy Anchor Link

Workspaces can age memories out automatically with the setting retention.memoryDays (1–3650). A daily sweep deletes memories older than that with the same cascade as an explicit delete. Age-based retention only runs when the setting is overridden for the workspace or configured by the operator; by default nothing is aged out.

Memories can also carry an expiry time; expired memories are removed by the same daily sweep. Session memory expires on its own 48 hours after a run's last write. See Workspace settings.

Quick referenceCopy Anchor Link