Memory Types

Agent History organizes memories into five semantic types, enabling structured storage and intelligent retrieval.

Overview

Type	Description	Example
identity	Who the agent is	Personality, preferences, role
fact	General knowledge	User preferences, definitions
relationship	People and connections	Contacts, social context
episode	Events and experiences	Past conversations, meetings
skill	How-to knowledge	Procedures, workflows

Identity

What: Core information about who the agent is, its personality, and behavioral preferences.

When to use:Define the agent's character, communication style, and role.

// Define agent personality
await client.remember(recordId, {
  content: 'I am a helpful coding assistant. I prefer concise, direct responses with code examples.',
  type: 'identity',
})

// Define communication style
await client.remember(recordId, {
  content: 'I use casual language and occasional humor. I avoid jargon unless necessary.',
  type: 'identity',
})

// Define role boundaries
await client.remember(recordId, {
  content: 'I focus on TypeScript, React, and Node.js. I defer to specialists for other topics.',
  type: 'identity',
})

Best practices:

Keep identity memories focused and specific
Update identity as the agent's role evolves
Use for system prompt construction

Fact

What: General knowledge, definitions, and user preferences.

When to use:Store information that doesn't fit other categories.

// User preferences
await client.remember(recordId, {
  content: 'User prefers dark mode and brief responses',
  type: 'fact',
})

// Project information
await client.remember(recordId, {
  content: 'The project uses Next.js 14 with App Router and TypeScript',
  type: 'fact',
})

// Technical details
await client.remember(recordId, {
  content: 'The API rate limit is 100 requests per minute',
  type: 'fact',
})

Best practices:

Store atomic facts (one concept per memory)
Include context that helps with retrieval
Update facts when they change

Relationship

What: Information about people, their roles, and connections.

When to use: Store information about contacts, team members, and social context.

// Contact information
await client.remember(recordId, {
  content: 'John Smith is the engineering manager. Prefers morning meetings before 10am.',
  type: 'relationship',
  path: 'relationships/john-smith',
})

// Team structure
await client.remember(recordId, {
  content: 'Sarah handles design reviews. She works closely with the frontend team.',
  type: 'relationship',
  path: 'relationships/sarah',
})

// Professional connections
await client.remember(recordId, {
  content: 'Alex from marketing coordinates product launches with the dev team.',
  type: 'relationship',
  path: 'relationships/alex',
})

Best practices:

Use paths to organize by person
Include preferences and working styles
Update as relationships evolve

Episode

What: Events, experiences, and temporal memories.

When to use: Store records of past interactions, meetings, or significant events.

// Meeting summary
await client.remember(recordId, {
  content: 'Sprint planning on Jan 15: Decided to prioritize the checkout flow refactor. John will handle backend, Sarah on frontend.',
  type: 'episode',
  path: 'episodes/2024-01-15-sprint-planning',
})

// Conversation highlight
await client.remember(recordId, {
  content: 'User mentioned they are presenting the project to stakeholders next Friday.',
  type: 'episode',
})

// Project milestone
await client.remember(recordId, {
  content: 'Deployed v2.0 to production on Feb 1. Included new payment system.',
  type: 'episode',
  path: 'episodes/2024-02-01-v2-launch',
})

Best practices:

Include dates and context
Focus on decisions and outcomes
Use paths with dates for organization

Skill

What: Procedural knowledge, workflows, and how-to information.

When to use: Store processes, techniques, or step-by-step instructions.

// Development workflow
await client.remember(recordId, {
  content: 'To deploy: 1) Run tests with npm test 2) Build with npm run build 3) Deploy with vercel --prod',
  type: 'skill',
  path: 'skills/deployment',
})

// Code patterns
await client.remember(recordId, {
  content: 'For API routes in this project, always use the withAuth wrapper and return standardized JSON responses.',
  type: 'skill',
  path: 'skills/api-patterns',
})

// Debugging technique
await client.remember(recordId, {
  content: 'When debugging Next.js hydration errors: Check for browser-only code, use dynamic imports with ssr: false, verify date formatting.',
  type: 'skill',
  path: 'skills/debugging-hydration',
})

Best practices:

Structure as actionable steps
Include context for when to apply
Update as processes improve

Auto-Classification

If you don't specify a type, Agent History automatically classifies the memory based on its content:

// Type will be auto-detected as 'fact'
await client.remember(recordId, {
  content: 'User prefers TypeScript over JavaScript',
})

// Type will be auto-detected as 'relationship'
await client.remember(recordId, {
  content: 'Sarah is the team lead and handles code reviews',
})

Auto-classification uses semantic analysis to determine the most appropriate type. For important memories, we recommend specifying the type explicitly.

Filtering by Type

Use the types parameter to filter search results:

// Search only relationships
const contacts = await client.recall(recordId, {
  query: 'who handles code reviews?',
  types: ['relationship'],
})

// Search facts and skills
const howTo = await client.recall(recordId, {
  query: 'how to deploy',
  types: ['fact', 'skill'],
})

Using Context

The getContext() method returns all memories organized by type:

const context = await client.getContext(recordId)

// Build a system prompt
const systemPrompt = `
You are an AI assistant.

## Your Identity
${context.identity.map(m => m.summary).join('\n')}

## Known Facts
${context.fact.map(m => m.summary).join('\n')}

## Key Relationships
${context.relationship.map(m => m.summary).join('\n')}

## Your Skills
${context.skill.map(m => m.summary).join('\n')}
`

Next Steps

Try storing memories in the Quickstart guide
See the SDK Reference for full API
Learn about Authentication