Skip to main content
PATCH
/
v1
/
memories
/
{memory_id}
TypeScript SDK
import { MemoryClient } from '@xtraceai/memory';

const client = new MemoryClient({
  apiKey: process.env.XTRACE_API_KEY!,
  orgId:  process.env.XTRACE_ORG_ID!,
});

const updated = await client.memories.update(
  '5b0d0f7d-d502-45d5-847d-e19512b5c517',
  { text: 'Corrected fact.' },
);
{
  "id": "<string>",
  "text": "<string>",
  "object": "memory",
  "user_id": "<string>",
  "agent_id": "<string>",
  "conv_id": "<string>",
  "app_id": "<string>",
  "metadata": {},
  "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>"
    ]
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.mem.xtrace.ai/llms.txt

Use this file to discover all available pages before exploring further.

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).

Headers

​
X-Service-Token
string | null

Path Parameters

​
memory_id
string
required

Body

application/json

PATCH /v1/memories/{id} — update text and/or metadata.

Metadata is merged onto the existing payload, not replaced. Immutable fields (type, entity ids, created_at) cannot be changed via this endpoint; attempting to set them surfaces 422 immutable_field.

​
text
string | null

New fact text. When provided, supersedes the existing fact: a new ACTIVE row is created pointing back at the old one via supersedes, the old row's tag2 flips to superseded. Fact-only — sending text on an artifact or episode row returns 422. Empty / whitespace-only values return 422 empty_text_field.

​
metadata
Metadata · object

Customer metadata to merge onto the row. Keys present here replace same-named keys on the existing row; keys absent here are left untouched (no key deletion via PATCH). Setting an immutable field (entity ids, type, created_at) returns 422 immutable_field; setting an internal storage key (tag1-tag5, kb_type, etc.) returns 422 reserved_field.

Response

Successful Response

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

The mem0-parity 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.

​
metadata
Metadata · object

Free-form customer-supplied metadata that was on the row at write time. Each key here is independently indexed and filterable on search.

​
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 metadata patch / supersede.

​
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.