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

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

MuBit architecture: Agent writes memory with remember(), retrieves context with recall()/getContext(), sends enriched prompt to LLM, then feeds outcomes back through recordOutcome() and reflect() to improve over time.

The core loop has four steps:

  1. Write

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

  2. Retrieve

    Before the next LLM call, recall() finds relevant evidence and getContext() assembles a token-budgeted context block with rules, lessons, and facts.

  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. Reinforce

    recordOutcome() 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.

SurfaceResponsibilityTypical use
controlMemory lifecycle, context assembly, diagnostics, learning loop, coordination, and planning stateDefault application path
coreDirect search, sessions, scratch memory, and specialized low-level primitivesAdvanced or specialized features
authUser and API key lifecycleAdmin and provisioning workflows
  • Start with helper-first control usage: remember, recall, getContext, checkpoint, reflect, recordOutcome.
  • Introduce core.* only when you need direct-lane or branch/session primitives.
  • Keep auth.* out of end-user request handlers.

Execution contract

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

Query and context controls that matter

ControlWhy it matters
run_id / session_idDefines the memory scope
mode on contextChooses full, summary, or sectioned context assembly
max_token_budgetKeeps context within the active model budget
entry_typesRestricts retrieval to facts, lessons, rules, traces, and other types
diagnose / memory_healthExplains weak retrieval and low-quality memory

Minimal helper-first example

helper_flow.py
client.remember(
    session_id="support:acme:ticket-42",
    agent_id="support-agent",
    content="Customer Taylor prefers concise Friday updates.",
    intent="fact",
)
 
answer = client.recall(
    session_id="support:acme:ticket-42",
    query="What preference do we already know for Taylor?",
)
 
context = client.get_context(
    session_id="support:acme:ticket-42",
    query="Draft the next response.",
    mode="summary",
    max_token_budget=300,
)

Failure modes and troubleshooting

SymptomRoot causeFix
Recent write missing from later contextRaw ingest completion was ignoredGate reads on done=true or use remember()
Context is too long or too noisyNo explicit context mode or budgetUse getContext() / get_context() with mode and max_token_budget
The system does not improve across attemptsReflection or outcomes are missingPair reflect() with recordOutcome()
Security boundary driftauth or direct core calls leaked into the request pathKeep application logic on the control plane

Deep dives

Next steps