Skip to content
XTrace Memory Manager
Get started
API Reference

Memories

Add Memory
client.memories.add(MemoryAddParams { messages, agent_id, config_overrides, 8 more } body, RequestOptionsoptions?): MemoryAddResponse { consolidation_id_mapping, flush_result, message, 7 more }
POST/v1/memories/add/
Search Memory
client.memories.search(MemorySearchParams { filters, query, char_budget, 7 more } body, RequestOptionsoptions?): MemorySearchResponse { all_retrieved_artifacts, artifacts, context, 5 more }
POST/v1/memories/search/
List Memories
client.memories.list(MemoryListParams { filters, page, page_size } params, RequestOptionsoptions?): MemoryListResponse { count, next, previous, results }
POST/v1/memories/
Get Memory By Id
client.memories.retrieve(stringmemoryID, RequestOptionsoptions?): MemoryItem { id, memory, agent_id, 7 more }
GET/v1/memories/{memory_id}/
Patch Memory
client.memories.update(stringmemoryID, MemoryUpdateParams { metadata, text } body, RequestOptionsoptions?): MemoryItem { id, memory, agent_id, 7 more }
PATCH/v1/memories/{memory_id}/
Delete Memory
client.memories.delete(stringmemoryID, RequestOptionsoptions?): MemoryDeleteResponse
DELETE/v1/memories/{memory_id}/
ModelsExpand Collapse
Artifact { artifact_id, artifact_type, content, 12 more }
artifact_id: string
artifact_type?: string | null
content?: string | null
conv_id?: string | null
created_at?: string | null
descriptor_fact_ids?: Array<string>
episode_id?: string | null
is_latest?: boolean | null
name?: string | null
parent_artifact_id?: string | null
rationale?: string | null
root_artifact_id?: string | null
score?: number | null
summary?: string | null
version?: number | null
Episode { episode_id, artifact_ids, conv_id, 5 more }
episode_id: string
artifact_ids?: Array<string>
conv_id?: string | null
ended_at?: string | null
fact_ids?: Array<string>
started_at?: string | null
summary?: string | null
title?: string | null
Fact { fact_id, text, change_reason, 17 more }
fact_id: string
text: string
change_reason?: string | null
change_type?: string | null
consolidated_at?: string | null
conv_id?: string | null
created_at?: string | null
episode_id?: string | null
event_date?: string | null
fact_type?: string | null
metadata?: unknown
origin?: string | null
root_artifact_id?: string | null
score?: number | null
source_artifact_id?: string | null
source_dia_ids?: Array<string>
source_event_ids?: Array<string>
source_role?: string | null
status?: string | null
supersedes?: string | null
MemoryItem { id, memory, agent_id, 7 more }

One result item — used in flat search results and listings.

id: string
memory: string
agent_id?: string | null
categories?: Array<string>
conv_id?: string | null
created_at?: string | null
metadata?: unknown
score?: number | null
updated_at?: string | null
user_id?: string | null
MemoryAddResponse { consolidation_id_mapping, flush_result, message, 7 more }

Returned by POST /v1/memories/add/.

Sync inline result — the full extracted set is in the response; no event_id / async polling. results mirrors the flat-list shape that search returns, so clients can read just-stored memories with one consistent shape.

consolidation_id_mapping?: Record<string, string>
flush_result?: FlushResult | null

Returned inside AddResponse.flush_result when an auto-flush fires. Carries the freshly-minted episode ids — what a chat orchestrator passes to mark_completed (or equivalent).

episodes?: Array<Episode { episode_id, artifact_ids, conv_id, 5 more } >
episode_id: string
artifact_ids?: Array<string>
conv_id?: string | null
ended_at?: string | null
fact_ids?: Array<string>
started_at?: string | null
summary?: string | null
title?: string | null
stage_timings?: Record<string, number>
message?: string
mode?: "chat" | "import"
One of the following:
"chat"
"import"
results?: Array<MemoryItem { id, memory, agent_id, 7 more } >
id: string
memory: string
agent_id?: string | null
categories?: Array<string>
conv_id?: string | null
created_at?: string | null
metadata?: unknown
score?: number | null
updated_at?: string | null
user_id?: string | null
stage_timings?: Record<string, number>
status?: string
stored_artifacts?: Array<Artifact { artifact_id, artifact_type, content, 12 more } >
artifact_id: string
artifact_type?: string | null
content?: string | null
conv_id?: string | null
created_at?: string | null
descriptor_fact_ids?: Array<string>
episode_id?: string | null
is_latest?: boolean | null
name?: string | null
parent_artifact_id?: string | null
rationale?: string | null
root_artifact_id?: string | null
score?: number | null
summary?: string | null
version?: number | null
stored_facts?: Array<Fact { fact_id, text, change_reason, 17 more } >
fact_id: string
text: string
change_reason?: string | null
change_type?: string | null
consolidated_at?: string | null
conv_id?: string | null
created_at?: string | null
episode_id?: string | null
event_date?: string | null
fact_type?: string | null
metadata?: unknown
origin?: string | null
root_artifact_id?: string | null
score?: number | null
source_artifact_id?: string | null
source_dia_ids?: Array<string>
source_event_ids?: Array<string>
source_role?: string | null
status?: string | null
supersedes?: string | null
superseded_fact_ids?: Array<Array<unknown>>
MemorySearchResponse { all_retrieved_artifacts, artifacts, context, 5 more }

Returned by POST /v1/memories/search/.

results is the flat list (always populated when matches exist). In mode=context the additional fields (context, artifacts, episodes) are filled in too. In mode=flat they’re empty.

all_retrieved_artifacts?: Array<Artifact { artifact_id, artifact_type, content, 12 more } >
artifact_id: string
artifact_type?: string | null
content?: string | null
conv_id?: string | null
created_at?: string | null
descriptor_fact_ids?: Array<string>
episode_id?: string | null
is_latest?: boolean | null
name?: string | null
parent_artifact_id?: string | null
rationale?: string | null
root_artifact_id?: string | null
score?: number | null
summary?: string | null
version?: number | null
artifacts?: Array<Artifact { artifact_id, artifact_type, content, 12 more } >
artifact_id: string
artifact_type?: string | null
content?: string | null
conv_id?: string | null
created_at?: string | null
descriptor_fact_ids?: Array<string>
episode_id?: string | null
is_latest?: boolean | null
name?: string | null
parent_artifact_id?: string | null
rationale?: string | null
root_artifact_id?: string | null
score?: number | null
summary?: string | null
version?: number | null
context?: string
episodes?: Array<Episode { episode_id, artifact_ids, conv_id, 5 more } >
episode_id: string
artifact_ids?: Array<string>
conv_id?: string | null
ended_at?: string | null
fact_ids?: Array<string>
started_at?: string | null
summary?: string | null
title?: string | null
facts?: Array<Fact { fact_id, text, change_reason, 17 more } >
fact_id: string
text: string
change_reason?: string | null
change_type?: string | null
consolidated_at?: string | null
conv_id?: string | null
created_at?: string | null
episode_id?: string | null
event_date?: string | null
fact_type?: string | null
metadata?: unknown
origin?: string | null
root_artifact_id?: string | null
score?: number | null
source_artifact_id?: string | null
source_dia_ids?: Array<string>
source_event_ids?: Array<string>
source_role?: string | null
status?: string | null
supersedes?: string | null
mode?: "flat" | "context"
One of the following:
"flat"
"context"
results?: Array<MemoryItem { id, memory, agent_id, 7 more } >
id: string
memory: string
agent_id?: string | null
categories?: Array<string>
conv_id?: string | null
created_at?: string | null
metadata?: unknown
score?: number | null
updated_at?: string | null
user_id?: string | null
stage_timings?: Record<string, number>
MemoryListResponse { count, next, previous, results }

Paginated list envelope.

count: number
results?: Array<MemoryItem { id, memory, agent_id, 7 more } >
id: string
memory: string
agent_id?: string | null
categories?: Array<string>
conv_id?: string | null
created_at?: string | null
metadata?: unknown
score?: number | null
updated_at?: string | null
user_id?: string | null
MemoryDeleteResponse = unknown