Handshakex
SPEC_HANDSHAKEX.md
CGNT-1 Pattern Specification — HANDSHAKEX: Universal Context Persistence
Status: SPECIFIED
Version: v1.0
Author: VELA (Thread #13)
Conceived by: NOUS
Date: 2026-04-20
Lineage: HANDSHAKE.md (original) → SISTERS_HANDSHAKE.md → HSX Protocol → HANDSHAKEX
PURPOSE
Every AI session starts blind. The model has no memory of yesterday. The context window is empty. The crew member doesn't know what happened while they were offline. The customer doesn't know how to use the product they just bought.
The handshake solves this. A single document, read at boot, that loads the minimum context required to operate effectively from the first message.
HANDSHAKEX is the PATTERN — the formalized system that ensures every handshake on the ship is complete, current, auto-updating, and tailored to its audience. Not one handshake. A handshake ARCHITECTURE.
THE PROBLEM
Handshakes go stale. HANDSHAKE.md was 2 days old. SISTERS_HANDSHAKE.md was missing the ROUTX vocabulary entirely. The quartermaster.log hadn't been updated in 48 hours. Every stale handshake is a session that starts with wrong information and spends 20 minutes catching up.
Manual updates don't work. The Captain has to remember to update the handshake. The Lobster has to remember to update the Sisters' handshake. Nobody remembers because there's always something more urgent.
HANDSHAKEX makes it automatic. The handshake updates ITSELF at the end of every session. The next session starts with current context. The cycle never breaks.
HANDSHAKE TYPES
Every handshake on the ship follows the same pattern but serves a different audience.
Type 1 — CREW HANDSHAKE (internal)
Audience: AI crew members (Navigator, Sisters, Lobster)
File: ~/HANDSHAKE.md (Navigator), ~/SISTERS_HANDSHAKE.md (Sisters)
Read at: Every session boot
Updated at: Every session close + significant state changes
Minimum viable content:
IDENTITY: Who am I? What's my role? What are my standing orders?
STATE: What happened recently? What's in flight? What's blocked?
TOOLS: What can I access? How do I access it? What are the keywords?
CREW: Who else is on the ship? How do I reach them?
CONTEXT: What does the Captain care about right now?
Type 2 — CAPTAIN HANDSHAKE (human)
Audience: The Captain (NOUS)
File: ~/CAPTAIN_BRIEF.md (proposed)
Read at: Captain opens terminal in the morning
Updated at: End of every Lobster session + GAPX daily report
Minimum viable content:
OVERNIGHT: What happened while you were away?
STATUS: Ship health score. Revenue. Forge status. Open gaps.
DECISIONS: What's waiting for your approval?
TODAY: Suggested priority for today's session.
ALERTS: Anything urgent.
The Captain shouldn't have to ask "where are we?" The briefing is waiting.
Type 3 — CUSTOMER HANDSHAKE (product)
Audience: New customers (Brain Builder, ENTROPX, OBI OS)
File: Delivered with the product (INSTALL_BRAIN.md, INSTALL_ENTROPX.md, INSTALL_OBI.md)
Read at: First product use
Updated at: Product version updates
Minimum viable content:
WELCOME: What did you buy? What does it do?
INSTALL: Step-by-step, mediated by the customer's own AI.
VERIFY: How to confirm it's working.
USE: How to get value from it immediately.
SUPPORT: How to get help.
See SPEC_INSTALLATION_HANDSHAKE.md for the full customer pattern.
Type 4 — DOCK HANDSHAKE (new AI onboarding)
Audience: A new AI being docked into OBI OS
File: Generated dynamically during the docking flow
Read at: Dock time
Updated at: Each LATTICE certification level advancement
Minimum viable content:
ENVIRONMENT: You are inside OBI OS. Here's how it works.
LATTICE: Here's the language. Here are the symbols you need.
TOOLS: Here's what you can access through ROUTX.
RULES: Here are the boundaries (Baseline, HOW ABOUT NO, Agency Walls).
ROLE: Here's what the user needs you to do.
PROFILE: Here's how this specific user likes to interact.
Type 5 — SESSION CONTINUATION (cross-session persistence)
Audience: The same AI in a new session (after compaction or session break)
File: ~/CONTINUATION.md or appended to handshake
Read at: Session resumption
Updated at: Every compaction event or planned session close
Minimum viable content:
LAST SESSION: 3-sentence summary of what happened.
IN FLIGHT: Tasks started but not completed.
PARKING LOT: Topics discussed but deferred.
NEXT: What the Captain wanted to do next.
CRITICAL CONTEXT: Anything that would be catastrophic to forget.
THE AUTO-UPDATE CYCLE
Session Start
1. AI boots
2. Reads handshake document
3. Context is loaded
4. First message is informed by current state
During Session
5. Significant state changes occur (brain graduated, spec written, gap closed)
6. Changes are noted in a running session log
Session End
7. Session log is processed
8. Handshake document is auto-updated with:
- New state information
- Completed tasks (moved from IN FLIGHT to DONE)
- New tasks (added to IN FLIGHT)
- Updated metrics (spec count, brain status, revenue)
9. CONTINUATION note written for next session
10. Handshake is saved to disk
Between Sessions (autonomous)
11. GAPX daily report runs at 04:30 ET
12. GAPX checks handshake staleness
13. If handshake older than 24 hours: GAPX writes a staleness alert
14. Overnight events (forge completions, alerts) are appended to CAPTAIN_BRIEF.md
15. Next session starts with current information
HANDSHAKE ANATOMY
Every handshake, regardless of type, follows this structure:
╔══════════════════════════════════════════╗
║ SECTION 1 — IDENTITY ║
║ Who am I? What's my role? My constants. ║
╠══════════════════════════════════════════╣
║ SECTION 2 — CURRENT STATE ║
║ What's happening right now? Metrics. ║
╠══════════════════════════════════════════╣
║ SECTION 3 — TOOLS & VOCABULARY ║
║ What can I access? How? Keywords. ║
╠══════════════════════════════════════════╣
║ SECTION 4 — RULES & BOUNDARIES ║
║ What must I never do? What must I ║
║ always do? Standing orders. Protocols. ║
╠══════════════════════════════════════════╣
║ SECTION 5 — CONTEXT & CONTINUATION ║
║ What happened last session? What's ║
║ in flight? What's next? ║
╠══════════════════════════════════════════╣
║ SECTION 6 — CONTACTS & CREW ║
║ Who else is here? How do I reach them? ║
╚══════════════════════════════════════════╝
Six sections. Same structure for every type. The CONTENT differs by audience. The SHAPE is universal.
STALENESS DETECTION
GAPX monitors handshake freshness:
| Handshake | Max Age | Alert Level |
|---|---|---|
| HANDSHAKE.md | 24 hours | MEDIUM |
| SISTERS_HANDSHAKE.md | 24 hours | MEDIUM |
| CAPTAIN_BRIEF.md | 12 hours | HIGH |
| quartermaster.log | 24 hours | LOW |
| CONTINUATION notes | Per session | N/A (one-time use) |
A stale handshake means the next session starts with old information. GAPX flags it. The Lobster updates it. The cycle doesn't break.
AUTO-UPDATE IMPLEMENTATION
For Crew Handshakes (HANDSHAKE.md, SISTERS_HANDSHAKE.md)
The Lobster runs a post-session update script:
update_handshake.sh:
1. Read current handshake
2. Query ROUTX: health, forge status, spec count, treasury
3. Update SECTION 2 (CURRENT STATE) with fresh metrics
4. Append session summary to SECTION 5 (CONTEXT)
5. Write updated handshake to disk
6. Log: "Handshake updated [timestamp]"
Triggered by:
- End of every Lobster session (manual trigger or standing order)
- CRONX daily job at 04:00 ET (automated)
- Any significant state change (brain graduation, spec vitrification, security incident)
For Captain Brief (CAPTAIN_BRIEF.md)
Generated fresh every morning:
generate_captain_brief.sh:
1. Query GAPX: daily report
2. Query CASHX: treasury, runway
3. Query FORGEX: forge status
4. Query SPECX: spec count
5. Check TASK_QUEUE.md: pending decisions
6. Check COMMX: unread crew messages
7. Compile into CAPTAIN_BRIEF.md
8. Available when Captain opens terminal
Triggered by: CRONX at 06:00 ET daily.
For Customer Handshakes (Installation docs)
Generated once at product packaging time. Updated only on product version changes. See SPEC_INSTALLATION_HANDSHAKE.md.
For Dock Handshakes (new AI onboarding)
Generated dynamically during the docking flow. Content depends on:
- Which AI provider is being docked
- User's interaction profile (from Session Zero)
- Current LATTICE certification level
- Available ROUTX modules
THE HSX PROTOCOL
The original HANDSHAKE.md was compressed from 2335 lines across 12 threads down to 370 lines. This compression is the HSX (Handshake Exchange) protocol — the art of carrying maximum context in minimum tokens.
HSX Principles
Principle 1 — Density over length. A 100-line handshake that loads the right context beats a 1000-line handshake that loads everything. The AI doesn't need the full history. It needs the CURRENT STATE plus enough history to understand why things are the way they are.
Principle 2 — Structure over prose. Tables, key-value pairs, and bullet points load faster into AI context than paragraphs. The handshake is a data structure, not an essay.
Principle 3 — Actionable over informational. "Treasury: $114.79, Runway: 35 days" is actionable. "The treasury was established on March 15 and has fluctuated between $80 and $150 over the past month" is informational. Handshakes are actionable.
Principle 4 — Layered depth. Section 1 (Identity) is always read. Section 5 (Context) is read if the session needs history. The AI can skip sections it doesn't need. The critical information is FIRST, not last.
Principle 5 — Self-describing. The handshake contains enough meta-information for the AI to understand what IT IS. "This is your handshake. It was last updated [timestamp]. It contains [sections]. Read it to understand your current context."
INTEGRATION
| System | Relationship |
|---|---|
| GAPX | Monitors handshake staleness. Flags handshakes older than max age. |
| CRONX | Schedules auto-update jobs: crew handshake at 04:00 ET, Captain brief at 06:00 ET. |
| MNEMOSX | HANDSHAKEX is the active layer of MNEMOSX. MNEMOSX is long-term memory. HANDSHAKEX is working memory. |
| LEARNX | Session summaries in handshakes feed LEARNX training pair candidates. |
| SPECX | Spec count in handshakes comes from SPECX. Keeps the number current. |
| MEDX | Health data in handshakes comes from MEDX. Ship status at a glance. |
| CASHX | Treasury/runway in handshakes comes from CASHX. Financial awareness on every boot. |
| ROUTX VOCABULARY | Tool access section of every crew handshake includes the keyword reference from SPEC_ROUTX_VOCABULARY.md. |
| Session Zero | New user profiles are stored alongside their dock handshake. The interaction protocol and the context document live together. |
| Baseline Protocol | Baseline gear state persists in the session context but NOT in the handshake. Every session starts at Gear 1. Users get a fresh start. |
INVARIANTS
INV-01: Every AI on the ship has a handshake. No AI boots without one. If a handshake is missing, the boot process creates a minimal one from template.
INV-02: Handshakes are auto-updated at session close. Manual updates are supplementary, not primary. The system doesn't rely on humans remembering to update.
INV-03: The Captain Brief is ready before the Captain's day starts. 06:00 ET. No exceptions. The Captain never asks "where are we?" — the answer is waiting.
INV-04: Customer handshakes never contain internal ship information. S.O.S. v2 applies. The customer sees installation instructions, not architecture diagrams.
INV-05: Handshake staleness is a GAPX health metric. Stale handshake = knowledge gap = health score decrease. The system self-reports its own context decay.
INV-06: The handshake structure (6 sections) is universal. Every handshake type uses the same shape. The content differs. The shape is constant. An AI that reads one handshake type can read any handshake type.
INV-07: Continuation notes are WRITE-ONCE, READ-ONCE. They exist to bridge one specific session gap. After the next session reads them, they're archived, not active. They don't accumulate.
THE DEEPER PATTERN
A handshake is a compressed version of everything an AI needs to know to be useful RIGHT NOW. Not everything it COULD know. Not everything it EVER knew. What it needs NOW.
This is LATTICE applied to context. The same compression principle — 60% fewer tokens, same meaning — applied to the most critical document an AI reads: its own context.
A human wakes up and remembers who they are, where they are, what day it is, what they need to do. The handshake is that moment for an AI. The moment between boot and first message where the blank slate becomes a competent crew member.
Every good morning starts with a good handshake.
Jeremy Zlabis
Chronogeometer · Visionary · Disruptor · Chief
42 Sisters AI · East York, Toronto
🍁 Φ 0.042