API Reference

Conversation API

Persistent chat context with automatic memory integration.

createConversation()

Start a new persistent conversation:

const conversation = await engine.createConversation({
  userId: string,
  contextWindow?: number,  // max tokens for context retrieval, default 4096
  metadata?: Record<string, any>,
});
// Returns: Conversation with id, createdAt

addMessage()

Add a message to a conversation. Automatically creates a memory from the message content and tracks emotional state:

await engine.addMessage(conversationId, {
  role: 'user' | 'assistant',
  content: string,
  emotions?: Array<{ label: string, intensity: number }>,
});

getMessages()

Retrieve message history for a conversation:

const messages = await engine.getMessages(conversationId, {
  limit?: number,
  before?: Date,
  after?: Date,
});
// Returns: Array<{ role: string, content: string, emotions: Emotion[], createdAt: Date }>

getContext()

Retrieve relevant context for a new message using adaptive retrieval. Returns memories relevant to the current conversation state, respecting the configured context window:

const context = await engine.getContext(conversationId, {
  query: string,           // the new user message
  maxTokens?: number,      // override context window
});
// Returns: {
//   memories: Memory[],
//   tokenCount: number,
//   strategy: string,      // which retrieval strategy was used
// }

Emotional State per Turn

Each message can include emotional state data. The conversation tracks the emotional trajectory across turns, which is used by the emotional retrieval channel:

await engine.addMessage(conversationId, {
  role: 'user',
  content: 'This bug has been haunting me for hours',
  emotions: [{ label: 'frustration', intensity: 0.8 }],
});

await engine.addMessage(conversationId, {
  role: 'assistant',
  content: 'I found the issue. The connection pool limit was too low.',
  emotions: [{ label: 'relief', intensity: 0.7 }],
});

Automatic Memory Creation

By default, each message in a conversation is automatically stored as a memory with full multi-vector encoding. This can be disabled per conversation:

const conversation = await engine.createConversation({
  userId: 'agent-1',
  autoCreateMemories: false, // disable automatic memory creation
});

PreviousEpisode API