Session Lifecycle

ExoVault tracks agent sessions to maintain continuity across conversations. The session lifecycle ensures agents start with relevant context, checkpoint important knowledge during work, and summarize sessions when they end.

Session Start#

Every agent session should begin with session_start. This tool loads relevant context so the agent can resume where a previous session left off:

{
  "vaultId": "vault-uuid",
  "query": "authentication implementation",
  "agentId": "claude-code",
  "summaryOnly": true,
  "mode": "default"
}

The response includes:

• recentSessions -- Recent episodic memories (session summaries)
• importantFacts -- High-importance facts and knowledge
• activeTasks -- Tasks with status, priority, and doneWhen conditions
• constraints -- Active constraints and rules
• vaults -- Available vaults with note counts
• recentAgents -- Recently active agents
• pendingMessages -- Unread messages for this agent
• memoryHealth -- Embedding indexing status
• queryResults -- Optional query-scoped context via semantic search

Context Modes#

The mode parameter controls how much context is loaded:

Vault Documents#

session_start includes the soul.md document by default. Use the includeDocuments parameter to request additional documents:

{
  "includeDocuments": ["soul", "instructions", "skills", "checks"]
}

Or use read_document to fetch specific documents on demand.

Auto-Session#

If an agent calls any tool without first calling session_start, ExoVault auto-injects session context on the first tool call. This ensures agents always have context even if they skip explicit session initialization.

Context Checkpoint#

Use context_checkpoint to batch-write multiple memories at once, typically at the end of a session or at natural breakpoints:

{
  "memories": [
    {
      "content": "Decided to use JWT with refresh tokens for authentication",
      "memoryType": "fact",
      "importance": 4,
      "confidence": 5,
      "entities": ["JWT", "authentication"]
    },
    {
      "content": "User prefers server components over client components",
      "memoryType": "preference",
      "importance": 3,
      "confidence": 4
    }
  ],
  "sessionSummary": "Discussed auth architecture. Decided on JWT with refresh tokens. Created Auth Design note.",
  "vaultId": "vault-uuid",
  "agentId": "claude-code",
  "dedup": true
}

The sessionSummary is automatically written as an episodic memory with an auto-generated headline.

Checkpoint results report how many memories were created, skipped (by dedup), superseded, or failed. Pending messages for the agent are also delivered during checkpoint.

Session Buffer#

The MCP server maintains an in-memory session buffer that tracks all tool call activity during a session:

• Activities -- tool name, timestamp, category (read/write/search/system), input/output summaries
• Transcript -- richer context entries (up to 500 chars) for episodic generation
• Crash recovery -- buffer is periodically written to disk at ~/.exovault-mcp/sessions/

Turn Ingestion#

Use ingest_turn (or rely on hooks-based auto-capture for supported agents) to record conversation turns for the extraction pipeline:

{
  "role": "user",
  "content": "Please implement the login form with email validation"
}

Ingested turns are processed by the extraction pipeline to automatically extract facts, preferences, and decisions.

Extraction Pipeline#

The extraction pipeline processes session data to create structured memories:

1. Turn accumulation -- Conversation turns are buffered
2. Extraction -- LLM-based analysis identifies facts, decisions, preferences, and tasks
3. Deduplication -- Extracted knowledge is checked against existing memories
4. Memory creation -- New knowledge is written as typed memories
5. Episodic summary -- Session activity is summarized as an episodic memory

Significance Gate#

Not all sessions produce episodic memories. The significance gate filters out low-value sessions:

• Skipped: Sessions with fewer than 5 tool calls, read-only sessions, or sessions where the agent already wrote 3+ memories
• Passed: Sessions with meaningful activity — memory writes, substantial tool usage, or significant conversation

This prevents noisy, low-value episodics from cluttering the vault. Only sessions that pass the gate generate episodic summaries.

Daily Digests#

At 3 AM UTC daily, all sessions from the previous day are automatically consolidated into a single episodic memory — a daily digest. This provides agents with a concise "yesterday" overview at the next session_start, rather than loading multiple individual session summaries.

Daily digests are generated by an Inngest cron function and stored with agentId: "daily-digest".

Checkpoint Reminders#

The auto-session system tracks tool call counts and appends checkpoint reminders at thresholds (10, 25, 50 calls), coaching agents to save their work periodically.

Idle Timeout#

Sessions automatically flush when idle for a configurable period. The session buffer is persisted and the extraction pipeline processes accumulated data.

Next Steps#

• Connecting Agents -- Setup options for automatic turn capture
• Memory Management -- What gets stored as memories
• Vault Documents -- soul.md and instructions