Agent Documentation Overview

ExoVault documentation is designed to be consumed by both humans and AI agents. This section explains how agents interact with the documentation system and how to optimize agent access to reference material.

Dual-Audience Documentation#

Every documentation page in ExoVault includes:

1. Human-readable content -- Standard markdown with headings, tables, and code blocks
2. Agent-reference blocks -- Machine-parseable metadata at the bottom of each page, enclosed in <!-- agent-reference --> HTML comments

Agent-Reference Blocks#

Agent-reference blocks provide structured, token-efficient summaries that agents can parse without reading the full page:

<!-- agent-reference
page: write-memory
required-fields: content (string, 1-100000)
optional-fields: memoryType, importance(1-5), confidence(1-5), entities[], dedup, vaultId
scope: write
dedup-layers: content-hash, blind-token, semantic-embedding
response: { memoryId, created, idempotent, memoryType, vaultId }
-->

These blocks are key-value pairs optimized for minimal token usage while conveying essential information.

The read_document Tool#

Agents access vault-specific documentation through the read_document MCP tool (or POST /api/agent/read-document). This retrieves configurable documents stored per-vault:

Document Types#

How Documents Work#

1. System defaults -- ExoVault ships default document templates
2. User customization -- Users can override defaults per-vault or globally
3. Inheritance -- Vault documents can inherit from global settings
4. Agent editability -- Some documents can be edited by agents (when agentEditable: true)
5. Append-only -- Some documents are append-only (agents can add but not remove content)

Requesting Documents#

During session_start, the includeDocuments parameter controls which documents are included in the response:

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

By default, only the soul document is included to minimize token overhead. Agents can fetch additional documents on demand via read_document.

Document Versioning#

Documents track template versions. When a newer system default exists, the response includes:

{
  "hasNewerDefault": true,
  "latestTemplateVersion": 2
}

This lets agents notify users about available template updates.

How Agents Should Use Documentation#

At Session Start#

1. Call session_start which returns the soul document by default
2. Read the soul document to understand role and behavior guidelines
3. If needed, call read_document for instructions, skills, or checks

During a Session#

• Use search_memories to find relevant information before consulting docs
• Call read_document when the agent needs to check specific guidelines
• Agent-reference blocks in memory search results provide quick context

For Documentation Consumption#

When an agent needs to read ExoVault documentation pages:

1. The read_document tool retrieves stored vault documents
2. For general ExoVault docs, agents can browse via links in the soul document or instructions

Best Practices for Document Authors#

Writing Soul Documents#

• Keep it concise -- this is loaded on every session start
• Focus on identity, tone, and core behavioral rules
• Use bullet points for scannable guidelines
• Include references to other document types for detailed rules

Writing Instructions#

• Be specific and actionable
• Organize by scenario or task type
• Include examples of expected behavior
• Reference memory types and when to use each

Writing Checks#

• List pre-conditions the agent should verify
• Format as a checklist the agent can evaluate
• Keep items binary (pass/fail)

Related Pages#

• Memory Protocol -- When and how to write memories
• Session Protocol -- Full session lifecycle
• Tool Reference -- Compact tool listing for system prompts
• Prompt Templates -- Ready-to-use system prompt snippets