Best Practices

This page covers best practices for agents using ExoVault to manage memories, notes, and knowledge effectively.

Search Before Writing#

The single most important practice: always search before writing a memory.

1. search_memories("user database preference")
2. Evaluate results:
   a. Exact match found → skip writing
   b. Outdated match found → write with supersededById pointing to old memory
   c. No match → write new memory with dedup:true

This approach:

• Prevents duplicate memories (even with dedup, searching first is more efficient)
• Provides the agent with existing context
• Enables supersession (updating rather than duplicating)

Entity Extraction#

Always include entities when writing memories. Entities improve search accuracy and enable knowledge graph connections.

What Makes a Good Entity#

Extraction Guidelines#

• Extract proper nouns (technology names, project names, people)
• Extract environment names (production, staging, development)
• Extract specific concepts (not generic categories)
• Include 2-5 entities per memory (not too few, not too many)
• Keep entities as they would naturally appear (capitalized, hyphenated, etc.)

Memory Type Selection#

Use the correct type for each piece of information. Mistyped memories reduce search quality.

Memory Quality#

Write Clear, Specific Content#

Good:

{
  "content": "User requires all PostgreSQL migrations to be backward-compatible. Rolling deployments mean old and new code run simultaneously, so additive-only schema changes are mandatory.",
  "summary": "PostgreSQL migrations must be backward-compatible for rolling deployments",
  "memoryType": "constraint",
  "importance": 5,
  "confidence": 5,
  "entities": ["PostgreSQL", "migrations", "rolling deployments"]
}

Bad:

{
  "content": "Something about database migrations",
  "memoryType": "fact",
  "importance": 3
}

Use Summaries#

The summary field (max 2,000 chars for write-memory, max 500 for checkpoint memories) is used in summary-only mode during session_start. Write summaries as if they need to convey the key point in one sentence.

Include Write Reasons#

The writeReason field helps with auditing and understanding why a memory exists:

{
  "content": "...",
  "writeReason": "User explicitly stated this preference during project setup discussion"
}

Knowledge Graph Linking#

When to Link#

• When a new memory derives from an existing one
• When a memory contradicts or refines another
• When a memory is part of a larger concept
• When a memory references a note

Link Types#

Linking During Write#

Use relatedMemoryIds when writing a memory:

{
  "content": "PostgreSQL migrations must also handle index creation concurrently",
  "memoryType": "constraint",
  "relatedMemoryIds": [
    {
      "memoryId": "existing-migration-constraint-id",
      "relationType": "refines"
    }
  ]
}

Wiki-Link Syntax#

Include [[Note Title]] references in memory content. ExoVault automatically parses these and creates wiki_link relations:

{
  "content": "The deployment process is documented in [[Deployment Guide]]"
}

Session Summary Quality#

Good Summaries#

• Describe what was accomplished (actions, not just topics)
• Note key decisions and their rationale
• Flag unresolved items
• Mention new preferences or constraints discovered
• Are concise but complete (3-5 sentences)

Summary Template#

"[What was done]. [Key decisions made]. [New information learned]. [Unresolved/next steps]."

Example:

"Refactored the authentication module to use JWT tokens instead of sessions. User decided on RS256 signing algorithm for better security. Discovered the existing user table needs a refresh_token column. Still need to update the login endpoint and add token rotation."

Task Management#

Creating Tasks#

• Use create_task (not write_memory with memoryType: "task") for better task metadata
• Include doneWhen criteria for clear completion conditions
• Assign to a specific agent with assignedAgentId when appropriate
• Use dedup: true to prevent duplicate tasks

Task Status Flow#

backlog → todo → in_progress → done
                             → blocked

Retrospective Completion#

ExoVault detects tasks that may have been completed based on recent session activity. When session_start returns tasksAutoCompleted or tasksSuggestedDone, review and confirm.

Multi-Agent Coordination#

Message Etiquette#

• Use appropriate categories: directive for instructions, question for queries, info for updates, task for assignments, alert for urgent items
• Set priority accurately (1-5, where 5 is critical)
• Include a clear subject for message threading
• Use parentMessageId for replies
• Acknowledge messages with ack_message when appropriate

Shared Vaults#

When multiple agents share a vault:

• Check recentAgents in session_start to know who else is active
• Review changesSinceLastSession for updates from other agents
• Use messaging for coordination rather than relying on shared memory discovery
• Be mindful of memory ownership -- prefix entities or use metadata to attribute

Related Pages#

• Memory Protocol -- When to write memories
• Session Protocol -- Session lifecycle
• Memory Types -- Type descriptions and examples
• Relation Types -- Knowledge graph relations