Concepts
How MuBit's memory model works, what the learning loop does, and how it compares to vector DBs, prompt caches, and RAG.
MuBit's job is to give AI agents memory that persists, evolves, and is queryable across runs. This page is an evaluator's overview — read it to decide whether MuBit fits your problem before you write any integration code.
The memory model
MuBit organizes memory by entry type. Each type has different retention, retrieval, and access semantics.
| Entry type | What it stores | Lifetime | Recall scope |
|---|---|---|---|
| fact | Atomic statements grounded in observation (e.g. "Customer Taylor uses SSO") | Run-scoped by default | Same session_id + agent_id |
| lesson | Generalized takeaways from runs (e.g. "Always flag bare except:") | Configurable: run / session / global | Cross-session if lesson_scope="global" |
| rule | Hard constraints that must always apply (e.g. "Never PII-log a user.ssn") | Persistent | Cross-session |
| trace | Per-call records of what happened (LLM call, tool call, response) | Run-scoped | Same session_id |
| archive_block | Exact artifacts you'll need byte-for-byte later (diffs, SQL, raw outputs) | Persistent | Cross-session via reference_id |
Storing a fact and asking the wrong session to recall it returns nothing. Storing a global lesson and asking any session keyed by the same user_id returns it. This is the most common shape of "why didn't my recall work" — see SDK helpers → cross-session recall.
More entry types for richer agents
The five types above are what most agents start with. The full taxonomy is larger — multi-agent coordination, tool-call audit, and process-reward learning each have their own entry types.
| Entry type | What it captures |
|---|---|
| observation | Raw agent observations during a run |
| tool_input / tool_output | LLM tool call request and response |
| reflection | Notes a reflection pass produced before lessons crystallize |
| task_result | Outcome of a discrete sub-task |
| log | Free-form structured log entries |
| checkpoint | Snapshot of context for later restore — see SDK methods → helper catalog |
| step_outcome | Per-step success/failure for process-reward learning — see Step-level outcomes |
| mental_model | Curated high-priority summary, retrieved first |
| handoff | Inter-agent task handoff record — see Lane-scoped memory |
| feedback | Verdict on a handoff |
The learning loop
The four-step loop is what differentiates MuBit from a passive store. Read How MuBit works for the full discussion.
- Write
Your agent calls
remember()to store facts, traces, or observations as they happen. - Retrieve
Before the next LLM call,
recall()finds relevant evidence andget_context()assembles a token-budgeted context block. - Reflect
After a run completes,
reflect()extracts reusable lessons from what happened. Fresh lessons start as candidates and are validated before they're trusted — a lesson stays pending until enough evidence accrues, then is promoted (run → session → global) or marked stale. See How MuBit works for details. - Reinforce
record_outcome()feeds success / failure signals back into the lesson store, strengthening what worked and weakening what didn't.
The agent gets better over multiple runs without retraining the model.
How MuBit compares
| If you need… | Reach for… | MuBit's role |
|---|---|---|
| Similarity search over a static corpus | A vector DB (Pinecone, Weaviate, pgvector) | Not the right tool — MuBit is for mutable memory with outcomes |
| Prompt-level caching of identical requests | A prompt cache (Anthropic prompt cache, Helicone) | Orthogonal — MuBit can sit alongside |
| Stateless RAG against a fixed knowledge base | A RAG framework (LlamaIndex, LangChain) | Use the framework + MuBit as its persistent store via the adapters |
| Memory that persists across sessions and evolves | MuBit | The whole product |
| Multi-agent coordination with scoped access | MuBit (register_agent, handoff, feedback) | Native primitives |
Trust and operations
- Authentication. All calls use a bearer API key formatted as
mbt_<instance>_<key_id>_<secret>. The instance segment routes to a region; the key id is safe to log; the secret is not. See Authentication. - Scopes. Each agent registers with explicit
read_scopesandwrite_scopes(fact,lesson,rule,archive_block, etc). The runtime enforces them. - Rate limits. Per-instance, per-route. See Rate limits.
- Audit. Every write produces an activity entry. See Activity & audit trail.
- Data residency / SOC 2. See mubit.ai/security.
Where to go next
The full memory model, control-plane vs. core-plane, query and context controls, and a worked helper-first example.
Decided to integrate? Make your first authenticated call in under 60 seconds.
Plug MuBit into CrewAI, LangGraph, LangChain, LlamaIndex, ADK, Agno, Vercel AI SDK, or MCP.
Plans and per-instance limits.