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

Sessions & Branching

Use checkpoints for durable task continuity and core sessions for reversible scratch branches.

Current MuBit uses two distinct ideas here:

  • control-plane checkpoints for durable task continuity and compaction survival
  • core session branches for temporary scratch or what-if work

These are not the same thing. Checkpoints preserve the durable task path. Core sessions give you a temporary branch you can inspect, commit, or drop.

Decision model

RequirementPrimitive
Preserve the main task before compactioncheckpoint()
Try a temporary branch and discard itcore.create_session, core.drop_session
Keep a reviewed branchcore.commit_session
Keep a short-lived scratch buffercore.add_memory with ttl_seconds

Minimal implementation example

sessions_and_branching.py
run_id = "claims:planner:claim-42"
 
client.checkpoint(
    session_id=run_id,
    label="before-scratch-branch",
    context_snapshot="Planner is about to compare two claim settlement strategies.",
)
 
base = client.core.create_session({})
branch = client.core.create_session({"parent_session_id": base["session_id"]})
branch_id = branch["session_id"]
 
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 becomes hard to restoreNo checkpoint was takenCheckpoint before the scratch branch
Branch writes leak into the main pathBranch was committed too earlyCommit only reviewed branches
Scratch context disappears too soonTTL or session lifecycle too shortAdjust branch lifetime intentionally

Next steps