TypeScript SDK

The ConvoMem TypeScript SDK works in Node.js, Deno, Bun, and edge runtimes. Published to JSR as @optraze/convomem-sdk.

Install

# npm / Node
npx jsr add @optraze/convomem-sdk
 
# pnpm
pnpm i jsr:@optraze/convomem-sdk
 
# bun
bunx jsr add @optraze/convomem-sdk
 
# deno
deno add jsr:@optraze/convomem-sdk

Initialize

import { ConvoMem } from '@optraze/convomem-sdk'
 
const client = new ConvoMem({
  apiKey: process.env.CONVOMEM_API_KEY!, // required
  timeout: 10_000,                        // optional — ms (default 30 000)
  maxRetries: 3,                          // optional — retries on 429 / 5xx
})

Keep keys server-side

Never expose an API key in client-side code. All ConvoMem calls should originate from your backend or an edge function. For browser widgets, use embed tokens.

ConvoMem (primary class)

Flat API — every method accepts a CustomerIdentity and routes to the correct endpoint. Use this for all new integrations.

Memory methods

Method	Description
`capture(messages, identity, options?)`	Send conversation turns for background extraction
`lookup(topic, identity, options?)`	Recall relevant memories as a ready-to-use context string
`listMemories(identity, options?)`	Page through all memories for a customer
`addMemory(content, identity, options?)`	Write a memory directly (synchronous, no extraction lag)
`updateMemory(memoryId, data, identity)`	Update content or category (requires `customerId`)
`deleteMemory(memoryId, identity)`	Delete a memory permanently (requires `customerId`)

Customer methods

Method	Description
`createCustomer(data)`	Create a new customer profile
`getCustomer(identity)`	Get a customer by any identity field
`listCustomers(options?)`	List all customers with pagination and filters
`updateCustomer(identity, data)`	Update customer fields (metadata is merged)
`deleteCustomer(identity)`	Delete a customer and all their data
`getStats(options?)`	Aggregate memory and conversation stats for the org
`listMergeCandidates()`	List profiles flagged as potential duplicates
`dismissMergeCandidate(customerId, candidateId)`	Mark a duplicate pair as a false positive

Conversation methods

Method	Description
`startConversation(identity, options)`	Begin a new conversation session
`endConversation(conversationId, identity, options?)`	Mark a conversation completed
`escalateConversation(conversationId, identity, options?)`	Escalate to a human agent
`listConversations(identity, options?)`	List a customer's conversation sessions

Handoff & embed

Method	Description
`getHandoff(identity, options?)`	Full cross-channel briefing for a human takeover
`createEmbedToken(identity, options?)`	Mint a short-lived browser token

ConvoMemClient (advanced)

Resource-based client — organized as client.customers.*, client.memories.*, client.conversations.*, client.embed.*. Use this for direct path-based access without identity routing.

import { ConvoMemClient } from '@optraze/convomem-sdk'
 
const client = new ConvoMemClient({
  apiKey: process.env.CONVOMEM_API_KEY!,
})
 
const customer = await client.customers.get('cust_uuid_123')
const { memories } = await client.memories.list('cust_uuid_123')

CustomerIdentity

All ConvoMem methods that operate on a customer accept a CustomerIdentity object. Provide at least one field:

interface CustomerIdentity {
  customerId?: string   // ConvoMem UUID — most direct
  externalId?: string   // Your CRM / system ID
  email?: string
  phone?: string        // E.164 preferred (+14155550101)
}

With customerId → path route (/customers/:id/*)
Without customerId → flat route (/customers/*?email=…) — server resolves

Error handling

import { ConvoMemApiError } from '@optraze/convomem-sdk'
 
try {
  await client.capture([...turns], { email: '[email protected]' })
} catch (err) {
  if (err instanceof ConvoMemApiError) {
    console.error(err.status, err.body) // { status: 401, body: { error: '...' } }
  }
}

Property	Type	Description
`status`	number	HTTP status code
`body`	unknown	Parsed response body
`url`	string	Full request URL

Cancellation

Pass an AbortSignal to cancel any in-flight request:

const controller = new AbortController()
 
const result = await client.lookup(
  'billing',
  { email: '[email protected]' },
  { signal: controller.signal },
)
 
// Cancel:
controller.abort()

TypeScript types

Key types exported from @optraze/convomem-sdk:

import type {
  CustomerIdentity,
  Customer,
  Memory,
  MemoryContext,
  CaptureResponse,
  Conversation,
  HandoffResponse,
  EmbedTokenResponse,
  CustomerStats,
  MergeCandidate,
} from '@optraze/convomem-sdk'