Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content
Build with MuBit

Add data

Use helper-first writes for normal MuBit memory flows, and fall back to raw ingest only when you need explicit async ingest control.

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.

Recommended write 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.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
ℹ️Note

control.ingest and control.batch_insert accept at most 1000 items per request; larger requests return 400 (InvalidArgument) — chunk bigger writes.

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