Memory

Scenario Engine

The scenario engine forks memory state to run what-if analyses and hypothesis tests. Create parallel memory branches, run agents against them, and compare outcomes — without touching the main memory state. Each scenario is isolated, auditable, and can be committed to main or discarded when the analysis is complete.

Creating a scenario

A scenario is created from a base branch and an optional hypothesis statement. The hypothesis is stored as metadata and surfaced in comparison output to keep the analysis grounded.

bash
POST /scenarios
{
  "name": "risk-assessment-q2",
  "baseBranch": "main",
  "hypothesis": "If we remove the rate limiter from the public API, error rates will stay below 1% under peak load."
}

# Response:
# {
#   "scenarioId": "scen_abc123",
#   "branchId": "branch_scen_abc123",
#   "status": "ready"
# }

Creating a scenario automatically creates a corresponding memory branch. All agent writes during a scenario run are isolated to that branch.

Running an agent in a scenario

Point any agent at a scenario to run it in the forked memory context. The agent operates as normal but all memory reads and writes are scoped to the scenario branch.

bash
POST /scenarios/scen_abc123/run
{
  "agentId": "agent_load-tester",
  "input": "Simulate 10,000 requests/min against the public API with the rate limiter disabled.",
  "timeoutSeconds": 120
}

# Response:
# { "runId": "run_xyz789", "status": "running" }

Multiple agents can run against the same scenario concurrently. Use GET /scenarios/:id/runs to poll run status and retrieve outputs when complete.

Comparing scenarios

Compare the outcomes and memory state of two scenarios side by side. The comparison includes the memory diff (which entries were added, modified, or removed relative to the base branch) and a summary of each agent run's output.

bash
GET /scenarios/scen_abc123/compare/scen_def456

# Response:
# {
#   "scenarioA": { "id": "scen_abc123", "outcome": "error rate 0.7%" },
#   "scenarioB": { "id": "scen_def456", "outcome": "error rate 4.2%" },
#   "memoryDiff": { "added": 12, "modified": 5, "removed": 0 }
# }

Committing a scenario to main

If a scenario produces insights or memory updates you want to retain, commit it back to the target branch. Committing uses the same merge strategies available in Memory Branching.

bash
POST /scenarios/scen_abc123/commit
{
  "target": "main",
  "strategy": "crdt-auto",
  "message": "Validated rate limiter removal under peak load"
}

Discarding a scenario

If the scenario is no longer needed, delete it. This removes the scenario record, all associated run outputs, and the underlying memory branch.

bash
DELETE /scenarios/scen_abc123

Use cases

  • Risk modeling — Fork memory before a high-stakes change, run an analysis agent in the scenario, and evaluate the simulated outcome before committing to the real environment.
  • A/B tests — Create two scenarios from the same base branch with different hypotheses, run the same agent against both, and compare the resulting memory states and outputs.
  • Training data generation — Run agents through synthetic scenarios to generate diverse memory states that can be used as labeled training examples for fine-tuning.
  • Incident replay — Fork memory at a pre-incident snapshot and replay events to trace how state evolved and where the root cause emerged.