How sessions work

Every fai session is a git branch. The branch model is what makes sessions conflict-free, resumable, and auditable.

The three branches

journal/<session-name> - the active session branch.

When you open a session named "auth-refactor", fai creates journal/auth-refactor. Everything captured during that session lives on this branch. Your AI conversations, file diffs, terminal activity - all committed here as it happens.

pending - the sealed session queue.

When you seal a session, the journal/ branch merges into pending. This is the staging area for synthesis: sessions that have closed but haven't yet been synthesized into project knowledge.

kept - the canonical knowledge branch.

After synthesis runs, the synthesized knowledge is committed to kept. Every new session inherits from kept - it's the clean, distilled record of everything your workbench has learned.

(Archived sessions move to archived/<session-name> - they're preserved but out of the active flow.)

The lifecycle in sequence

Open session
  → creates journal/session-name

Work (captures stream in continuously)
  → commits to journal/session-name

Seal session
  → journal/session-name merges to pending

Synthesis runs (triggered by ProposalThreshold)
  → pending synthesized by sub-vault agents
  → kept updated with new knowledge
  → next session opens from kept

Two simultaneous sessions

Two people can work on the same project simultaneously without conflict because they each have their own journal/ branch:

Person A: journal/auth-refactor
Person B: journal/dashboard-redesign

No merge conflicts during work. When A seals, their knowledge goes to pending → kept. When B seals next, they inherit A's knowledge from kept automatically.

Why git?

Git gives you everything for free:

• Full history of every capture
• Conflict-free parallel sessions
• Rollback to any point in your workbench's history
• Portable: clone your workbench, carry it anywhere

Your workbench is just a git repo. Open it, read it, push it anywhere.