How memory works

After every message your customer sends, Contact Intelligence runs an extraction pipeline to pull out things worth remembering — preferences, facts about their life, named people and pets they mention. These memories are then available to the bot the next time that customer messages you.

The extraction pipeline

Customer sends a message
        │
        ▼
  Mood classification (LLM)
        │
        ▼
  Memory extraction (rule-based, < 10ms)
        │
        ▼
  Entity extraction (rule-based, < 5ms)
        │
        ▼
  Contact state update (streak, stage, churn risk)
        │
        ▼
  Response returned (< 50ms total)

Extraction runs on every customer message. Bot responses are not extracted.

Memory types

Memories have an importance score (0.0–1.0) that starts at a type-specific default and decays slowly over time if the memory is not accessed again. More accessed memories stay important longer.

What triggers a memory

Contact Intelligence extracts memories from patterns in the customer's text:

Memories are deduplicated — if the same fact is mentioned again, it doesn't create a duplicate entry.

Entities

Entities are named things that belong to a contact: a pet, a family member, their employer, a hobby, a place. CI extracts these from the same message alongside memories:

Entities are linked to the memories that mention them. When the bot retrieves memories about Bruno, it also surfaces all Bruno-related context — breed, incidents, dates — without you having to configure anything.

Mood detection

Every customer message is classified into one of seven moods:

The mood is classified by an LLM (haiku tier) with a keyword-based fallback if the LLM times out. The mood and a short adaptation hint are injected into the bot's system prompt before it generates a reply — so the bot automatically adjusts its tone without you having to write mood-specific instructions.

Energy level (high / medium / low) is detected alongside mood and refines the adaptation. A frustrated customer with high energy receives a different response than a frustrated customer who seems drained.

How the bot uses memories

When a customer sends a message, the bot calls GET /context/:id before generating a reply. CI returns:

• The contact's current mood, energy, and relationship stage
• The top 8 most relevant memories (ranked by importance)
• All known entities
• A pre-built context text ready for injection into the system prompt

For contacts with a query parameter (the customer's actual message), CI can also do a semantic search across memories — finding the most relevant facts for what the customer is asking, not just the generically "most important" ones.

Memory budget by relationship stage:

Viewing a contact's memories

In the dashboard: Contact Intelligence → Contacts → [contact] → Memories

Or via the API:

GET /contacts/:id/memories

Response:

{
  "memories": [
    {
      "id": "mem_01j...",
      "memoryType": "fact",
      "content": "Has a golden retriever named Bruno",
      "importance": 0.85,
      "accessCount": 7,
      "entityIds": ["pet:bruno"],
      "createdAt": "2026-03-01T10:00:00Z"
    },
    {
      "id": "mem_02j...",
      "memoryType": "preference",
      "content": "Prefers WhatsApp over email",
      "importance": 0.78,
      "accessCount": 2,
      "entityIds": [],
      "createdAt": "2026-03-05T14:30:00Z"
    }
  ]
}