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

Branching Memory (What-If Simulations)

Use checkpoints and core session branches for reversible what-if exploration without polluting the main execution path.

When one task has multiple candidate strategies, preserve the main path and branch only the temporary exploratory state.

Current MuBit supports this with two complementary tools:

  • checkpoint() on the control plane for the durable main-path snapshot
  • core session create / commit / drop for reversible what-if branches

Decision model

RequirementPrimitive
Preserve the current durable task state before compaction or divergencecheckpoint()
Try a temporary branch against the hosted API and discard it latercore.create_session, core.drop_session
Merge a branch back into its parentcore.commit_session
Persist a session to disk on a self-hosted node (server-side filesystem path)core.snapshot_session, core.load_session
ℹ️Note

snapshot_session and load_session are disk-persistence operations that take a server-side filesystem path — they are only meaningful on a self-hosted node, not against the hosted API. Reversible in-memory what-if branching against https://api.mubit.ai is create_session + drop_session, with commit_session to merge a branch into its parent.

Minimal implementation example

branch_what_if.py
from mubit import Client
import os
 
run_id = "claims:planner:claim-42"
client = Client(
    endpoint=os.getenv("MUBIT_ENDPOINT", "https://api.mubit.ai"),
    api_key=os.environ["MUBIT_API_KEY"],
    run_id=run_id,
    transport="http",
)
 
client.checkpoint(
    session_id=run_id,
    label="before-strategy-branch",
    context_snapshot="Planner has two settlement strategies to compare.",
    metadata={"stage": "what-if"},
)
 
base = client.core.create_session({})
branch = client.core.create_session({"parent_session_id": base["session_id"]})
branch_id = branch["session_id"]
 
# Explore the branch, then either merge it into the parent or discard it.
# Merge back: client.core.commit_session({"session_id": branch_id, "merge_strategy": "overwrite"})
client.core.drop_session({"session_id": branch_id})

Failure modes and troubleshooting

SymptomRoot causeFix
Main path gets overwritten by experimentationNo durable checkpoint before branchingAlways checkpoint the primary path first
Scratch changes vanish too earlyBranch was dropped before reviewSnapshot or commit only after inspection
Compaction loses the decision contextBranching happened without checkpointingSave a checkpoint before diverging

Next steps