How Mubit works

How your agents go from stateless to self-improving with Mubit's memory loop.

Mubit is a memory engine for AI agents. It stores what your agents learn, retrieves the right context before each LLM call, and extracts reusable lessons so agents improve over time. Everything runs behind a single control-plane boundary — your agent talks to Mubit, Mubit talks to storage.

Overview

The core loop has four steps:

1. 1
   Write

   Your agent calls remember() to store facts, traces, or observations as they happen.

2. 2
   Retrieve

   Before the next LLM call, recall() finds relevant evidence and context() assembles a token-budgeted context block with rules, lessons, and facts; the wrappers inject it into the system message for you.

3. 3
   Reflect

   After a run completes, reflect() extracts reusable lessons from what happened. Recurring lessons get promoted from run-scoped to session-scoped to global. A freshly reflected lesson may start as a pending candidate and is only promoted to active once its evidence score crosses the acceptance threshold (default 0.6; low-scoring ones are rejected at or below 0.25 and down-weighted), so newly learned lessons are not always surfaced instantly. This validation gate is on by default and can be disabled with MUBIT_CONTROL_LESSON_VALIDATION_ENABLED.

4. 4
   Reinforce

   outcome() feeds success/failure signals back into the lesson store, strengthening what worked and weakening what didn't.

Over multiple runs, agents accumulate lessons that make them better at the task — without retraining the LLM.

Component model

Mubit exposes three API surfaces. Most application logic belongs on the control plane.

• Start with the global helpers and the client.memory, client.snapshots, client.lessons and client.outcomes namespaces.
• Introduce client.raw.invoke("core.<op>", ...) only when you need direct-lane or branch/session primitives.
• Keep client.admin.* out of end-user request handlers.

Execution contract

1. Write memory with client.memory.remember() or raw control.ingest.
2. If you use raw ingest, poll client.jobs.get(job_id, run_id=...) until done is true before freshness-critical reads.
3. Read with client.memory.recall() or assemble context with client.memory.context().
4. Checkpoint before compaction.
5. Reflect and record outcomes when the attempt finishes.

Query and context controls that matter

Minimal helper-first example

client.memory.remember(
    "Customer Taylor prefers concise Friday updates.",
    kind="fact",
    run_id="support:acme:ticket-42",
    agent_id="support-agent",
)
 
answer = client.memory.recall(
    "What preference do we already know for Taylor?",
    run_id="support:acme:ticket-42",
)
 
context = client.memory.context(
    "Draft the next response.",
    lane="legacy",
    mode="summary",
    max_token_budget=300,
    run_id="support:acme:ticket-42",
)

Failure modes and troubleshooting

Deep dives

• Data-plane memory component
• Control-plane state runtime component

Next steps

• Extend the same project with Add data.
• Extend retrieval behavior with Retrieve data.