Skip to content
ExoVault

Search Documentation

Search across all documentation pages

Memory Management

ExoVault memories are the core data structure for persistent agent knowledge. Each memory has a type, content, importance/confidence scores, entities, and is encrypted with AES-256-GCM before storage.

Memory Types#

TypePurposeExample
factObjective knowledge"The API uses PostgreSQL 16"
skillLearned procedures"To deploy, run npm run build && vercel --prod"
preferenceUser/system preferences"User prefers dark mode and TypeScript"
constraintRules and boundaries"Never use MySQL in production"
taskActionable work items"Implement OAuth2 login flow"
episodicSession summaries"Discussed auth architecture, decided on JWT"
correctionKnowledge updates"API endpoint changed from /v1 to /v2"

Writing Memories#

Use write_memory to persist knowledge:

json
{
  "content": "The project uses Next.js 15 with App Router and server components",
  "memoryType": "fact",
  "importance": 4,
  "confidence": 5,
  "entities": ["Next.js", "App Router", "server components"],
  "vaultId": "vault-uuid",
  "dedup": true,
  "externalWriteId": "agent:run123:fact:nextjs-stack"
}

Key Parameters#

  • importance (1-5): How critical this knowledge is. 5 = mission-critical, 1 = trivial.
  • confidence (1-5): How certain the agent is. 5 = verified, 1 = speculative.
  • entities: People, projects, tools, and concepts for cross-referencing.
  • dedup: When true, the server checks for semantic duplicates before writing. Near-duplicates (>92% similarity) are skipped; partial matches (>80%) supersede the older memory.
  • externalWriteId: Idempotency key. Calling write_memory with the same externalWriteId upserts instead of creating a duplicate.

Searching Memories#

Use search_memories for hybrid retrieval combining semantic search, blind-index keyword matching, and knowledge graph expansion:

json
{
  "query": "database configuration",
  "topK": 10,
  "threshold": 0.4,
  "memoryType": "fact",
  "compact": true
}

The search pipeline:

  1. Semantic signal -- pgvector cosine similarity on embeddings
  2. Blind-index signal -- privacy-preserving keyword matching
  3. Graph expansion -- discovers related memories via knowledge links
  4. RRF fusion -- combines signals with reciprocal rank fusion
  5. Temporal decay -- recency-weighted re-ranking
  6. MMR diversity -- removes redundant results

Use compact: true for summaries, then call read_memories for full content on specific IDs.

Updating Memories#

Use update_memory to modify existing memories without creating duplicates:

json
{
  "memoryId": "mem-uuid",
  "content": "Updated content here",
  "importance": 5
}

Archiving Memories#

Use archive_memory to soft-delete memories. Archived memories are excluded from search by default but can be included with includeArchived: true:

json
{
  "memoryId": "mem-uuid",
  "archived": true
}

Cleanup#

Use cleanup_memories to archive stale or low-value memories in bulk:

  • Old episodic memories (default: >30 days, importance <= 2)
  • Low-importance stale memories (importance <= 1, not updated in 14 days)
  • Failed indexing entries
  • Superseded memories

Set dryRun: true to preview what would be archived.

Corrections and Supersession#

When knowledge changes, create a correction memory with supersededById pointing to the old memory:

json
{
  "content": "API endpoint moved from /v1/users to /v2/users",
  "memoryType": "correction",
  "supersededById": "old-memory-uuid",
  "importance": 4,
  "confidence": 5
}

The old memory is automatically archived and linked via a supersedes relation.

Next Steps#