# Memories ## Add Memory `client.memories.add(MemoryAddParamsbody, RequestOptionsoptions?): MemoryAddResponse` **post** `/v1/memories/add/` Ingest memories. `mode=chat` pairs messages; `mode=import` is bulk. Workspace/CB write target lives in `metadata.workspace_id` / `metadata.cb_id` (absent → hosted single-tenant). ### Parameters - `body: MemoryAddParams` - `messages: Array` - `content: string` - `role: string` - `date?: string | null` - `dia_id?: string | null` - `agent_id?: string | null` - `config_overrides?: unknown` - `conv_id?: string | null` - `custom_instructions?: string | null` - `flush_after?: boolean` - `flush_hint?: "force" | null` - `"force"` - `infer?: boolean` - `metadata?: unknown` - `mode?: "chat" | "import"` - `"chat"` - `"import"` - `user_id?: string | null` ### Returns - `MemoryAddResponse` 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` - `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_id: string` - `artifact_ids?: Array` - `conv_id?: string | null` - `ended_at?: string | null` - `fact_ids?: Array` - `started_at?: string | null` - `summary?: string | null` - `title?: string | null` - `stage_timings?: Record` - `message?: string` - `mode?: "chat" | "import"` - `"chat"` - `"import"` - `results?: Array` - `id: string` - `memory: string` - `agent_id?: string | null` - `categories?: Array` - `conv_id?: string | null` - `created_at?: string | null` - `metadata?: unknown` - `score?: number | null` - `updated_at?: string | null` - `user_id?: string | null` - `stage_timings?: Record` - `status?: string` - `stored_artifacts?: Array` - `artifact_id: string` - `artifact_type?: string | null` - `content?: string | null` - `conv_id?: string | null` - `created_at?: string | null` - `descriptor_fact_ids?: Array` - `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_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` - `source_event_ids?: Array` - `source_role?: string | null` - `status?: string | null` - `supersedes?: string | null` - `superseded_fact_ids?: Array>` ### Example ```typescript import XtraceMemoryManager from 'xtrace-memory-manager'; const client = new XtraceMemoryManager({ apiKey: process.env['XTRACE_MEMORY_MANAGER_API_KEY'], // This is the default and can be omitted orgID: process.env['XTRACE_MEMORY_MANAGER_ORG_ID'], // This is the default and can be omitted }); const response = await client.memories.add({ messages: [{ content: 'content', role: 'role' }] }); console.log(response.consolidation_id_mapping); ``` #### Response ```json { "consolidation_id_mapping": { "foo": "string" }, "flush_result": { "episodes": [ { "episode_id": "episode_id", "artifact_ids": [ "string" ], "conv_id": "conv_id", "ended_at": "ended_at", "fact_ids": [ "string" ], "started_at": "started_at", "summary": "summary", "title": "title" } ], "stage_timings": { "foo": 0 } }, "message": "message", "mode": "chat", "results": [ { "id": "id", "memory": "memory", "agent_id": "agent_id", "categories": [ "string" ], "conv_id": "conv_id", "created_at": "created_at", "metadata": {}, "score": 0, "updated_at": "updated_at", "user_id": "user_id" } ], "stage_timings": { "foo": 0 }, "status": "status", "stored_artifacts": [ { "artifact_id": "artifact_id", "artifact_type": "artifact_type", "content": "content", "conv_id": "conv_id", "created_at": "created_at", "descriptor_fact_ids": [ "string" ], "episode_id": "episode_id", "is_latest": true, "name": "name", "parent_artifact_id": "parent_artifact_id", "rationale": "rationale", "root_artifact_id": "root_artifact_id", "score": 0, "summary": "summary", "version": 0 } ], "stored_facts": [ { "fact_id": "fact_id", "text": "text", "change_reason": "change_reason", "change_type": "change_type", "consolidated_at": "consolidated_at", "conv_id": "conv_id", "created_at": "created_at", "episode_id": "episode_id", "event_date": "event_date", "fact_type": "fact_type", "metadata": {}, "origin": "origin", "root_artifact_id": "root_artifact_id", "score": 0, "source_artifact_id": "source_artifact_id", "source_dia_ids": [ "string" ], "source_event_ids": [ "string" ], "source_role": "source_role", "status": "status", "supersedes": "supersedes" } ], "superseded_fact_ids": [ [ {}, {} ] ] } ``` ## Search Memory `client.memories.search(MemorySearchParamsbody, RequestOptionsoptions?): MemorySearchResponse` **post** `/v1/memories/search/` Search memories. `mode=flat` returns flat results; `mode=context` runs the full retrieval agent and returns assembled context. ### Parameters - `body: MemorySearchParams` - `filters: unknown` - `query: string` - `char_budget?: number | null` - `conv_history?: Array | null` - `conv_id?: string | null` - `exclude_artifact_ids?: Array | null` - `mode?: "flat" | "context"` - `"flat"` - `"context"` - `rerank?: boolean` - `threshold?: number` - `top_k?: number` ### Returns - `MemorySearchResponse` 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_id: string` - `artifact_type?: string | null` - `content?: string | null` - `conv_id?: string | null` - `created_at?: string | null` - `descriptor_fact_ids?: Array` - `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_id: string` - `artifact_type?: string | null` - `content?: string | null` - `conv_id?: string | null` - `created_at?: string | null` - `descriptor_fact_ids?: Array` - `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_id: string` - `artifact_ids?: Array` - `conv_id?: string | null` - `ended_at?: string | null` - `fact_ids?: Array` - `started_at?: string | null` - `summary?: string | null` - `title?: string | null` - `facts?: Array` - `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` - `source_event_ids?: Array` - `source_role?: string | null` - `status?: string | null` - `supersedes?: string | null` - `mode?: "flat" | "context"` - `"flat"` - `"context"` - `results?: Array` - `id: string` - `memory: string` - `agent_id?: string | null` - `categories?: Array` - `conv_id?: string | null` - `created_at?: string | null` - `metadata?: unknown` - `score?: number | null` - `updated_at?: string | null` - `user_id?: string | null` - `stage_timings?: Record` ### Example ```typescript import XtraceMemoryManager from 'xtrace-memory-manager'; const client = new XtraceMemoryManager({ apiKey: process.env['XTRACE_MEMORY_MANAGER_API_KEY'], // This is the default and can be omitted orgID: process.env['XTRACE_MEMORY_MANAGER_ORG_ID'], // This is the default and can be omitted }); const response = await client.memories.search({ filters: {}, query: 'x', }); console.log(response.all_retrieved_artifacts); ``` #### Response ```json { "all_retrieved_artifacts": [ { "artifact_id": "artifact_id", "artifact_type": "artifact_type", "content": "content", "conv_id": "conv_id", "created_at": "created_at", "descriptor_fact_ids": [ "string" ], "episode_id": "episode_id", "is_latest": true, "name": "name", "parent_artifact_id": "parent_artifact_id", "rationale": "rationale", "root_artifact_id": "root_artifact_id", "score": 0, "summary": "summary", "version": 0 } ], "artifacts": [ { "artifact_id": "artifact_id", "artifact_type": "artifact_type", "content": "content", "conv_id": "conv_id", "created_at": "created_at", "descriptor_fact_ids": [ "string" ], "episode_id": "episode_id", "is_latest": true, "name": "name", "parent_artifact_id": "parent_artifact_id", "rationale": "rationale", "root_artifact_id": "root_artifact_id", "score": 0, "summary": "summary", "version": 0 } ], "context": "context", "episodes": [ { "episode_id": "episode_id", "artifact_ids": [ "string" ], "conv_id": "conv_id", "ended_at": "ended_at", "fact_ids": [ "string" ], "started_at": "started_at", "summary": "summary", "title": "title" } ], "facts": [ { "fact_id": "fact_id", "text": "text", "change_reason": "change_reason", "change_type": "change_type", "consolidated_at": "consolidated_at", "conv_id": "conv_id", "created_at": "created_at", "episode_id": "episode_id", "event_date": "event_date", "fact_type": "fact_type", "metadata": {}, "origin": "origin", "root_artifact_id": "root_artifact_id", "score": 0, "source_artifact_id": "source_artifact_id", "source_dia_ids": [ "string" ], "source_event_ids": [ "string" ], "source_role": "source_role", "status": "status", "supersedes": "supersedes" } ], "mode": "flat", "results": [ { "id": "id", "memory": "memory", "agent_id": "agent_id", "categories": [ "string" ], "conv_id": "conv_id", "created_at": "created_at", "metadata": {}, "score": 0, "updated_at": "updated_at", "user_id": "user_id" } ], "stage_timings": { "foo": 0 } } ``` ## List Memories `client.memories.list(MemoryListParamsparams, RequestOptionsoptions?): MemoryListResponse` **post** `/v1/memories/` List active memories matching `filters`. Paginated. ### Parameters - `params: MemoryListParams` - `filters: unknown` Body param - `page?: number` Query param - `page_size?: number` Query param ### Returns - `MemoryListResponse` Paginated list envelope. - `count: number` - `next?: string | null` - `previous?: string | null` - `results?: Array` - `id: string` - `memory: string` - `agent_id?: string | null` - `categories?: Array` - `conv_id?: string | null` - `created_at?: string | null` - `metadata?: unknown` - `score?: number | null` - `updated_at?: string | null` - `user_id?: string | null` ### Example ```typescript import XtraceMemoryManager from 'xtrace-memory-manager'; const client = new XtraceMemoryManager({ apiKey: process.env['XTRACE_MEMORY_MANAGER_API_KEY'], // This is the default and can be omitted orgID: process.env['XTRACE_MEMORY_MANAGER_ORG_ID'], // This is the default and can be omitted }); const memories = await client.memories.list({ filters: {} }); console.log(memories.count); ``` #### Response ```json { "count": 0, "next": "next", "previous": "previous", "results": [ { "id": "id", "memory": "memory", "agent_id": "agent_id", "categories": [ "string" ], "conv_id": "conv_id", "created_at": "created_at", "metadata": {}, "score": 0, "updated_at": "updated_at", "user_id": "user_id" } ] } ``` ## Get Memory By Id `client.memories.retrieve(stringmemoryID, RequestOptionsoptions?): MemoryItem` **get** `/v1/memories/{memory_id}/` Get one memory by id. Scope resolved from the row itself. ### Parameters - `memoryID: string` ### Returns - `MemoryItem` One result item — used in flat search `results` and listings. - `id: string` - `memory: string` - `agent_id?: string | null` - `categories?: Array` - `conv_id?: string | null` - `created_at?: string | null` - `metadata?: unknown` - `score?: number | null` - `updated_at?: string | null` - `user_id?: string | null` ### Example ```typescript import XtraceMemoryManager from 'xtrace-memory-manager'; const client = new XtraceMemoryManager({ apiKey: process.env['XTRACE_MEMORY_MANAGER_API_KEY'], // This is the default and can be omitted orgID: process.env['XTRACE_MEMORY_MANAGER_ORG_ID'], // This is the default and can be omitted }); const memoryItem = await client.memories.retrieve('memory_id'); console.log(memoryItem.id); ``` #### Response ```json { "id": "id", "memory": "memory", "agent_id": "agent_id", "categories": [ "string" ], "conv_id": "conv_id", "created_at": "created_at", "metadata": {}, "score": 0, "updated_at": "updated_at", "user_id": "user_id" } ``` ## Patch Memory `client.memories.update(stringmemoryID, MemoryUpdateParamsbody, RequestOptionsoptions?): MemoryItem` **patch** `/v1/memories/{memory_id}/` Update memory text — supersedes old + creates new. Metadata-only patches (no `text`) are rejected with 400; the row's metadata is derived from extraction and isn't editable from the API yet. ### Parameters - `memoryID: string` - `body: MemoryUpdateParams` - `metadata?: unknown` - `text?: string | null` ### Returns - `MemoryItem` One result item — used in flat search `results` and listings. - `id: string` - `memory: string` - `agent_id?: string | null` - `categories?: Array` - `conv_id?: string | null` - `created_at?: string | null` - `metadata?: unknown` - `score?: number | null` - `updated_at?: string | null` - `user_id?: string | null` ### Example ```typescript import XtraceMemoryManager from 'xtrace-memory-manager'; const client = new XtraceMemoryManager({ apiKey: process.env['XTRACE_MEMORY_MANAGER_API_KEY'], // This is the default and can be omitted orgID: process.env['XTRACE_MEMORY_MANAGER_ORG_ID'], // This is the default and can be omitted }); const memoryItem = await client.memories.update('memory_id'); console.log(memoryItem.id); ``` #### Response ```json { "id": "id", "memory": "memory", "agent_id": "agent_id", "categories": [ "string" ], "conv_id": "conv_id", "created_at": "created_at", "metadata": {}, "score": 0, "updated_at": "updated_at", "user_id": "user_id" } ``` ## Delete Memory `client.memories.delete(stringmemoryID, RequestOptionsoptions?): MemoryDeleteResponse` **delete** `/v1/memories/{memory_id}/` Delete Memory ### Parameters - `memoryID: string` ### Returns - `MemoryDeleteResponse = unknown` ### Example ```typescript import XtraceMemoryManager from 'xtrace-memory-manager'; const client = new XtraceMemoryManager({ apiKey: process.env['XTRACE_MEMORY_MANAGER_API_KEY'], // This is the default and can be omitted orgID: process.env['XTRACE_MEMORY_MANAGER_ORG_ID'], // This is the default and can be omitted }); const memory = await client.memories.delete('memory_id'); console.log(memory); ``` #### Response ```json {} ``` ## Domain Types ### Artifact - `Artifact` - `artifact_id: string` - `artifact_type?: string | null` - `content?: string | null` - `conv_id?: string | null` - `created_at?: string | null` - `descriptor_fact_ids?: Array` - `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` - `episode_id: string` - `artifact_ids?: Array` - `conv_id?: string | null` - `ended_at?: string | null` - `fact_ids?: Array` - `started_at?: string | null` - `summary?: string | null` - `title?: string | null` ### Fact - `Fact` - `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` - `source_event_ids?: Array` - `source_role?: string | null` - `status?: string | null` - `supersedes?: string | null` ### Memory Item - `MemoryItem` One result item — used in flat search `results` and listings. - `id: string` - `memory: string` - `agent_id?: string | null` - `categories?: Array` - `conv_id?: string | null` - `created_at?: string | null` - `metadata?: unknown` - `score?: number | null` - `updated_at?: string | null` - `user_id?: string | null` ### Memory Add Response - `MemoryAddResponse` 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` - `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_id: string` - `artifact_ids?: Array` - `conv_id?: string | null` - `ended_at?: string | null` - `fact_ids?: Array` - `started_at?: string | null` - `summary?: string | null` - `title?: string | null` - `stage_timings?: Record` - `message?: string` - `mode?: "chat" | "import"` - `"chat"` - `"import"` - `results?: Array` - `id: string` - `memory: string` - `agent_id?: string | null` - `categories?: Array` - `conv_id?: string | null` - `created_at?: string | null` - `metadata?: unknown` - `score?: number | null` - `updated_at?: string | null` - `user_id?: string | null` - `stage_timings?: Record` - `status?: string` - `stored_artifacts?: Array` - `artifact_id: string` - `artifact_type?: string | null` - `content?: string | null` - `conv_id?: string | null` - `created_at?: string | null` - `descriptor_fact_ids?: Array` - `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_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` - `source_event_ids?: Array` - `source_role?: string | null` - `status?: string | null` - `supersedes?: string | null` - `superseded_fact_ids?: Array>` ### Memory Search Response - `MemorySearchResponse` 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_id: string` - `artifact_type?: string | null` - `content?: string | null` - `conv_id?: string | null` - `created_at?: string | null` - `descriptor_fact_ids?: Array` - `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_id: string` - `artifact_type?: string | null` - `content?: string | null` - `conv_id?: string | null` - `created_at?: string | null` - `descriptor_fact_ids?: Array` - `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_id: string` - `artifact_ids?: Array` - `conv_id?: string | null` - `ended_at?: string | null` - `fact_ids?: Array` - `started_at?: string | null` - `summary?: string | null` - `title?: string | null` - `facts?: Array` - `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` - `source_event_ids?: Array` - `source_role?: string | null` - `status?: string | null` - `supersedes?: string | null` - `mode?: "flat" | "context"` - `"flat"` - `"context"` - `results?: Array` - `id: string` - `memory: string` - `agent_id?: string | null` - `categories?: Array` - `conv_id?: string | null` - `created_at?: string | null` - `metadata?: unknown` - `score?: number | null` - `updated_at?: string | null` - `user_id?: string | null` - `stage_timings?: Record` ### Memory List Response - `MemoryListResponse` Paginated list envelope. - `count: number` - `next?: string | null` - `previous?: string | null` - `results?: Array` - `id: string` - `memory: string` - `agent_id?: string | null` - `categories?: Array` - `conv_id?: string | null` - `created_at?: string | null` - `metadata?: unknown` - `score?: number | null` - `updated_at?: string | null` - `user_id?: string | null` ### Memory Delete Response - `MemoryDeleteResponse = unknown`