Thought Branching Logic
Relevant source files
The following files were used as context for generating this wiki page:
Thought Branching Logic enables the exploration of alternative reasoning paths within a structured session. It allows the system to deviate from a primary line of thought to investigate hypothetical scenarios or secondary options without losing the context of the main exploration.
The system treats branches as containers for thought IDs. While the UnifiedSession object owns all thoughts, specific thoughts reference a branch_id to indicate their membership in a specific reasoning path.
Sources: memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md:30-34, models.py:47-53
Data Structures and Relationships
The branching system relies on the Branch and Thought dataclasses defined in models.py.
The Branch Entity
A Branch object records the metadata of a specific divergent path. It tracks:
- name: The human-readable identifier for the branch.
- purpose: The reason for creating the branch.
- session_id: A back-reference to the parent session.
- from_thought_id: The ID of the thought where the diversion began.
- thoughts: A list of thought IDs belonging to this branch.
Sources: models.py:47-53, tests/test_models.py:126-148
Relationship Architecture
The UnifiedSession acts as the aggregate root for all branching data. It owns collections of thoughts and branches. Thoughts are not stored inside the branch objects; instead, both entities reside in the session, and the thought object contains a branch_id field.
The diagram shows the hierarchical relationship where the session owns all entities, but thoughts link to branches via IDs.
Sources: memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md:30-34, models.py:7-25
Branching Operations
The UnifiedSessionManager class implements the logic for creating, navigating, and merging branches.
Creating a Branch
You create a branch using the create_branch method. The manager validates that an active session exists and ensures all required fields (name, purpose, from_thought) are provided. If validation fails, the system raises a ValidationError or BranchError.
Sources: session_manager.py:240-271, tests/test_session_manager.py:101-120
Merging a Branch
The merge_branch operation integrates the findings of a branch back into a target thought. The system appends a merge notification string, [Merged from {branch_name}], to the content of the target thought. This signifies the conclusion of the divergent path and the incorporation of its results into the main sequence.
Sources: session_manager.py:273-305, tests/test_session_manager.py:122-143
Logical Flow of Branching
The following sequence diagram illustrates the process of diverging from a main thought and later merging the results.
The diagram outlines the interaction between the manager and the session state during a typical branching lifecycle.
Sources: session_manager.py:240-305, tests/test_integration.py:48-62
Component Summary
| Component | Function | Key File |
|---|---|---|
Branch | Dataclass representing a divergent reasoning path. | models.py |
create_branch() | Validates and persists new branch entities to the session. | session_manager.py |
merge_branch() | Reconciles branch content with a target thought. | session_manager.py |
BranchError | Exception raised for invalid branching operations. | errors.py |
branch_id | Field on Thought identifying its reasoning path. | models.py |
Sources: models.py:47-53, session_manager.py:240-305, CLAUDE.md:88-93
Persistence Logic
Branches are persisted within the session markdown files located in memory-bank/sessions/. The _save_session_to_file method in session_manager.py does not currently include a dedicated header for branches in the markdown export, but it embeds branch_id information directly into the individual thought entries.
Sources: session_manager.py:84-88, memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md:30-34
Summary
Thought Branching Logic provides a structured way to handle non-linear reasoning. By using unique identifiers and session-level ownership, the system maintains a clear history of how different ideas branched from the main path and were eventually reconciled. This ensures that even complex, multi-path investigations remain traceable and persistent across restarts.