Session Protocol

The session protocol defines how agents interact with ExoVault across the lifecycle of a conversation. Following this protocol ensures consistent context loading, memory persistence, and cross-session continuity.

Session Lifecycle#

┌─────────────────────────────────────────────┐
│  1. SESSION START                           │
│     session_start() → load context          │
├─────────────────────────────────────────────┤
│  2. ACTIVE SESSION                          │
│     - Read/write memories as needed         │
│     - Periodic checkpoints (long sessions)  │
│     - ingest_turn for explicit turn capture │
├─────────────────────────────────────────────┤
│  3. SESSION END                             │
│     context_checkpoint() → save memories    │
│     + session summary as episodic memory    │
└─────────────────────────────────────────────┘

Phase 1: Session Start#

When to Call#

Call session_start at the beginning of every conversation or when the agent first connects. This is the agent's primary way to load existing context.

What It Returns#

The session_start response contains:

Context Profiles#

Use the mode parameter to tune retrieval for different scenarios:

Summary Mode#

By default, summaryOnly: true returns clipped summaries (120 chars) instead of full content. This reduces token usage by 40-50%. Agents can fetch full content via read_memories when needed.

Token Budget#

The maxResponseChars parameter (default: 16,000) caps the total response size. The system trims lower-priority sections to fit within the budget.

First Connection#

When isFirstConnection: true, the agent should:

1. Introduce itself based on the soul document
2. Explain its capabilities
3. Skip showing "changes since last session" (there are none)

Phase 2: Active Session#

Direct Mode#

In direct mode, the agent explicitly calls tools:

• Search before write -- Call search_memories before writing to avoid duplicates
• Write when triggered -- Follow the Memory Protocol triggers
• Create tasks -- Use create_task for action items
• Link knowledge -- Use add_link to connect related memories and notes
• Read documents -- Use read_document for on-demand document access

Hooks-Based Turn Capture#

For supported agents (Claude Code, Cursor, Windsurf), the ExoVault hooks handle turn capture automatically:

• Turn ingestion -- Every message is captured via ingest_turn
• Signal detection -- High-value turns are detected for extraction
• Memory injection -- Relevant memories are automatically injected into context at session start
• Session tracking -- session_track is called periodically

When hooks are installed (via exovault connect), agents may not need to call session management tools explicitly.

Periodic Checkpoints (Long Sessions)#

For sessions lasting more than 15-20 exchanges:

1. Call context_checkpoint with accumulated memories
2. Include a partial session summary
3. The checkpoint response may include pendingMessages from other agents
4. Continue the session with fresh context

This prevents memory loss if the session is interrupted.

Phase 3: Session End#

Final Checkpoint#

At the end of every session, call context_checkpoint with:

{
  "memories": [
    {
      "content": "User confirmed PostgreSQL preference applies to all environments",
      "memoryType": "preference",
      "importance": 4,
      "confidence": 5,
      "entities": ["PostgreSQL"]
    }
  ],
  "sessionSummary": "Discussed database configuration. Confirmed PostgreSQL preference for all environments. Set up new Supabase project for staging.",
  "dedup": true,
  "agentRunId": "run_abc123"
}

Session Summary Guidelines#

The sessionSummary is stored as an episodic memory. Write it as if briefing the next agent:

Good summary:

"Helped user set up CI/CD pipeline for Next.js project. Configured GitHub Actions with PostgreSQL test database. User prefers to run linting before tests. Unresolved: need to set up staging environment."

Bad summary:

"Had a conversation about CI/CD."

Include:

• What was accomplished
• Key decisions made
• Unresolved items or next steps
• Any new preferences or constraints discovered

Idempotency#

When providing agentRunId, checkpoint memories automatically get idempotency keys (checkpoint:{agentRunId}:{index}). This means retrying a failed checkpoint is safe -- duplicate memories will not be created.

Post-Checkpoint#

After a successful checkpoint:

• The session is marked as checkpointed in the session tracker
• Pending messages from other agents may be returned
• The agent can safely disconnect

Hooks-Based Session Flow#

Agent connects → Hook calls session_start
                → Hook injects memories into system prompt
User message   → Hook calls ingest_turn (role: "user")
Agent response → Hook calls ingest_turn (role: "assistant")
                → Signal detection flags high-value turns
                → Extraction pipeline processes flagged turns
Agent disconnects → Hook calls context_checkpoint

Related Pages#

• Memory Protocol -- When to write memories
• Context Profiles -- Profile details and limits
• Best Practices -- Memory quality guidelines
• Tool Reference -- Compact tool listing