API Reference

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Memories

Add Memory

POST/v1/memories/add/

Search Memory

POST/v1/memories/search/

List Memories

POST/v1/memories/

Get Memory By Id

GET/v1/memories/{memory_id}/

Patch Memory

PATCH/v1/memories/{memory_id}/

Delete Memory

DELETE/v1/memories/{memory_id}/

ModelsExpand Collapse

Artifact object { artifact_id, artifact_type, content, 12 more }

artifact_id: string

artifact_type: optional string

content: optional string

conv_id: optional string

created_at: optional string

descriptor_fact_ids: optional array of string

episode_id: optional string

is_latest: optional boolean

name: optional string

parent_artifact_id: optional string

rationale: optional string

root_artifact_id: optional string

score: optional number

summary: optional string

version: optional number

Episode object { episode_id, artifact_ids, conv_id, 5 more }

episode_id: string

artifact_ids: optional array of string

conv_id: optional string

ended_at: optional string

fact_ids: optional array of string

started_at: optional string

summary: optional string

title: optional string

Fact object { fact_id, text, change_reason, 17 more }

fact_id: string

text: string

change_reason: optional string

change_type: optional string

consolidated_at: optional string

conv_id: optional string

created_at: optional string

episode_id: optional string

event_date: optional string

fact_type: optional string

metadata: optional unknown

origin: optional string

root_artifact_id: optional string

score: optional number

source_artifact_id: optional string

source_dia_ids: optional array of string

source_event_ids: optional array of string

source_role: optional string

status: optional string

supersedes: optional string

MemoryItem object { id, memory, agent_id, 7 more }

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

id: string

memory: string

agent_id: optional string

categories: optional array of string

conv_id: optional string

created_at: optional string

metadata: optional unknown

score: optional number

updated_at: optional string

user_id: optional string

MemoryAddResponse object { 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: optional map[string]

flush_result: optional object { episodes, stage_timings }

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: optional array of Episode { episode_id, artifact_ids, conv_id, 5 more }

episode_id: string

artifact_ids: optional array of string

conv_id: optional string

ended_at: optional string

fact_ids: optional array of string

started_at: optional string

summary: optional string

title: optional string

stage_timings: optional map[number]

message: optional string

mode: optional "chat" or "import"

One of the following:

"chat"

"import"

results: optional array of MemoryItem { id, memory, agent_id, 7 more }

id: string

memory: string

agent_id: optional string

categories: optional array of string

conv_id: optional string

created_at: optional string

metadata: optional unknown

score: optional number

updated_at: optional string

user_id: optional string

stage_timings: optional map[number]

status: optional string

stored_artifacts: optional array of Artifact { artifact_id, artifact_type, content, 12 more }

artifact_id: string

artifact_type: optional string

content: optional string

conv_id: optional string

created_at: optional string

descriptor_fact_ids: optional array of string

episode_id: optional string

is_latest: optional boolean

name: optional string

parent_artifact_id: optional string

rationale: optional string

root_artifact_id: optional string

score: optional number

summary: optional string

version: optional number

stored_facts: optional array of Fact { fact_id, text, change_reason, 17 more }

fact_id: string

text: string

change_reason: optional string

change_type: optional string

consolidated_at: optional string

conv_id: optional string

created_at: optional string

episode_id: optional string

event_date: optional string

fact_type: optional string

metadata: optional unknown

origin: optional string

root_artifact_id: optional string

score: optional number

source_artifact_id: optional string

source_dia_ids: optional array of string

source_event_ids: optional array of string

source_role: optional string

status: optional string

supersedes: optional string

superseded_fact_ids: optional array of array of unknown

MemorySearchResponse object { 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: optional array of Artifact { artifact_id, artifact_type, content, 12 more }

artifact_id: string

artifact_type: optional string

content: optional string

conv_id: optional string

created_at: optional string

descriptor_fact_ids: optional array of string

episode_id: optional string

is_latest: optional boolean

name: optional string

parent_artifact_id: optional string

rationale: optional string

root_artifact_id: optional string

score: optional number

summary: optional string

version: optional number

artifacts: optional array of Artifact { artifact_id, artifact_type, content, 12 more }

artifact_id: string

artifact_type: optional string

content: optional string

conv_id: optional string

created_at: optional string

descriptor_fact_ids: optional array of string

episode_id: optional string

is_latest: optional boolean

name: optional string

parent_artifact_id: optional string

rationale: optional string

root_artifact_id: optional string

score: optional number

summary: optional string

version: optional number

context: optional string

episodes: optional array of Episode { episode_id, artifact_ids, conv_id, 5 more }

episode_id: string

artifact_ids: optional array of string

conv_id: optional string

ended_at: optional string

fact_ids: optional array of string

started_at: optional string

summary: optional string

title: optional string

facts: optional array of Fact { fact_id, text, change_reason, 17 more }

fact_id: string

text: string

change_reason: optional string

change_type: optional string

consolidated_at: optional string

conv_id: optional string

created_at: optional string

episode_id: optional string

event_date: optional string

fact_type: optional string

metadata: optional unknown

origin: optional string

root_artifact_id: optional string

score: optional number

source_artifact_id: optional string

source_dia_ids: optional array of string

source_event_ids: optional array of string

source_role: optional string

status: optional string

supersedes: optional string

mode: optional "flat" or "context"

One of the following:

"flat"

"context"

results: optional array of MemoryItem { id, memory, agent_id, 7 more }

id: string

memory: string

agent_id: optional string

categories: optional array of string

conv_id: optional string

created_at: optional string

metadata: optional unknown

score: optional number

updated_at: optional string

user_id: optional string

stage_timings: optional map[number]

MemoryListResponse object { count, next, previous, results }

Paginated list envelope.

count: number

next: optional string

previous: optional string

results: optional array of MemoryItem { id, memory, agent_id, 7 more }

id: string

memory: string

agent_id: optional string

categories: optional array of string

conv_id: optional string

created_at: optional string

metadata: optional unknown

score: optional number

updated_at: optional string

user_id: optional string

MemoryDeleteResponse = unknown