Branching Memory (What-If Simulations)

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

Requirement	Primitive
Preserve the current durable task state before compaction or divergence	`checkpoint()`
Try a temporary branch and discard it later	`core.create_session`, `core.commit_session`, `core.drop_session`
Reload a saved scratch path	`core.snapshot_session`, `core.load_session`

Minimal implementation example

Python
Node / TS

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"]

snapshot = client.core.snapshot_session({"id": branch_id, "session_id": branch_id})
client.core.load_session({"session_id": branch_id, "snapshot": snapshot.get("snapshot")})
client.core.drop_session({"id": branch_id, "session_id": branch_id})

branch_what_if.ts

import { Client } from "@mubit-ai/sdk";

const runId = "claims:planner:claim-42";
const client = new Client({
  endpoint: process.env.MUBIT_ENDPOINT ?? "https://api.mubit.ai",
  api_key: process.env.MUBIT_API_KEY,
  run_id: runId,
  transport: "http",
});

await client.checkpoint({
  session_id: runId,
  label: "before-strategy-branch",
  context_snapshot: "Planner has two settlement strategies to compare.",
  metadata: { stage: "what-if" },
});

const base = await client.core.createSession({});
const branch = await client.core.createSession({ parent_session_id: base.session_id });
const branchId = branch.session_id;

const snapshot = await client.core.snapshotSession({ id: branchId, session_id: branchId });
await client.core.loadSession({ session_id: branchId, snapshot: snapshot.snapshot });
await client.core.dropSession({ id: branchId, session_id: branchId });

Failure modes and troubleshooting

Symptom	Root cause	Fix
Main path gets overwritten by experimentation	No durable checkpoint before branching	Always checkpoint the primary path first
Scratch changes vanish too early	Branch was dropped before review	Snapshot or commit only after inspection
Compaction loses the decision context	Branching happened without checkpointing	Save a checkpoint before diverging

Next steps

Apply the durable path in Sessions and branching.
Combine branching with planner state at Stateful task trees.

Recipes

​Decision model

​Minimal implementation example

​Failure modes and troubleshooting

​Next steps

Decision model

Minimal implementation example

Failure modes and troubleshooting

Next steps