Skip to main content
Most MuBit integrations should start with remember(). Use raw control.ingest only when you need explicit async ingest behavior, job polling, or bulk payload control. For normal agent memory writes, the helper path is simpler and stays aligned with the current SDK contract.
  1. Keep one stable session_id / run_id per workflow, claim, ticket, or task.
  2. Use remember() for facts, traces, lessons, rules, handoffs, feedback, and tool artifacts.
  3. Use raw control.ingest when you need explicit async ingestion lifecycle control.
  4. Stamp agent_id, intent, and metadata so later diagnose, reflect, and context assembly stay useful.

​
Helper-first write examples

add_data_helper.py
def add_data_helper(client, run_id: str, text: str):
    client.remember(
        session_id=run_id,
        agent_id="support-agent",
        content=text,
        intent="fact",
        metadata={"source": "support", "channel": "ticket"},
    )

​
When raw ingest is still the right choice

Use raw client.control.ingest when you need one of these explicitly:
  • async job polling through get_ingest_job
  • controlled batch writes through /v2/control/ingest or /v2/control/batch_insert
  • wire-level debugging of serialized payloads
  • compatibility with systems that already generate ingest payload JSON directly

​
Failure modes and troubleshooting

SymptomRoot causeFix
Important memory never shows up laterintent or metadata missingTag writes with intent, agent_id, and useful metadata
Helper writes feel too implicitYou need job-level controlSwitch that path to raw control.ingest
Cross-task contaminationsession_id changes per requestKeep one deterministic task/session mapping

​
Next steps