The memory model
Mubit's four cognitive memory types, the full entry-type taxonomy, who writes each type, and how assembled context prioritizes them.
Everything a Mubit-backed agent remembers is stored as a typed entry. Read this page when you're deciding what to write (which entry type fits the thing your agent just learned) or debugging what came back (why a lesson outranked a trace in assembled context). The Concepts overview covers the five types most agents start with; this page is the complete map.
The mental model has two axes. The cognitive type says what kind of knowledge something is — a fact about the world, a record of what happened, a way of doing things, or in-flight task state. The entry type is the concrete unit you write and retrieve. Every entry type maps onto one cognitive type, and that mapping determines how the entry is retained, retrieved, and prioritized.
The four cognitive memory types
| Cognitive type | What it holds | Nimbus example |
|---|---|---|
| Semantic | Facts and knowledge about the world, independent of any one episode | "Acme Corp is on the Scale plan" |
| Episodic | Traces and history — what happened, when, in which run | The full record of how Ari resolved ticket 1042 |
| Procedural | Workflows, skills, and rules — how to do things and what must never happen | The step-by-step CSV-export fix; "never issue refunds above $500 without review" |
| Working | In-flight state and attention for the current task | Which ticket Ari is triaging right now, and what's been tried so far |
Semantic, episodic, and procedural entries live in long-term memory and survive runs. Working memory is a separate, mutable, run-scoped store — see Working memory vs long-term memory for the full comparison.
Entry types
The complete taxonomy, with who typically writes each type and who reads it back:
| Entry type | Cognitive type | Written by | Typical reader |
|---|---|---|---|
fact | Semantic | You (remember(intent="fact")) or ingestion classification | Context assembly, recall |
mental_model | Semantic | Runtime — consolidation promotes recurring observations | Context assembly — searched and injected first |
trace | Episodic | Ingestion (captured run activity) | Reflection; recall when reconstructing what happened |
archive_block | Episodic (exact) | You (archive()) | You, via dereference() |
observation | Episodic | You or ingestion | Reflection; consolidation into mental models |
tool_input / tool_output | Episodic | Ingestion (auto-captured tool calls) or you | Reflection |
reflection | Episodic | Reflection pass | Later reflection, before lessons crystallize |
task_result | Episodic | You | Reflection; recall |
step_outcome | Episodic | You (record_step_outcome()) | Process-reward learning during reflection |
handoff | Episodic | You (handoff()) | The receiving agent |
feedback | Episodic | You (feedback()) | The agent that made the handoff; reflection |
log | Episodic | You | Audit and debugging |
lesson | Procedural | Reflection (reflect()), or you explicitly | Context assembly — injected ahead of facts |
rule | Procedural | You | Context assembly — always-on constraints |
workflow | Procedural | Runtime — induced from successful traces | Context assembly — reusable procedures |
checkpoint | Working (durable snapshot) | You (checkpoint()) | You, when restoring after compaction |
See the helper catalog for the methods named above.
The taxonomy in one support ticket
At Nimbus, Ari (the support agent) picks up ticket 1042 — Acme Corp's CSV export is timing out. One ticket touches five entry types:
- While Ari works, its in-flight state — active ticket, hypotheses tried, next step — lives in working memory, not in a durable entry at all.
- Along the way Ari confirms the account details and stores "Acme Corp is on the Scale plan" as a
fact— true independent of this ticket, useful in every future one. - When the ticket resolves, the full record of what happened — the reproduction, the row-count check, the fix — persists as a
trace. - Reflection over that trace extracts the reusable insight as a
lesson: "When an export times out, check the report row count before retrying — over 500k rows needs the batched exporter." - After the same fix works across several tickets, consolidation induces a
workflow: the placeholder-abstracted, step-by-step CSV-export fix procedure any agent can follow.
Same episode, five different retention and retrieval behaviors — that's the point of typing entries instead of storing undifferentiated text.
Context priority
When get_context() assembles a context block, evidence is grouped into sections with a fixed priority order. Distilled, high-trust knowledge comes first; raw history comes last:
Within a section, entries sort by importance (critical > high > medium > low). Under a token budget, low-priority sections are the first to be trimmed. An abridged assembled block for Ari looks like:
## Mental Models
- Acme Corp support profile: Scale plan, CSV-heavy usage, exports peak on Mondays
## Active Rules
- Never issue refunds above $500 without reviewer approval
## Lessons Learned
- When an export times out, check the report row count before retrying
## Known Facts
- Acme Corp is on the Scale plan (since May 3)
## Current State
- active_ticket = "TCK-1042"
- attempts = 2The section names are the real ones the runtime emits; the layout is abridged. Working memory appearing near the end is deliberate — it is situational scratch state, not validated knowledge.
Verbatim vs semantic entries
One entry type is retrieved differently from all the others. archive_block is verbatim: stored exactly, addressed by reference_id, and fetched back byte-for-byte with dereference() — the right tool for diffs, generated SQL, or raw outputs you'll re-execute. Every other entry type is semantic: retrieved by similarity to your query, which means paraphrase-tolerant recall but no byte-exactness guarantee. If losing a character matters, archive it — see Exact references.
Related
- Concepts overview — the evaluator's summary of the memory model and learning loop
- Runs, sessions, and scopes — where entries are visible and how knowledge widens
- Retrieval semantics — how entries come back out at query time
- Working memory vs long-term memory — the mutable store behind the "Current State" section
- How Mubit works — the write → retrieve → reflect → reinforce loop
- Step-level outcomes — process-reward learning with
step_outcomeentries - Lane-scoped memory — handoffs and feedback in multi-agent systems