State Management Surface
Run-scoped state routes for variables and concepts, plus deprecated planning state (goals / actions / cycles).
MuBit is primarily a memory engine. It also exposes a small set of run-scoped state routes (variables, concepts) that are useful when you want to persist orchestrator state next to memory.
A broader planning surface (goals, actions, decision cycles) is still wired for backward compatibility but is deprecated — most workflows are better served by external task / orchestration systems.
For most use cases, start with remember, recall, getContext, checkpoint, and the learning-loop APIs. Reach for these state routes only when memory alone isn't enough.
Supported state surfaces
| Domain | Purpose | Status |
|---|---|---|
| Variables | Small explicit run-scoped state values that memory shouldn't infer | Supported |
| Concepts | Named planner concepts / controlled vocabulary | Supported |
Variables routes
| Route | Method | Purpose |
|---|---|---|
/v2/control/variables/set | POST | Set a run-scoped variable |
/v2/control/variables/get | POST | Get a variable |
/v2/control/variables/list | POST | List variables for a run |
/v2/control/variables/delete | POST | Delete a variable |
Concepts routes
| Route | Method | Purpose |
|---|---|---|
/v2/control/concepts/define | POST | Define a concept |
/v2/control/concepts/list | POST | List concepts |
Deprecated planning surfaces
The goals, actions, and decision-cycle RPCs are deprecated. They remain wired for existing deployments but are no longer recommended.
- Goals — Track tasks in a dedicated system (Linear, Jira, Asana). MuBit should store the lessons and outcomes, not the task list.
- Actions / decision cycles — Delegate to your agent orchestration framework (LangGraph, CrewAI, ADK). Persist only the resulting lessons, outcomes, and traces in MuBit.
If you're currently using these routes, keep them running — they aren't being turned off — but plan to migrate the planning surface to external tools and keep MuBit focused on experiential memory.
| Capability | Routes | Replacement |
|---|---|---|
| Goals | /v2/control/goals/add, /v2/control/goals/update, /v2/control/goals/list, /v2/control/goals/tree | External task tracker (Linear, Jira). Store only the resulting lessons / rules / mental models in MuBit. |
| Actions | /v2/control/actions/submit, /v2/control/actions/log | Agent framework execution log (LangGraph, CrewAI). Use archive + dereference when you need exact trace fidelity. |
| Decision cycles | /v2/control/cycles/run, /v2/control/cycles/history | Agent framework planning loop. Record the outcome of each cycle via record_outcome / record_step_outcome. |
Recommended usage guidance
- Keep variables and concepts in the same
run_idas the memory they explain. - Move goals, actions, and decision cycles to your task / orchestration system of record.
- Record the learning signal that comes out of those systems (outcomes, lessons, rules) in MuBit so future runs benefit.
- Use
checkpointwhen a long run is about to compact or cross a risky boundary.
Failure modes and troubleshooting
| Symptom | Root cause | Fix |
|---|---|---|
| Planner state exists but the model still forgets things | Only state was stored, not memory | Persist facts, lessons, or rules alongside variables |
| Debugging is hard | Actions / cycles are missing | Record planner decisions in your orchestration framework and surface outcomes to MuBit |
| Variable list grows unbounded | No TTL discipline | Use variables/delete at end-of-run or namespace by session |
Next steps
- Review the main control surface at Control HTTP reference.
- See memory and the learning loop in action in Support agent loop.