Skip to main content
PATCH
/
v1
/
memories
/
{memory_id}
Update memory group_ids
curl --request PATCH \
  --url https://api.production.xtrace.ai/v1/memories/{memory_id} \
  --header 'Content-Type: application/json' \
  --header 'X-Org-Id: <api-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "add_group_ids": [
    "<string>"
  ],
  "remove_group_ids": [
    "<string>"
  ]
}
'
{
  "id": "<string>",
  "text": "<string>",
  "object": "memory",
  "user_id": "<string>",
  "agent_id": "<string>",
  "conv_id": "<string>",
  "app_id": "<string>",
  "group_ids": [
    "<string>"
  ],
  "categories": [
    "<string>"
  ],
  "score": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "details": {
    "fact_type": "<string>",
    "status": "<string>",
    "supersedes": "<string>",
    "source_role": "<string>",
    "episode_id": "<string>",
    "artifact_id": "<string>",
    "artifact_ids": [
      "<string>"
    ],
    "source_event_ids": [
      "<string>"
    ]
  }
}

Authorizations

​
x-api-key
string
header
required

Long-lived org API key. Alternative: Authorization: Bearer <key>.

​
X-Org-Id
string
header
required

Required alongside the API key (no key→org reverse index).

Path Parameters

​
memory_id
string
required

Body

application/json

PATCH /v1/memories/{id} — add or remove group_ids on an existing memory row.

Scope is intentionally narrow: this endpoint mutates the row's group tags only — the sharing axis. It does not edit text or any entity id (user_id / agent_id / conv_id / app_id); those are immutable once ingested.

Semantics are set-based and order-independent — group_ids is an unordered set of tags. Adding an id already present is a no-op, and removing an id that isn't there is a no-op, so the whole operation is idempotent and safe to retry. remove is applied before add; the same id may not appear in both lists (422 contradictory_group_ids). At least one list must be non-empty (422 empty_patch).

Every id in add_group_ids must be an active group on the org (see POST /v1/groups); an unknown or archived id is rejected with 422 invalid_group_ids. remove_group_ids is not validated against the registry — a tag can always be removed, including one whose group was archived after it was applied.

​
add_group_ids
string[]

Group ids to add to the row. Each must be an active group on the org. Ids already present are ignored (no duplicates). Blank entries are trimmed away.

Example:
["grp_eng", "grp_oncall"]
​
remove_group_ids
string[]

Group ids to remove from the row. Ids not currently on the row are ignored. Not validated against the group registry, so an archived group's tag can still be removed.

Example:
["grp_personal"]

Response

Updated. Returns the full memory with its new group_ids.

Unified memory resource — facts, artifacts, episodes marshal to this shape. type is the discriminator; details is the type-specific extension.

Invariant: text is always a short readable preview, regardless of type (fact statement / artifact summary / episode summary).

​
id
string
required

Stable UUID for this memory row.

​
type
enum<string>
required

Memory subtype. fact = a single semantic claim extracted from a turn; artifact = a structured object (code, doc, image) referenced by the conversation; episode = a session-scoped summary of a stretch of turns.

Available options:
fact,
artifact,
episode
​
text
string
required

Short readable preview. For facts: the claim statement. For artifacts: a summary or title (full body lives in details.full_content, opt-in via include=full_content). For episodes: a summary of the session.

​
object
string
default:memory

Constant discriminator for the resource type.

Allowed value: "memory"
​
user_id
string | null

User scope this row belongs to.

​
agent_id
string | null

Agent scope, if any.

​
conv_id
string | null

Conversation anchor.

​
app_id
string | null

App scope, if any.

​
group_ids
string[]

Group ids associated with this row — the sharing axis. Stamped at ingest time and editable afterward via PATCH /v1/memories/{id} (add_group_ids / remove_group_ids). Reachable as a filter axis via filters: {group_ids: <id>} or {group_ids: {"$in": [<id>, ...]}}.

​
categories
string[]

Optional category labels from xmem's extraction pipeline.

​
score
number | null

Vector-similarity score. Present only on search responses; null on list / get-by-id / patch / ingest result rows.

​
created_at
string<date-time>

ISO-8601 timestamp of original ingest.

​
updated_at
string<date-time>

ISO-8601 timestamp of the last supersede / consolidation.

​
details
FactDetails · object

Per-row fact details — sits under Memory.details when Memory.type == "fact". Mirrors the SoT shape, not xmem's raw Fact shape: e.g. xmem's source_artifact_id → artifact_id.