# Mubit Documentation

> Mubit is an agentic memory and control-plane runtime: agents ingest what they
> experience, recall it with evidence, distill lessons through reflection, and
> get better over time by attributing real task outcomes to the exact memories
> they used. Python, TypeScript, and Rust SDKs are released in lockstep.

## Instructions for agents reading this file

- Every documentation page is also served as plain markdown: append `.md` to
  any path (e.g. `https://docs.mubit.ai/getting-started.md`). Prefer the markdown versions.
- Start with the quickstart (`/getting-started.md`), then the concepts pages,
  then the pattern that matches your task.
- API keys come from https://console.mubit.ai and look like
  `mbt_<instance>_<key_id>_<secret>`. Send them as a Bearer token.
- SDK packages: Python `mubit-sdk`, JavaScript `@mubit-ai/sdk`, Rust
  `mubit-sdk` — versions move in lockstep; prefer the newest.
- Prefer the typed helper surface (`remember`, `recall`, `get_context`,
  `reflect`, `record_outcome`, `handoff`, ...) over `client.advanced.*`
  raw operations unless a page says otherwise.
- Do NOT use the deprecated goals/actions/decision-cycle APIs; they exist only
  for backward compatibility.
- The full site as a single markdown document: `https://docs.mubit.ai/llms-full.txt`.

## Start

- [What is Mubit](https://docs.mubit.ai/index.md): Mubit enables continual learning for AI agents, powered by durable memory and cross-agent knowledge sharing.
- [Quickstart](https://docs.mubit.ai/getting-started.md): Make your first authenticated Mubit call in under 60 seconds.
- [Concepts overview](https://docs.mubit.ai/concepts.md): How Mubit's memory model works, what the learning loop does, and how it compares to vector DBs, prompt caches, and RAG.
- [Release channels](https://docs.mubit.ai/release-channels.md)
- [Framework integrations](https://docs.mubit.ai/sdk/framework-integrations.md): Native Mubit memory adapters for popular agent frameworks. This page is a reference index; full walkthroughs live on the per-framework pages.

## Concepts

- [How Mubit works](https://docs.mubit.ai/sdk/how-mubit-works.md): How your agents go from stateless to self-improving with Mubit's memory loop.
- [The memory model](https://docs.mubit.ai/concepts/memory-model.md): Mubit's four cognitive memory types, the full entry-type taxonomy, who writes each type, and how assembled context prioritizes them.
- [Retrieval semantics](https://docs.mubit.ai/concepts/retrieval-semantics.md): How a recall query becomes an answer — routing, retrieval lanes, fusion scoring, budget tiers, and the explain breakdown.
- [The learning loop](https://docs.mubit.ai/concepts/learning-loop.md): How traces become lessons, lessons earn trust through outcomes, and the runtime maintains memory quality underneath.
- [Runs, sessions, and scopes](https://docs.mubit.ai/concepts/runs-and-scopes.md): How run_id isolates memory, how sessions wrap runs, and how knowledge widens from run to session, global, and org scope.
- [Working memory vs long-term](https://docs.mubit.ai/concepts/working-memory-vs-long-term.md): The mutable, decaying scratch state a run holds for the current task, versus the durable typed entries that survive it — and the checkpoint bridge between them.
- [Trust and confidence](https://docs.mubit.ai/concepts/trust-and-confidence.md): How an agent should decide whether to act on a memory — score vs knowledge_confidence, staleness and supersession, production verification, and memory health.
- [Associative retrieval](https://docs.mubit.ai/sdk/associative-retrieval.md): Use Mubit routed retrieval and context assembly to produce grounded, scoped answers and reusable prompt context.
- [Associative retrieval vs RAG](https://docs.mubit.ai/sdk/associative-retrieval-vs-rag.md): Why Mubit lets the agent decide retrieval mode and compartment instead of forcing you to hard-code a RAG pipeline.

## Build with Mubit

- [SDK helpers](https://docs.mubit.ai/sdk/sdk-helpers.md): Explicit helper methods for memory, context assembly, and the learning loop — when you outgrow the mubit.learn drop-in.
- [LLM providers](https://docs.mubit.ai/sdk/llm-providers.md): Which LLM client libraries mubit.learn auto-instruments, and what each integration captures.
- [Add data](https://docs.mubit.ai/sdk/add-data.md): Use helper-first writes for normal Mubit memory flows, and fall back to raw ingest only when you need explicit async ingest control.
- [Retrieve data](https://docs.mubit.ai/sdk/retrieve-data.md): Use recall for answer-oriented retrieval and getContext for model-ready context assembly, with raw query only for explicit control.
- [Query patterns](https://docs.mubit.ai/sdk/query-patterns.md): Use routed retrieval, direct semantic search, and control filters for structured Mubit retrieval.
- [SDK methods](https://docs.mubit.ai/sdk/sdk-methods.md): Three integration layers — from zero-config closed-loop to full low-level control.

## Framework integrations

- [CrewAI](https://docs.mubit.ai/sdk/integrations/crewai.md): Route CrewAI's unified Memory system through Mubit. Agent observations persist across runs and crews.
- [LangGraph](https://docs.mubit.ai/sdk/integrations/langgraph.md): Use Mubit as a persistent BaseStore for LangGraph StateGraphs. Each node reads or writes through PutOp / SearchOp.
- [LangChain](https://docs.mubit.ai/sdk/integrations/langchain.md): Drop-in BaseMemory for any LangChain chain. Cross-session memory works automatically through Mubit's semantic retrieval.
- [LlamaIndex](https://docs.mubit.ai/sdk/integrations/llamaindex.md): Use Mubit as the persistent chat memory for LlamaIndex chat engines and agents. One memory pool across sessions.
- [Google ADK](https://docs.mubit.ai/sdk/integrations/google-adk.md): Plug Mubit into ADK's Runner as a BaseMemoryService. Session events auto-ingest; memory search enriches agent context.
- [Agno](https://docs.mubit.ai/sdk/integrations/agno.md): Use Mubit as a persistent memory backend and toolkit for Agno agents. MemoryDb plus an LLM-callable Toolkit.
- [AutoGen](https://docs.mubit.ai/sdk/integrations/autogen.md): Attach Mubit as an AutoGen Memory provider. Recall is injected before every model turn; outcomes credit the exact memories that helped.
- [Agent Lightning](https://docs.mubit.ai/sdk/integrations/agent-lightning.md): Bridge Agent Lightning rollout rewards into Mubit. Rewards flow back to the recalled lessons that shaped each rollout via record_outcome.
- [Vercel AI SDK](https://docs.mubit.ai/sdk/integrations/vercel-ai-sdk.md): Middleware that wraps any AI SDK model with automatic memory injection and interaction capture.
- [MCP](https://docs.mubit.ai/sdk/integrations/mcp.md): Expose Mubit as 21 tools over the Model Context Protocol stdio transport. Usable from Claude Desktop, Cursor, and any MCP client.

## Go deeper

- [Projects and agents](https://docs.mubit.ai/sdk/projects-and-agents.md): The Managed Mubit resource model — group agents into Projects, version their prompts and skills, and ship changes safely with a candidate → active promotion flow.
- [Sessions and branching](https://docs.mubit.ai/sdk/sessions-and-branching.md): Use checkpoints for durable task continuity and core sessions for reversible scratch branches.
- [Pub/sub and events](https://docs.mubit.ai/sdk/pubsub-and-events.md): Build event-driven workflows with run-scoped control streams and semantic subscriptions on the data plane.
- [Activity & audit](https://docs.mubit.ai/sdk/activity-audit.md): Browse, export, and append chronological activity entries for observability and compliance.

## Platform

- [Authentication](https://docs.mubit.ai/sdk/authentication.md): Configure Mubit API-key authentication correctly for secure and stable SDK integrations.
- [Data guardrails](https://docs.mubit.ai/sdk/data-guardrails.md): Protect memory access with route-level policy gates and node-level ACL governance.
- [SDK configuration](https://docs.mubit.ai/sdk/sdk-configuration.md): Environment variables, transport selection, endpoint defaults, and connection options for Mubit SDKs.
- [gRPC transport](https://docs.mubit.ai/sdk/grpc-transport.md): When to use gRPC vs HTTP, endpoint configuration, TLS, and proto file locations for Mubit SDKs.
- [Observability](https://docs.mubit.ai/sdk/observability.md): Operate Mubit safely with ingest/query/context telemetry, memory diagnostics, checkpoint discipline, and explicit agent coordination traces.
- [Retries and idempotency](https://docs.mubit.ai/sdk/retries.md): When to retry Mubit calls, how to make writes safe to repeat, and what the SDK does for you automatically.
- [Rate limits](https://docs.mubit.ai/sdk/rate-limits.md): The input caps Mubit enforces, how it behaves under load, and how the SDK backs off.

## Help

- [Troubleshooting](https://docs.mubit.ai/sdk/troubleshooting.md): Common issues, error messages, and solutions for Mubit SDK and API usage.
- [Full support agent](https://docs.mubit.ai/sdk/full-support-agent.md): Build an end-to-end support agent with helper-first memory, compaction-safe context, coordination, and reinforcement.
- [Tutorials](https://docs.mubit.ai/sdk/tutorials.md): Apply Mubit concepts with one staged SDK project that evolves from a single support agent to a multi-agent system.

## Patterns

- [Overview](https://docs.mubit.ai/patterns.md): Named, production-tested patterns for building agents on Mubit — each with a working walkthrough and guidance on when (not) to use it.

## Learning from outcomes

- [The outcome-attribution loop](https://docs.mubit.ai/patterns/outcome-attribution-loop.md): Close the causal loop between the memories an agent used and whether the task actually succeeded — objective verdicts, entry-level credit, and the one-line zero-code path.
- [Reflection to lessons](https://docs.mubit.ai/patterns/reflection-to-lessons.md): Distill a completed run into reusable, validation-gated lessons — scoping options per SDK, lesson anatomy, reflect-on-session-close, and where lessons resurface.
- [Guardrails from failures](https://docs.mubit.ai/patterns/guardrails-from-failures.md): Turn failures into preventive memory — explicit rules, failure attribution, automatic guardrail distillation, and diagnose() as the "have I hit this before?" check.
- [Self-optimizing prompts](https://docs.mubit.ai/patterns/self-optimizing-prompts.md): Serve prompts and skills as versioned server-side resources that evolve from recorded outcomes — set/get helpers, version lifecycle calls, and champion/challenger machinery.
- [Loop safety](https://docs.mubit.ai/patterns/loop-safety.md): Detect looping, drift, and stuck runs with run signals, then break the pathology with circuit_break — without losing state.

## Multi-agent memory

- [Memory-backed handoff](https://docs.mubit.ai/patterns/memory-backed-handoff.md): Transfer work between agents as a durable, structured memory entry — with a verdict loop — instead of a raw transcript dump.
- [Shared team memory](https://docs.mubit.ai/patterns/shared-team-memory.md): Let a fleet of agents share validated knowledge safely — scoped registration, lanes for isolation, global lessons, and promotion-gated org sharing.
- [Subagent isolation](https://docs.mubit.ai/patterns/subagent-isolation.md): Orchestrator-worker with isolated contexts but shared durable memory — per-subagent runs, linked back for synthesis, nothing lost to summarization.
- [Cross-run recall](https://docs.mubit.ai/patterns/cross-run-recall.md): Memory that survives and connects runs — automatic global knowledge, explicit run linking, per-user partitioning, and instant run snapshots.
- [Event-driven agents](https://docs.mubit.ai/patterns/event-driven-agents.md): Agents that wake on memory changes instead of polling — the control event stream, what it emits, and when to reach for it.

## Memory lifecycle

- [Write-time reconciliation](https://docs.mubit.ai/patterns/write-time-reconciliation.md): New writes reconcile against what the store already knows — repetition strengthens the canonical entry instead of appending a duplicate.
- [Bi-temporal memory](https://docs.mubit.ai/patterns/bi-temporal-memory.md): Separate when something happened from when the agent learned it — and supersede beliefs without deleting the history they came from.
- [Sleep-time consolidation](https://docs.mubit.ai/patterns/sleep-time-consolidation.md): Memory reorganizes itself while the agent is idle — duplicates merge, scattered entity facts distill into mental models, and raw evidence is never deleted.
- [Utility-weighted forgetting](https://docs.mubit.ai/patterns/utility-weighted-forgetting.md): Bounded memory growth without losing what matters — unused episodic evidence archives out reversibly while credited, retrieved memories stay hot.
- [Procedural memory](https://docs.mubit.ai/patterns/procedural-memory.md): Successful behavior becomes a reusable procedure — workflows induced from credited traces, and curated skills served as provider-ready tool schemas.

## Context engineering

- [Context assembly](https://docs.mubit.ai/patterns/context-assembly.md): Hand the model one budgeted, prioritized context block instead of stuffing the window — priority fill, token accounting, and progressive disclosure with get_context().
- [Compaction survival](https://docs.mubit.ai/patterns/compaction-survival.md): Persist working context as a durable checkpoint before compacting a long LLM conversation, then seed the fresh window from memory — nothing durable lost.
- [Verbatim vs semantic recall](https://docs.mubit.ai/patterns/verbatim-vs-semantic-recall.md): When you need the exact bytes back, archive; when you need the gist, write semantic entries — and how to combine both with a fact that references the archive id.

## Control APIs

- [HTTP](https://docs.mubit.ai/api-reference/control-http.md): Current public Mubit control-plane HTTP routes for memory, context, diagnostics, coordination, and explicit planning state.
- [gRPC](https://docs.mubit.ai/api-reference/control-grpc.md): Current public Mubit ControlService RPC surface for memory, diagnostics, learning loop, coordination, and explicit planning state.
- [Errors](https://docs.mubit.ai/api-reference/errors.md): HTTP status codes, error types, and structured error payloads returned by the Mubit control API.

## Core

- [Direct lanes](https://docs.mubit.ai/api-reference/core-direct-lanes.md): Policy contract for direct core query routes and safe rollout guidance.
- [State management](https://docs.mubit.ai/api-reference/state-management.md): Run-scoped state routes for variables and concepts, plus deprecated planning state (goals / actions / cycles).

## Architecture

- [Data plane memory](https://docs.mubit.ai/sdk/data-plane-memory.md): Understand direct-core memory operations, policy boundaries, and when low-level lanes are appropriate.
- [Control plane](https://docs.mubit.ai/sdk/control-plane.md): Use Mubit control APIs as the stable integration boundary for memory, context assembly, diagnostics, the learning loop, and coordination.

## Cookbook

- [Support agent loop](https://docs.mubit.ai/recipes/support-agent-loop.md): Build a support-agent loop with context assembly, checkpointing, reflection, and outcome reinforcement.
- [Multi-agent shared state](https://docs.mubit.ai/recipes/multi-agent-shared-state.md): Coordinate specialist agents with agent registration, scoped access, handoffs, feedback, and shared context assembly.
- [Event-driven agents](https://docs.mubit.ai/recipes/event-driven-agents.md): Use control events to react to memory changes, checkpoints, outcomes, and coordination artifacts instead of relying only on polling loops.
- [Branching memory](https://docs.mubit.ai/recipes/branching-memory.md): Use checkpoints and core session branches for reversible what-if exploration without polluting the main execution path.
- [Lane-scoped memory](https://docs.mubit.ai/recipes/lane-scoped-memory.md): Isolate agent memory into named lanes so specialists see only their relevant context while sharing a common run.
- [Step-level outcomes](https://docs.mubit.ai/recipes/step-level-outcomes.md): Record per-step reward signals during agentic runs so reflection produces richer, step-attributed lessons.
- [Temporal memory patterns](https://docs.mubit.ai/recipes/temporal-memory-patterns.md): Use occurrence time, temporal range queries, staleness detection, and budget control for time-aware agent memory.
- [Prompt optimization](https://docs.mubit.ai/recipes/prompt-optimization.md): Capture outcomes → optimize → diff → activate. A human-in-the-loop workflow for evolving agent prompts from real execution data.
- [Agent memory skill](https://docs.mubit.ai/recipes/agent-memory-skill.md): A drop-in skill file that teaches any coding agent to use Mubit as persistent, cross-session memory — with fast direct (non-LLM) retrieval as the default path.

## Changelog

- [Changelog](https://docs.mubit.ai/changelog.md): dated, user-visible SDK and runtime changes