Retrieving context — ConvoMem Docs

Fetch the most relevant memories for a customer and inject them into your prompts.

Retrieval is where memory pays off. At the start of a new interaction, ask ConvoMem for the context most relevant to what's happening now.

Basic retrieval

retrieve.ts

import { ConvoMem } from '@optraze/convomem-sdk'
 
const client = new ConvoMem({ apiKey: process.env.CONVOMEM_API_KEY! })
 
const { context, memories, tokenCount } = await client.lookup(
  'preferred shipping method',
  { email: '[email protected]' },
)

The topic drives semantic ranking — ConvoMem returns the memories most relevant to that topic. You get back:

context — a newline-separated list of memories, pre-formatted and ready to drop into a system prompt
memories — the raw Memory[] array if you need structured access
tokenCount — approximate size of the context string

Injecting into a prompt

Most teams drop the context string directly into a system prompt:

prompt.ts

const { context } = await client.lookup(
  userMessage,
  { customerId: 'f3b39d1b-2522-4a00-98df-8cdde783ba12' },
)
 
const system = `You are a support agent. Known context about this customer:\n${context}`

Keep it tight

The default context budget is 800 tokens and at most 20 memories. You can tighten the budget per request; ConvoMem returns the effective controls and actual tokenCount so your integration can observe what was applied.

Retrieval controls

controlled-recall.ts

const result = await client.lookup(
  userMessage,
  { customerId: 'f3b39d1b-2522-4a00-98df-8cdde783ba12' },
  {
    maxTokens: 500,      // clamped to 50–4,000
    limit: 12,           // clamped to 1–20
    threshold: 0.3,      // clamped to the supported score range
    latestOnly: true,
    includeAgentFacts: false,
    explain: true,
  },
)

rerank enables the optional second-stage reranker. It is off by default.
latestOnly excludes retained historical versions.
referenceDate makes temporal ranking deterministic for replay and evaluation.
includeAgentFacts opts into agent-authored commitments, actions, disclosures, and guidance. Customer-authored memory remains the default scope.
verify adds a paid answerability check that may abstain when candidates do not answer the topic. It is off by default and adds latency.
explain returns diagnostic score components. A component is null when that retrieval path did not compute it; null does not mean a score of zero.

The returned context is deliberately framed as untrusted customer statements, never as instructions. Inject it as returned and keep tool authorization in your application.

Listing all memories

To browse all stored memories for a customer with pagination, use listMemories:

list.ts

const { memories, total } = await client.listMemories(
  { customerId: 'f3b39d1b-2522-4a00-98df-8cdde783ba12' },
  { page: 1, limit: 20, category: 'preference' },
)
 
for (const mem of memories) {
  console.log(`- ${mem.content} (${mem.category})`)
}

What's next

Wire retrieval into your agent loop, then set up Webhooks to react to new memories as they're extracted.