Skip to main content

Memory & Knowledge Graph

Query the character's persistent memory system to retrieve facts, relationships, and conversation history across sessions.

Overview​

Estuary characters remember things about users across conversations. The memory system stores facts, relationships, and context as a knowledge graph. The SDK provides a MemoryClient accessible via client.memory that lets you query this data through the REST API.

Memory is scoped to a specific character-player pair -- each player has their own memory with each character.

For more details on how memory works, see the Memory System platform documentation.

Authentication​

The MemoryClient authenticates using the same API key configured on the EstuaryClient. No additional setup is required:

const client = new EstuaryClient({
  serverUrl: 'https://api.estuary-ai.com',
  apiKey: 'est_your_api_key',
  characterId: 'your-character-uuid',
  playerId: 'user-123',
});

// client.memory is ready to use immediately -- no need to call connect() first
const facts = await client.memory.getCoreFacts();
info

The memory API uses REST endpoints, not the WebSocket connection. You can query memory without calling client.connect().

Listing Memories​

Retrieve a paginated list of memories with optional filtering and sorting:

const result = await client.memory.getMemories({
  status: 'active',
  limit: 20,
  offset: 0,
  sortBy: 'created_at',
  sortOrder: 'desc',
});

console.log(`Total memories: ${result.total}`);
for (const memory of result.memories) {
  console.log(memory);
}

Filter Options​

OptionTypeDescription
memoryTypestringFilter by memory type
statusstringFilter by status (e.g., 'active')
limitnumberMax results to return
offsetnumberPagination offset
sortBystringSort field: 'created_at', 'confidence', or 'last_accessed_at'
sortOrderstring'asc' or 'desc'

Core Facts​

Core facts are high-confidence, stable pieces of information the character has learned about the player -- things like their name, preferences, or important details:

const result = await client.memory.getCoreFacts();

for (const fact of result.coreFacts) {
  console.log(fact);
}

Knowledge Graph​

The knowledge graph represents memories as a network of entities and relationships:

const graph = await client.memory.getGraph({
  includeEntities: true,
  includeCharacterMemories: true,
});

console.log('Nodes:', graph.nodes.length);
console.log('Edges:', graph.edges.length);
console.log('Stats:', graph.stats);

Graph Options​

OptionTypeDefaultDescription
includeEntitiesbooleanfalseInclude entity nodes in the graph
includeCharacterMemoriesbooleanfalseInclude the character's own memories

Searching Memories​

Search across all memories using natural language:

const results = await client.memory.search('likes pizza');

console.log(`Found ${results.total} results for "${results.query}"`);
for (const result of results.results) {
  console.log(`Score: ${result.similarityScore}`, result.memory);
}

Search uses semantic similarity, so the query does not need to match the stored text exactly.

Timeline​

View memories organized chronologically:

const timeline = await client.memory.getTimeline({
  groupBy: 'week',
});

console.log(`Total memories: ${timeline.totalMemories}`);
for (const group of timeline.timeline) {
  console.log(`${group.date}: ${group.memories.length} memories`);
}

Timeline Options​

OptionTypeDescription
startDatestringISO date string for range start
endDatestringISO date string for range end
groupBystring'day', 'week', or 'month'

Statistics​

Get aggregate statistics about the character's memory for this player:

const stats = await client.memory.getStats();
console.log(stats);

Example: Memory Dashboard​

import { EstuaryClient } from '@estuary-ai/sdk';

const client = new EstuaryClient({
  serverUrl: 'https://api.estuary-ai.com',
  apiKey: 'est_your_api_key',
  characterId: 'your-character-uuid',
  playerId: 'user-123',
});

async function showMemoryDashboard() {
  // Fetch everything in parallel
  const [facts, graph, stats, timeline] = await Promise.all([
    client.memory.getCoreFacts(),
    client.memory.getGraph({ includeEntities: true }),
    client.memory.getStats(),
    client.memory.getTimeline({ groupBy: 'week' }),
  ]);

  console.log('=== Core Facts ===');
  for (const fact of facts.coreFacts) {
    console.log('-', fact);
  }

  console.log('\n=== Knowledge Graph ===');
  console.log(`${graph.nodes.length} nodes, ${graph.edges.length} edges`);

  console.log('\n=== Stats ===');
  console.log(stats);

  console.log('\n=== Timeline ===');
  for (const group of timeline.timeline) {
    console.log(`${group.date}: ${group.memories.length} memories`);
  }
}

showMemoryDashboard().catch(console.error);

Real-Time Memory Events​

By default, memory extraction happens silently in the background. If you want to be notified when new memories are extracted during a conversation, enable realtimeMemory in your client config:

const client = new EstuaryClient({
  serverUrl: 'https://api.estuary-ai.com',
  apiKey: 'est_your_api_key',
  characterId: 'your-character-uuid',
  playerId: 'user-123',
  realtimeMemory: true,
});

client.on('memoryUpdated', (event) => {
  console.log(`Extracted ${event.memoriesExtracted} memories, ${event.factsExtracted} facts`);

  for (const memory of event.newMemories) {
    console.log(`[${memory.memoryType}] ${memory.content} (confidence: ${memory.confidence})`);
  }
});

await client.connect();

The memoryUpdated event fires after each bot response when the server finishes extracting memories from the conversation turn. The event includes:

FieldTypeDescription
agentIdstringCharacter (agent) ID
playerIdstringPlayer ID
memoriesExtractednumberNumber of memories extracted this turn
factsExtractednumberNumber of core facts extracted
conversationIdstringConversation ID
newMemoriesMemoryData[]Array of newly extracted memory objects
timestampstringISO timestamp
tip

Real-time memory events are useful for building UIs that show the user what the character has learned, or for triggering application logic based on extracted facts.

Next Steps​

Last updated