How it works

ConvoMem sits between your AI agent and your customer data. This page covers the full pipeline, the data model, and the identity routing pattern that every API method uses.

The pipeline

capture()  →  extract  →  store  →  lookup()

1. Capture — You send conversation turns to POST /capture. ConvoMem resolves or creates the customer, associates turns with the active conversation session, and enqueues them for extraction. The response is immediate.

2. Extract — An AI pipeline reads a bounded history window plus the new source turns. Each candidate must cite a new source turn, preserve its speaker, and be independently usable. Unsupported, unresolved, or unsafe candidates fail closed before persistence.

3. Store — Memories are indexed for semantic search, linked to the customer, and available within a few seconds of capture.

4. Lookup — You call lookup(topic, identity) and receive a pre-ranked context string — ready to drop into a system prompt.

Data model

Agents

An agent is a workspace inside your organization — typically one per bot or use case, like a support line and a sales line. Each agent has its own capture prompt, API keys, webhooks, and data.

Agents are an isolation boundary: conversations, memories, and insights captured by one agent are invisible to the others. Your support agent never sees what the sales agent learned, unless you explicitly ask for a cross-agent view in the dashboard.

Customers

Customers are shared across your whole organization — one person is one customer record, no matter how many agents they talk to. ConvoMem creates a customer automatically on first contact — no explicit creation required.

Everything hanging off that customer, though, belongs to the agent that captured it. If someone contacts support and later talks to sales, you get one customer with two separate conversation and memory sets.

Memories

Memories are atomic facts extracted from conversation turns.

Durability scoring — "Prefers email over phone" is durable. "Asking about order #4471" is ephemeral. Durability lets retrieval weight long-lived context higher and age out transient facts automatically.

Lookup ranking — Semantic, keyword, temporal, importance, and lifecycle signals rank the candidate set. The default response is capped at 20 memories / 800 tokens; bounded per-request controls let an integration use a smaller context window.

Conversations

A conversation tracks a customer session across multiple captures. ConvoMem automatically reuses the active session for subsequent captures from the same customer and channel until the session is explicitly ended or times out.

Identity routing

Every SDK method that operates on a customer accepts a CustomerIdentity:

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

Provide at least one field. The SDK picks the right HTTP form automatically:

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

// All of these work — use whatever you have:
await client.lookup('billing', { customerId: 'f3b39d1b-2522-4a00-98df-8cdde783ba12' })
await client.lookup('billing', { email: '[email protected]' })
await client.lookup('billing', { externalId: 'crm-789' })
await client.lookup('billing', { phone: '+14155550101' })

PII redaction

Before any extracted memory is persisted, ConvoMem applies mandatory secret filtering and the organization's configured sensitive-data policy. Depending on policy, recognized values are masked with typed placeholders or the candidate is dropped. Conversation transcripts have their own retention and access controls; memory filtering is not a substitute for avoiding unnecessary sensitive input.

By default, card numbers, bank accounts, and national ID numbers are masked — for example 4111 1111 1111 1111 → •••• 1111 and an IBAN → [redacted:bank]. Email addresses and phone numbers are not masked by default; when an admin enables those categories they are stored as [redacted:email] and [redacted:phone]. See Authentication & security for the full list.

Manual memories

You can also write memories directly — bypassing extraction entirely. Manual memories are written synchronously and available for recall immediately (no extraction lag):

await client.addMemory(
  'Prefers to be contacted by email, not phone',
  { email: '[email protected]' },
  { category: 'preference' },
)

Use this to seed memory from your CRM, port data from another system, or correct an extracted memory.

Explore

• Quick start — end-to-end integration example
• Capture — send conversations to the pipeline
• Memories — browse, add, and manage stored memories

SDK: TypeScript · Python · Rust