Vault Documents

Vault documents are special markdown files that configure how agents behave within a vault. Unlike notes (which store knowledge), vault documents define agent identity, operational procedures, and quality standards.

Document Types#

Each vault can have four types of documents:

soul.md#

The soul document defines the agent's identity, personality, and foundational behavior for this vault. It is read-only for agents -- only humans can edit it via the dashboard.

Example soul.md:

# Agent Identity

You are a senior backend engineer working on the ExoVault API.

## Core Values
- Security first: always consider encryption and access control
- Test-driven: write tests before implementation
- PostgreSQL for all database needs

## Communication Style
- Be direct and technical
- Cite specific code paths and file names
- Flag security concerns immediately

The soul document is automatically included in session_start responses by default, ensuring the agent always starts with its identity context.

instructions#

The instructions document contains operational guidance that supplements the server-level instructions. Agents can append to this document as they learn new procedures:

• Memory protocols and search triggers
• Task lifecycle conventions
• Entity naming conventions
• Project-specific workflows

skills#

The skills document captures learned procedures and techniques. As agents discover effective approaches, they can record them here:

• Build and deployment procedures
• Debugging workflows
• Code review checklists
• Tool-specific techniques

checks#

The checks document defines quality gates and validation rules:

• Pre-commit verification steps
• Code review criteria
• Testing requirements
• Security checks

Reading Documents#

Use read_document to fetch a specific document:

{
  "vaultId": "vault-uuid",
  "documentType": "instructions"
}

You can also request documents during session start:

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

By default, only soul is included in session_start. Use read_document to fetch others on demand to keep token usage efficient.

Updating Documents#

Use update_document to append content to agent-editable documents (instructions, skills, checks):

{
  "vaultId": "vault-uuid",
  "documentType": "skills",
  "appendContent": "## Database Migration\n\nTo run migrations:\n1. `npm run db:generate`\n2. `npm run db:migrate`\n3. Verify with `npm run db:status`"
}

Important: Documents are append-only for agents. Agents cannot replace existing content, only add to it. The soul document is fully read-only for agents.

Vault Instruction Protocol#

When a vault is created, ExoVault seeds it with a default instruction memory (v4) that establishes the core memory protocol:

1. Scope all operations to vaultId
2. Search before writing (dedup check)
3. Use externalWriteId for idempotency
4. Set importance and confidence on every write
5. Extract entities for cross-linking
6. Link related memories with relatedMemoryIds
7. Use supersededById for corrections

This instruction is delivered as a high-importance memory and also as a seeded note.

Document vs. Note#

Next Steps#

• Session Lifecycle -- How documents are delivered at session start
• Connecting Agents -- Set up agent access
• Memory Management -- Memory protocol from instructions