Quick start — ConvoMem Docs

This guide walks the complete ConvoMem integration loop: capture a conversation, wait for extraction, then recall context at the start of the next interaction.

1. Install

npx jsr add @optraze/convomem-sdk

2. Initialize

Create an API key from the dashboard. Keys are created inside an agent — the workspace for one bot or use case — so pick the agent this integration belongs to first. New organizations start with one agent already created, so you can just use that.

The key stays bound to that agent: everything you capture with it lands there, and recall only returns that agent's data. Running a support bot and a sales bot? Give each its own agent and its own key. See Authentication.

import { ConvoMem } from '@optraze/convomem-sdk'
 
const client = new ConvoMem({
  apiKey: process.env.CONVOMEM_API_KEY!,
})

3. Capture a conversation

Send conversation turns as they happen. ConvoMem resolves the customer from whatever identity field you provide — no explicit customer creation needed.

await client.capture(
  [
    { role: 'user', content: 'Hi, I need help with my subscription. I am on the Pro plan.' },
    { role: 'assistant', content: 'Of course! I can see your Pro plan. What do you need?' },
  ],
  { email: '[email protected]' },
  { channel: 'CHAT' },
)

4. Recall context

Memory extraction happens in the background. Poll the returned capture ID until it is completed before testing extraction. In later conversations, look up the relevant context:

const { context, memories } = await client.lookup(
  'subscription and plan details',
  { email: '[email protected]' },
)
 
console.log(context)
// → "Alice is on the Pro plan."
console.log(`${memories.length} memories found`)

5. Inject context into your LLM

Drop context into the system prompt before every interaction:

agent.ts

import OpenAI from 'openai'
import { ConvoMem } from '@optraze/convomem-sdk'
 
const client = new ConvoMem({ apiKey: process.env.CONVOMEM_API_KEY! })
const openai = new OpenAI()
 
async function chat(userEmail: string, userMessage: string) {
  // 1. Recall what we know
  const { context } = await client.lookup(userMessage, { email: userEmail })
 
  // 2. Build prompt with memory
  const reply = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: [
      {
        role: 'system',
        content: `You are a helpful support agent.\n\nWhat you know about this customer:\n${context}`,
      },
      { role: 'user', content: userMessage },
    ],
  })
 
  // 3. Capture the exchange
  await client.capture(
    [
      { role: 'user', content: userMessage },
      { role: 'assistant', content: reply.choices[0].message.content! },
    ],
    { email: userEmail },
  )
 
  return reply.choices[0].message.content
}

The agent loop

start of session:  lookup(topic, identity)    → inject context into system prompt
user sends turn:   capture([turns], identity) → queue memory extraction
repeat each turn
end of session:    capture([final turns], identity, { endConversation: true, outcome })

Always recall before capture

Look up context at the start of the session, then capture as the conversation unfolds. Captured memories take a few seconds to become searchable — don't look up immediately after capture.

Next steps

How it works — extraction pipeline, identity routing, durability scoring
Capture — advanced options, idempotency, channel types
Memories — browse, add, update, and delete memories
Customers — resolve identities and manage customer profiles
Handoff — briefings for human agent takeover