Write a memory

Tenant to operate on. Omit it and the tenant is resolved from the credential, which is what a tenant- or agent-scoped key already identifies — no prior /whoami call is needed. Supply it to act on a different tenant your credential may read (and for an admin key, which belongs to no single tenant, it is required).

Memory type. Auto-classified by LLM if omitted. Valid values: fact, episode, decision, preference, task, plan, action.

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.

Value metering: tokens and turns the session spent since its previous write, as a hook, plugin or SDK read them from the provider. Leave unset rather than estimate.

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.

Write-mode dial. 'fast' = embed-only, LLM enrichment deferred to the background; 'strong' = full pipeline inline; 'auto' = the system picks. 'strong' also embeds inline regardless of the deployment's embedding mode, which makes it the supported opt-out when a caller must search for what it just wrote — see MemoryOut.metadata.embedding_pending. It costs the embedding provider call on the request path, which is exactly what fast mode's sub-2s p99 visibility SLA exists to avoid, so it is a per-write choice rather than a default to flip.