Handoff — ConvoMem Docs

A handoff briefing is a structured snapshot of everything ConvoMem knows about a customer: their full conversation journey, key memories, sentiment trend, open-issue detection, and an AI-written narrative. Designed to be injected directly into a human agent's context the moment they take over.

Get a briefing

const handoff = await client.getHandoff({ email: '[email protected]' })
 
if (handoff.found) {
  console.log('Narrative:', handoff.narrative)
  console.log('Key memories:', handoff.keyMemories)
  console.log('Sentiment:', handoff.sentimentTrend.direction)
  console.log('Open issue:', handoff.openIssue.isOpen)
}

Options

Option	Type	Default	Description
`fresh`	boolean	`false`	Bypass the 10-minute cache to get the latest state
`narrative`	boolean	`true`	Set to `false` to skip the LLM-written summary — faster, structured-data only

const handoff = await client.getHandoff(
  { customerId: 'cust_uuid_123' },
  { fresh: true, narrative: true },
)

Response fields

Field	Type	Description
`found`	boolean	`false` if the customer doesn't exist or has no history
`customer`	Customer	Full customer profile
`journey`	ConversationSummary[]	Recent conversation sessions, newest first
`keyMemories`	Memory[]	Top memories ranked by importance and recency
`sentimentTrend`	object	`{ direction: "positive" \| "neutral" \| "negative" \| "stable", current: number }`
`openIssue`	object	`{ isOpen: boolean, summary?: string }` — unresolved issue detection
`narrative`	string \| null	AI-written paragraph summarizing the customer's history
`narrativeSource`	string	`"generated"`, `"cached"`, or `"skipped"`

Injecting into a human agent

agent-context.ts

const handoff = await client.getHandoff(
  { customerId: escalatedCustomerId },
  { fresh: true },
)
 
const briefing = `
## Customer briefing
 
${handoff.narrative ?? 'No prior history.'}
 
### Key facts
${handoff.keyMemories.map((m) => `- ${m.content}`).join('\n')}
 
### Sentiment
${handoff.sentimentTrend.direction} (score: ${handoff.sentimentTrend.current})
 
### Open issue
${handoff.openIssue.isOpen ? handoff.openIssue.summary : 'None'}
`.trim()

Warm the cache for call queues

When a call enters the queue, call getHandoff() with fresh: false (cheap, cached). Call it again with fresh: true when the agent picks up to include anything that happened while the customer waited.

By customer ID (path-based route)

For direct ID access, the SDK routes to the path-based endpoint:

// With customerId → GET /api/v1/customers/:id/handoff
const handoff = await client.getHandoff({ customerId: 'cust_uuid_123' })
 
// Without customerId → GET /api/v1/customers/handoff?email=…
const handoff = await client.getHandoff({ email: '[email protected]' })

What's next

Customers — manage the profiles behind briefings
Conversations — manage and escalate sessions
Embed — browser widget for customer-facing agent panels

SDK: TypeScript · Python · Rust