Memory Types

ExoVault supports seven memory types, each serving a distinct purpose in an agent's knowledge system. Choosing the correct type improves search quality, deduplication accuracy, and context relevance.

fact#

Purpose: Objective information about the user, project, environment, or domain.

Typical importance: 3-4 Typical confidence: 3-5

Facts represent verifiable, objective information. They answer "what is" questions.

Examples#

{
  "content": "The production database is PostgreSQL 15 hosted on Supabase with pgvector enabled for vector search",
  "memoryType": "fact",
  "importance": 4,
  "confidence": 5,
  "entities": ["PostgreSQL", "Supabase", "pgvector", "production"]
}

{
  "content": "The project uses Next.js 14 with the App Router and TypeScript strict mode",
  "memoryType": "fact",
  "importance": 3,
  "confidence": 5,
  "entities": ["Next.js", "App Router", "TypeScript"]
}

When to Use#

• Technology stack details
• Project architecture decisions
• Environment configurations
• User profile information
• Domain knowledge relevant to the project

When NOT to Use#

• User opinions or preferences (use preference)
• Rules and restrictions (use constraint)
• Temporary information that changes frequently

skill#

Purpose: Learned patterns, techniques, workflows, or project-specific knowledge that helps the agent perform better.

Typical importance: 3-4 Typical confidence: 3-4

Skills represent "how to" knowledge -- things the agent learned about working effectively in this context.

Examples#

{
  "content": "In this codebase, database queries use Drizzle ORM with the pattern: db.select().from(table).where(conditions). Always use parameterized queries, never raw SQL interpolation.",
  "memoryType": "skill",
  "importance": 4,
  "confidence": 4,
  "entities": ["Drizzle ORM", "database queries", "parameterized queries"]
}

{
  "content": "When creating API routes in this project, follow the pattern: validate with Zod schema, call requireAgentAuth/requireAuth, then use handleRouteError wrapper for consistent error handling.",
  "memoryType": "skill",
  "importance": 4,
  "confidence": 5,
  "entities": ["API routes", "Zod", "error handling"]
}

When to Use#

• Coding patterns specific to this project
• Workflow procedures the agent should follow
• Debugging techniques that worked
• Build/deploy procedures
• Tool usage patterns

When NOT to Use#

• Objective facts about the environment (use fact)
• User preferences about style or approach (use preference)

preference#

Purpose: User preferences, opinions, and choices that should influence agent behavior.

Typical importance: 4-5 Typical confidence: 4-5

Preferences represent subjective choices. The agent should respect and remember them across sessions.

Examples#

{
  "content": "User prefers PostgreSQL over MySQL for all database needs in production and development",
  "memoryType": "preference",
  "importance": 5,
  "confidence": 5,
  "entities": ["PostgreSQL", "MySQL", "database"]
}

{
  "content": "User wants concise code comments that explain 'why' not 'what'. No JSDoc for internal functions, only for public API.",
  "memoryType": "preference",
  "importance": 4,
  "confidence": 5,
  "entities": ["code comments", "JSDoc"]
}

When to Use#

• Technology choices ("prefer X over Y")
• Style preferences (naming conventions, formatting)
• Communication preferences (level of detail, tone)
• Workflow preferences (how they like to work)

When NOT to Use#

• Hard rules that must never be violated (use constraint)
• Objective information (use fact)

constraint#

Purpose: Rules, restrictions, and mandatory practices that must always be followed.

Typical importance: 4-5 Typical confidence: 4-5

Constraints are non-negotiable rules. Violating a constraint is considered an error.

Examples#

{
  "content": "Never use 'any' type in TypeScript unless truly unavoidable. Always use proper generics and type narrowing.",
  "memoryType": "constraint",
  "importance": 5,
  "confidence": 5,
  "entities": ["TypeScript", "any type", "generics"]
}

{
  "content": "All database tables must have Row Level Security (RLS) enabled. Service role bypass is only acceptable in server-side API routes, never in client code.",
  "memoryType": "constraint",
  "importance": 5,
  "confidence": 5,
  "entities": ["RLS", "Row Level Security", "service role", "database"]
}

When to Use#

• Security requirements ("never expose X")
• Code quality rules ("always do Y")
• Compliance requirements
• Architectural constraints
• Team conventions that are mandatory

When NOT to Use#

• Soft preferences ("I'd prefer X") -- use preference
• General facts -- use fact

task#

Purpose: Action items, to-dos, and work tracking.

Typical importance: 3-5 (maps to priority) Typical confidence: 3-5

Tasks track work that needs to be done. They have status, priority, and optional assignment.

Examples#

{
  "content": "Add input validation to the /api/agent/write-memory endpoint for the metadata field",
  "memoryType": "task",
  "importance": 4,
  "confidence": 5,
  "entities": ["input validation", "write-memory", "metadata"],
  "metadata": {
    "taskStatus": "todo",
    "assignedAgentId": "claude_code",
    "doneWhen": "metadata field validates against a Zod schema that rejects functions and circular references"
  }
}

Task Statuses#

When to Use#

• User assigns work to be done
• Agent identifies needed improvements
• Bug reports that need tracking
• Feature requests

Note#

Prefer the create_task tool over write_memory with memoryType: "task". The create_task tool provides better task-specific fields like title, description, status, assignedAgentId, and doneWhen.

episodic#

Purpose: Session summaries and event records that capture what happened during a conversation.

Typical importance: 2-3 Typical confidence: 5

Episodic memories provide a chronological record of sessions. They are the primary source for "what happened last time" context.

Examples#

{
  "content": "Session focused on refactoring the authentication module. Migrated from session-based auth to JWT tokens with RS256 signing. User decided to use refresh token rotation. Discovered the user table needs a refresh_token column. Next: update login endpoint.",
  "summary": "Refactored auth to JWT (RS256) with refresh token rotation",
  "memoryType": "episodic",
  "importance": 2,
  "confidence": 5,
  "entities": ["authentication", "JWT", "RS256", "refresh tokens"]
}

When to Use#

• Automatically at session end (via context_checkpoint)
• Summarizing significant events within a long session

When NOT to Use#

• Episodic memories should not be written manually during a session. Use context_checkpoint at session end, which automatically creates an episodic memory from the sessionSummary.

Summary Generation#

ExoVault auto-generates a headline from the episodic content for display in agent lists and session history. Write episodic content as complete summaries, not just headlines.

correction#

Purpose: Records when the user corrected the agent, capturing both what was wrong and what is right.

Typical importance: 4-5 Typical confidence: 5

Corrections are high-value memories that prevent the agent from repeating mistakes.

Examples#

{
  "content": "CORRECTION: The API uses POST for all agent routes, not GET. Previously assumed search endpoints used GET, but they are all POST with JSON body.",
  "memoryType": "correction",
  "importance": 5,
  "confidence": 5,
  "entities": ["API routes", "POST", "GET"]
}

{
  "content": "CORRECTION: The project uses pnpm, not npm. Build commands should use pnpm run build, not npm run build.",
  "memoryType": "correction",
  "importance": 4,
  "confidence": 5,
  "entities": ["pnpm", "npm", "build commands"]
}

When to Use#

• User explicitly corrects the agent
• Agent discovers its previous assumption was wrong
• A fact or skill is found to be outdated

Best Practices#

• Include both the incorrect assumption and the correct information
• Prefix with "CORRECTION:" for clarity
• Set importance 4-5 (corrections must be remembered)
• Set confidence 5 (the user confirmed the correction)
• Link to the memory being corrected via relatedMemoryIds with contradicts relation

Memory Type Distribution#

For a healthy vault, expect roughly this distribution:

Related Pages#

• Memory Protocol -- When and how to write memories
• Best Practices -- Quality guidelines
• Relation Types -- Knowledge graph relations
• Agent Routes -- write-memory and create-task API details