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 client.memory.remember() (or the global mubit.remember() inside a run).

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 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, kind, 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.memory.remember(
        text,
        kind="fact",
        metadata={"source": "support", "channel": "ticket"},
        run_id=run_id,
        agent_id="support-agent",
    )

When raw ingest is still the right choice

Use raw client.raw.invoke("control.ingest", payload) when you need one of these explicitly:

  • async job polling through client.jobs.get(job_id, run_id=...) (an IngestJob with done, status, error)
  • 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 laterkind or metadata missingTag writes with kind, agent, and useful metadata
Helper writes feel too implicitYou need job-level controlSwitch that path to raw control.ingest
Cross-task contaminationrun_id changes per requestKeep one deterministic task/run mapping

Next steps