Branches

Branches are topic-specific containers for messages. Each branch represents a distinct semantic topic in the conversation.

What is a Branch?

A branch is a collection of messages about the same topic:

Branch: "dog-adoption"
- User: "Tell me about your dog adoption services"
- Assistant: "We help match dogs with loving homes..."
- User: "What's the adoption fee?"
- Assistant: "Adoption fees range from $50-$200..."

When you ask about adoption fees, the LLM only sees the 4 messages in the "dog-adoption" branch—not the 20 messages about black holes and vacation planning.

Branch Lifecycle

Creation

Branches are created when DriftOS detects a new topic:

Message: "Tell me about black holes"
Current Branch: "dog-adoption"
Decision: BRANCH (new topic)
→ New branch created: "black-holes"

Growth

Messages are added to the active branch when the topic continues:

Message: "What's the event horizon?"
Current Branch: "black-holes"
Decision: STAY
→ Message added to "black-holes" branch

Switching

With DriftOS Core, you can switch back to old branches:

Message: "Back to the dog thing—what was the fee?"
Current Branch: "black-holes"
Decision: ROUTE to "dog-adoption"
→ Switched to existing branch

Note: DriftOS Embed doesn't switch—it creates a new branch instead.

Branch Context

When DriftOS builds context for the LLM, it:

1. Takes the current branch
2. Limits to max messages (default: 10)
3. Prunes all other branches
4. Returns only relevant context

Example:

Total messages: 23
Current branch: "dog-adoption" (5 messages)
Max context: 10

Context sent to LLM: 5 messages
Pruned branches: "black-holes" (8 msgs), "vacation" (10 msgs)
Token savings: 78%

Branch Metadata

Each branch stores:

• Topic - Semantic label (e.g., "dog-adoption")
• Branch ID - Unique identifier
• Message count - How many messages in this branch
• Centroid (Embed only) - Average embedding for similarity matching
• Facts (if extraction enabled) - Key facts extracted when leaving branch

Next Steps

• Routing - How branches are created
• Facts - Automatic fact extraction
• Troubleshooting - Fix branch issues