# Branching ("Fork Reality")

**Last Updated:** 2025-01-31
**Confidence:** Medium (planned feature)

## Summary

Branching allows agents to create hypothetical scenarios without polluting the main knowledge graph. Think "What if inflation hits 5%?" - simulate effects without committing to reality.

**Key Facts:**
- Implemented via Overlay Graphs
- Branch = lightweight index (Map<Hash, Assertion>)
- Writes go to branch, reads check branch first then global
- Merge commits branch assertions to global WAL
- Copy-on-write semantics

**File Pointer:** `crates/stemedb-core/src/branch.rs` (planned, Phase 3)

## How It Works

```
Global DAG:                    Branch "recession-2025":
[A1] -> [A2] -> [A3]          [A4-hypothetical]
                                    |
                              "inflation = 5%"
```

### Write to Branch
```rust
// Assertions stored in branch's ephemeral index, not Global DAG
branch.put(hypothetical_assertion)?;
```

### Read from Branch
```rust
// Check branch index first, fall back to global
let value = branch.get(hash)
    .or_else(|| global.get(hash))?;
```

### Merge Branch
```rust
// Commit hypotheticals to global if they become real
global.merge(branch)?;  // Appends branch assertions to WAL
```

## Use Cases

1. **Scenario Analysis:** "What if competitor launches?"
2. **Planning:** "What if we expand to Europe?"
3. **Backtesting:** "What if we knew X earlier?"

## Related Topics

- [Storage](../services/storage.md)
- [Roadmap Phase 3](../../../roadmap.md)