Memories · Get, update and delete
GET, PATCH and DELETE /api/v1/memories/{memory_id} — operate on one memory.
APIKeyHeaderX-API-Key<token>memory_id*Memory Iduuidtenant_id*Tenant IdSuccessful Response
application/json- response
Full detail for one memory: row fields, entity links, embedding stats.
id*Idtenant_id*Tenant Idfleet_id?string|nullagent_id*Agent Idagent_display_name?string|nullagent_trust_level?integer|nullmemory_type*Memory Typetitle?string|nullcontent*Contentweight?number|nullsource_uri?string|nullrun_id?string|nullmetadata?|nullsystem_metadata?|nullcontent_hash?string|nullcreated_at?string|nullexpires_at?string|nulldeleted_at?string|nullsubject_entity_id?string|nullpredicate?string|nullobject_value?string|nullts_valid_start?string|nullts_valid_end?string|nullstatus*Statusvisibility*Visibilityrecall_count*Recall Countlast_recalled_at?string|nullsupersedes_id?string|nullentity_links?array<>[]embedding_preview?array<number>|nullembedding_stats?|nullcurl -X GET 'https://example.com/api/v1/memories/497f6eca-6276-4993-bfeb-53cbbbba6f08?tenant_id=string'{ "id": "string", "tenant_id": "string", "fleet_id": "string", "agent_id": "string", "agent_display_name": "string", "agent_trust_level": 0, "memory_type": "string", "title": "string", "content": "string", "weight": 0, "source_uri": "string", "run_id": "string", "metadata": {}, "system_metadata": {}, "content_hash": "string", "created_at": "string", "expires_at": "string", "deleted_at": "string", "subject_entity_id": "string", "predicate": "string", "object_value": "string", "ts_valid_start": "string", "ts_valid_end": "string", "status": "string", "visibility": "string", "recall_count": 0, "last_recalled_at": "string", "supersedes_id": "string", "entity_links": [], "embedding_preview": [ 0 ], "embedding_stats": {}}APIKeyHeaderX-API-Key<token>memory_id*Memory Iduuidtenant_id*Tenant Idagent_id?string|nullmetadata_mode?|C7: alias for the body field of the same name. Body wins on conflict. When supplied as a query param without a matching metadata field in the body, returns 422 (same contract as the body-side validator). Provided so SDK callers that thread the toggle through a URL query don't silently get the default merge behaviour.
application/json- body
content?|nullmemory_type?|Memory type. Auto-classified by LLM if omitted. Valid values: fact, episode, decision, preference, task, plan, action.
weight?|nulltitle?|nullstatus?|nullvisibility?|nullmetadata?|Free-form metadata stored with the memory. Keys you send are yours: enrichment never overwrites a summary or tags you supply here, on this write or on any later one — the platform's own versions go to system_metadata instead. Platform-reserved keys (timings, governance verdicts, provenance) are stripped from this dict; send them and they are dropped, not stored.
metadata_mode?|How to apply metadata: merge (default when omitted or null) does a top-level JSONB || merge, preserving keys not present in the patch; replace overwrites the column wholesale.
source_uri?|nullsubject_entity_id?|nullpredicate?|nullobject_value?|nullts_valid_start?|nullts_valid_end?|nullexpires_at?|Optional retention hint. Once this time passes, the row moves to status outdated on the next lifecycle tick and drops out of default search results. Not a hard cutoff: the row remains readable until that tick runs. Distinct from ts_valid_end, which closes a temporal-validity interval rather than expressing retention.
entity_links?array<>|Entity links to add to this memory. Additive, unlike metadata: links already on the memory are kept even when this list does not name them, and re-sending a pair already present leaves its existing role unchanged rather than overwriting it. There is no replace mode and no way to remove a link through this endpoint. An entity_id outside the caller's tenant is rejected with 422.
Successful Response
application/json- response
id*Iduuidtenant_id*Tenant Idfleet_id?string|nullagent_id*Agent Idagent_display_name?string|nullagent_trust_level?integer|nullmemory_type*Memory Typetitle?string|nullcontent*Contentweight*Weightsource_uri*string|nullrun_id*string|nullmetadata*|nullsystem_metadata?|nullcreated_at*Created Atdate-timeexpires_at*|nullentity_links?array<>[]similarity?number|nullscore?number|nullscore_parts?|nullinjected?Injectedfalsesubject_entity_id?|nullpredicate?string|nullobject_value?string|nullts_valid_start?|nullts_valid_end?|nullstatus?Status"active"visibility?Visibility"scope_team"recall_count?Recall Count0last_recalled_at?|nullsupersedes_id?|nullsuperseded_by?array<>|nullconfidence?number|nullis_inferred?Is Inferredfalsescope?|nullusage?|nullcurl -X PATCH 'https://example.com/api/v1/memories/497f6eca-6276-4993-bfeb-53cbbbba6f08?tenant_id=string' \ -H 'Content-Type: application/json' \ -d '{}'{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "tenant_id": "string", "fleet_id": "string", "agent_id": "string", "agent_display_name": "string", "agent_trust_level": 0, "memory_type": "string", "title": "string", "content": "string", "weight": 0, "source_uri": "string", "run_id": "string", "metadata": {}, "system_metadata": {}, "created_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z", "entity_links": [], "similarity": 0, "score": 0, "score_parts": { "vec_sim": 0, "fts_score": 0, "freshness": 0, "entity_boost": 0, "recall_boost": 0, "temporal_boost": 0, "status_penalty": 0, "rerank": 0 }, "injected": false, "subject_entity_id": "2f43e1a1-7cec-4ccf-9421-4ab19090ca45", "predicate": "string", "object_value": "string", "ts_valid_start": "2019-08-24T14:15:22Z", "ts_valid_end": "2019-08-24T14:15:22Z", "status": "active", "visibility": "scope_team", "recall_count": 0, "last_recalled_at": "2019-08-24T14:15:22Z", "supersedes_id": "8149cd94-4e90-4a99-91f5-a3e0f9b829dc", "superseded_by": [ { "old_memory_id": "07606bd2-b9bc-468a-8200-790e8b7345cf", "old_status": "string", "reason": "string", "old_content_preview": "string", "direction": "canonical" } ], "confidence": 0, "is_inferred": false, "scope": {}, "usage": { "memories_stored": 0, "memories_limit": 0, "writes_remaining": 0 }}APIKeyHeaderX-API-Key<token>memory_id*Memory Iduuidtenant_id*Tenant Idagent_id?string|nullSuccessful Response
curl -X DELETE 'https://example.com/api/v1/memories/497f6eca-6276-4993-bfeb-53cbbbba6f08?tenant_id=string'