MEmetacognition
ingestion-memory

Unified dual-write ingest (active memory + HelixDB)

Fan a list of conversational turns out to active memory + HelixDB.

scope accepts BOTH shapes (shared contract with the SDK):

  • legacy tenant dict {org_id, user_id, session_id} -> unchanged behavior;
  • hierarchical write-scope string "<kind>:<value>" -> validated against the caller's visible scopes (403 with explanatory body otherwise) and stamped on every HelixDB write (X-Scope-Id). org/user then come from the auth context; the session is the body's top-level session_id when given (the SDK sends it alongside a string scope), else the auth context's, else "default-session".
post/ingestion/memory

Request

Request body

timezonestring nullable

The caller's timezone (IANA name, e.g. Europe/Berlin, or +HH:MM) for natural-language turn timestamps such as "yesterday 3pm"; default UTC

session_idstring nullable

Explicit session id, honored on the string-scope path (the SDK sends it alongside a string scope; the legacy dict carries its own)

agent_idstring nullable

Agent identifier for the active-memory episode; falls back to default-agent if unset (same default as /recall)

supersedesstring[] nullable

turn_ids this write CORRECTS. Each is retired once the new turns are durably stored, so a correction replaces the earlier text instead of sitting beside it. A turn id cannot be edited in place: its id is a hash of its own content, so a new version is always a new id, and this is what links them.

inactivity_timeout_secondsinteger nullable

Idle time in seconds after which this active-memory episode is closed and consolidated into long-term memory. Stored on the episode (later writes without it keep it). Omitted: the org default, else 1800 (30 min). Bounds: 300-86400.

metadataobject nullable

Free-form caller metadata (currently unused)

Response

Successful Response

job_idstring required

Per-call observability id (uuid hex)

active_fragment_idsstring[]

Fragment ids written to active memory (turn first, then observations)

turn_idsstring[]

Turn id (the item's content hash) of each stored item, parallel to active_fragment_ids. This is the handle for retiring a remembered turn (DELETE /ingestion/memory/turns/{turn_id}); the fragment id is a one-way hash of scope+turn id and cannot be converted back.

not_stored_forgottenstring[]

turn_ids in this request that were NOT stored because their owner had forgotten them (a resend of history, a retried batch). They are refused rather than brought back; remember new text to store it again.

supersededstring[]

turn_ids this write retired, from the request's supersedes

supersede_errorsstring[]

Why a requested supersede did not complete. Non-empty means the OLD turn may still answer recall alongside the new one — the new turns are stored regardless, so this is never a reason to retry the whole write.

passive_job_idstring nullable

Reserved for future async passive job tracking

Changes

No recorded changes to this operation across all 1 revision of this API.