Memories — ConvoMem Docs

Memories are durable facts extracted from customer conversations. They persist across sessions and are retrieved at the start of future interactions.

Extraction is asynchronous

When you ingest a conversation, memory extraction happens in the background. Facts become searchable within a few seconds. Build your flows around recall-then-capture, not capture-then-immediately-recall.

Ingest

Send conversation turns for a known customer to the extraction pipeline. The endpoint returns 202 with a captureId you can poll at GET /capture/:captureId.

Terminal

curl -s -X POST -H "X-API-Key: $CONVOMEM_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.convomem.com/api/v1/customers/f3b39d1b-2522-4a00-98df-8cdde783ba12/memories/ingest" \
  -d '{
    "messages": [
      {"role": "user", "content": "I prefer email over phone"},
      {"role": "assistant", "content": "Noted, I have updated your preference."}
    ],
    "channel": "CHAT"
  }'
# → { "captureId": "0b6f4c1e-3d2a-4e8b-a7c9-5f1d2e3b4a6c", "status": "queued" }

Using an SDK?

The SDKs send turns through capture, which feeds the same extraction pipeline and also resolves the customer and manages the conversation session.

Lookup by topic

Retrieve the most relevant memories for a specific topic. ConvoMem ranks facts by relevance and returns them with a pre-built context string.

const { context, memories } = await client.lookup('billing', {
  customerId: 'f3b39d1b-2522-4a00-98df-8cdde783ba12',
})
 
console.log('Context:', context)
console.log('Memories:', memories.length)

List

List all memories for a customer with pagination.

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

Add manually

Add a memory directly without going through the extraction pipeline. Manual memories are available for recall immediately. Any identity field works; when you omit category, it defaults to context.

const memory = await client.addMemory(
  'Prefers dark mode',
  { email: '[email protected]' },
  { category: 'preference' },
)
 
console.log('Memory ID:', memory.id)

Update

Update an existing memory's content or category. Requires the customer's customerId.

const updated = await client.updateMemory(
  'c2a7e4b1-9f3d-4a6e-8b5c-1d2e3f4a5b6c',
  { content: 'Prefers dark mode and large fonts', category: 'preference' },
  { customerId: 'f3b39d1b-2522-4a00-98df-8cdde783ba12' },
)
 
console.log('Updated:', updated.content)

Delete

Permanently delete a memory. Requires the customer's customerId.

await client.deleteMemory('c2a7e4b1-9f3d-4a6e-8b5c-1d2e3f4a5b6c', {
  customerId: 'f3b39d1b-2522-4a00-98df-8cdde783ba12',
})

Response fields

Memory

Field	Type	Description
`id`	string	Unique memory identifier
`content`	string	The memory in natural language
`category`	string	Category (e.g., `preference`, `account`, `intent`)
`memoryType`	string	Type of memory (e.g., `fact`, `preference`, `commitment`)
`speaker`	string	`customer` or `agent`
`confidence`	number	0–1 extraction confidence (list responses)
`relevance`	number	Per-query relevance score (lookup responses)
`expiresAt`	string \| null	ISO-8601 expiry, if the fact is time-bound (list responses)
`createdAt`	string	ISO-8601 creation timestamp

MemoryContext (lookup response)

Field	Type	Description
`context`	string	Pre-built context string for prompt injection
`tokenCount`	number	Approximate token count of the context
`memories`	Memory[]	Array of relevant memories

What's next

Capture — send conversations to the extraction pipeline
Customers — manage the profiles that own these memories
How it works — extraction pipeline, durability scoring, lookup ranking

SDK: TypeScript · Python · Rust