A chatbot that remembers every customer

Giulia opens your support chat for the third time this month. A stateless bot asks for her email again, asks what plan she is on again, and has no idea she already reported the same shipping problem twice. She types the whole story a third time.

With Korely in the loop, the same bot opens with: "Hi Giulia, I can see your Advanced plan and the open shipping issue from last week. I'll follow up by email as usual, unless you'd prefer otherwise." Same LLM, same prompt template. The difference is four API calls. This cookbook walks through all four at the function level.

The four calls

1. On chat open: load who she is

Before the first LLM turn, fetch the customer's active facts. This is a deterministic read, pure SQL and graph lookups with no model in the path, so it adds a database query, not an inference call, to your time-to-first-token budget.

from korely_memory import Korely

korely = Korely(api_key="kor_live_...", region="eu")

facts = korely.get_facts(user_id="customer-giulia-4812")

The response is a flat list of her active facts: typed (subject, predicate, object) triples the graph extracts automatically. A fact is live until its invalid_at (null while nothing has closed it); predicate is the canonical relation (the relation as the extractor wrote it is kept in predicate_raw; her own words stay in the memory that source_memory_id points to), and each fact carries a predicate_family for grouping. (Need them grouped by family instead? Call get_profile.)

{
  "facts": [
    { "id": "fct_a1", "subject": "customer-giulia-4812", "predicate": "subscribes_to",
      "object": "Advanced plan", "predicate_family": "other", "predicate_raw": "subscribes_to",
      "valid_from": "2026-05-02T09:14:00Z", "invalid_at": null,
      "invalidated_by": null, "source_memory_id": "mem_91a2" },
    { "id": "fct_a2", "subject": "customer-giulia-4812", "predicate": "has_open_issue",
      "object": "shipping delay, order #88412", "predicate_family": "events",
      "predicate_raw": "has_open_issue", "valid_from": "2026-06-03T16:40:00Z",
      "invalid_at": null, "invalidated_by": null, "source_memory_id": "mem_2b91d4" },
    { "id": "fct_a3", "subject": "customer-giulia-4812", "predicate": "prefers",
      "object": "email follow-ups", "predicate_family": "preferences",
      "predicate_raw": "prefers", "valid_from": "2026-05-19T11:02:00Z",
      "invalid_at": null, "invalidated_by": null, "source_memory_id": "mem_5c0d" }
  ],
  "total": 3
}

Render that into your system prompt as a compact context block and the bot greets her like it knows her, because it does.

2. During the chat: search her history

When she mentions the shipping problem, don't make the LLM guess. Search her memories, scoped to her and only her:

hits = korely.search(
    "shipping complaint",
    user_id="customer-giulia-4812",
    limit=5,
)

What comes back is ranked retrieval, not generated text, semantic vector search (cosine over embeddings) scoped to her user_id. The only model call on the read path is the query embedding, a fraction of a hundredth of a cent. Your bot's own model does the reasoning over the results. Each hit is {id, score, snippet, user_id, agent_id, metadata}, the snippet is the first 280 characters of the memory (read the whole text with get(id) when it is longer):

{
  "results": [
    { "id": "mem_2b91d4", "score": 0.93,
      "snippet": "Order #88412 delayed at the Bologna hub, second report. Promised an email update within 48h.",
      "user_id": "customer-giulia-4812", "agent_id": "support-bot", "metadata": {} },
    { "id": "mem_77c0ae", "score": 0.81,
      "snippet": "First shipping complaint for order #88412. Courier marked the address as incomplete.",
      "user_id": "customer-giulia-4812", "agent_id": "support-bot", "metadata": {} }
  ]
}

Filters are additive (AND): user_id alone searches everything stored about Giulia across every conversation; add run_id to narrow to one session. Another customer's memories can never leak into her results. The scope is enforced server-side, not by prompt discipline.

3. On new info: write it down

Back in May, Giulia mentioned she'd rather not be called on the phone. That is how the email preference in step 1 got there. Store it:

result = korely.add(
    "Prefers email follow-ups, not phone",
    user_id="customer-giulia-4812",
    agent_id="support-bot",
)

The call returns the stored memory immediately. Fact extraction runs after the write returns, so the reply always has status processing and an empty facts list:

{
  "id": "mem_5c0d",
  "content": "Prefers email follow-ups, not phone",
  "user_id": "customer-giulia-4812",
  "agent_id": "support-bot",
  "run_id": null,
  "client": "korely-python/0.1.28",
  "kind": "note",
  "metadata": {},
  "status": "processing",
  "created_at": "2026-05-19T11:02:00Z",
  "updated_at": "2026-05-19T11:02:00Z",
  "facts": []
}

Read the facts with get_facts at the next chat open (or poll GET /v1/events). This is the bi-temporal part: if Giulia previously preferred phone calls and the judge decides the new preference replaces it, the old fact is not deleted when the new one lands. It gets an invalid_at timestamp and an invalidated_by pointing at the new fact, stops being served by the default get_facts, and survives for audit and point-in-time queries (as_of). Ask for the closed facts too and both show up. (The extractor picks the predicate name, so prefers here is an example, not a guaranteed string.)

history = korely.get_facts(
    user_id="customer-giulia-4812",
    predicate="prefers",
    include_invalidated=True,
)

{
  "facts": [
    { "id": "fct_a3", "subject": "customer-giulia-4812", "predicate": "prefers",
      "object": "email follow-ups", "predicate_family": "preferences",
      "predicate_raw": "prefers", "valid_from": "2026-05-19T11:02:00Z",
      "invalid_at": null, "invalidated_by": null, "source_memory_id": "mem_5c0d" },
    { "id": "fct_b0", "subject": "customer-giulia-4812", "predicate": "prefers",
      "object": "phone calls", "predicate_family": "preferences",
      "predicate_raw": "prefers", "valid_from": "2026-03-08T15:30:00Z",
      "invalid_at": "2026-05-19T11:02:00Z", "invalidated_by": "fct_a3",
      "source_memory_id": "mem_14e2" }
  ],
  "total": 2
}

4. On account change: let the contradiction engine work

You don't write supersede logic. When Giulia upgraded on 2 May and the bot (or your billing webhook) wrote "The customer upgraded to the Advanced plan" (the write reply again says processing, with an empty facts list), the contradiction detector (a prefilter picks candidate facts, then a model judges whether the new fact makes the old one false) closed the existing "subscribes to Basic plan" fact and superseded it. The closure is a model's judgement; read with include_invalidated=true to see what was closed. The history read shows both:

korely.get_facts(
    user_id="customer-giulia-4812",
    include_invalidated=True,
)

The extractor chooses the predicate name, so it can vary from one write to the next (here it came out as subscribes_to). Read all the facts with include_invalidated=True and group them on your side, or filter by predicate_family, rather than relying on an exact predicate string.

{
  "facts": [
    { "id": "fct_a1", "subject": "customer-giulia-4812", "predicate": "subscribes_to",
      "object": "Advanced plan", "predicate_family": "other", "predicate_raw": "subscribes_to",
      "valid_from": "2026-05-02T09:14:00Z", "invalid_at": null,
      "invalidated_by": null, "source_memory_id": "mem_91a2" },
    { "id": "fct_a0", "subject": "customer-giulia-4812", "predicate": "subscribes_to",
      "object": "Basic plan", "predicate_family": "other", "predicate_raw": "subscribes_to",
      "valid_from": "2026-02-10T08:00:00Z", "invalid_at": "2026-05-02T09:14:00Z",
      "invalidated_by": "fct_a1", "source_memory_id": "mem_08b3" }
  ],
  "total": 2
}

The write path is where the intelligence runs: embeddings, entity extraction, typed-fact extraction with contradiction checking and bi-temporal validity. All of it is included in the write: one write for every 6,000 characters of a memory, counted against your plan's monthly writes. Nobody edits anything by hand.

Scoping: one agent, unlimited customers

The scoping model is three strings you choose, and it maps one-to-one onto the scoping you already use elsewhere (see the migration guide):

The part that matters for your bill: a support bot serving 10,000 customers is one agent_id with 10,000 user_id values, and end users are unlimited on every tier, including the free one. What's metered is volume: writes (one for every 6,000 characters of a memory) and reads (searches, facts, context, profile) per month (Hobby: 250/25k, Developer at 19 euro + VAT: 2k/250k, Team at 79 euro + VAT: 8k/1M). Reads are retrieval, not generation, which is why every plan allows at least a hundred times more reads than writes. No overage billing: a quota.warning webhook fires at 80% of the monthly writes, and past a 10% grace you get a clean 429, never a surprise invoice.

Why not just stuff the history into the prompt?

Prompt-stuffing is the default pattern, and it makes chatbots expensive and forgetful at the same time. Three concrete reasons:

• Token cost. Re-sending a 20-turn history is thousands of tokens, every turn, forever, and it grows with every message. A facts block from get_facts is a few hundred tokens, fetched once at chat open, and it grows with what's worth remembering, not with conversation length.
• Staleness. A raw history contains both "I'm on Basic" (March) and "I upgraded to Advanced" (May), and you're trusting the LLM to pick the right one every single time. When the judge closes the superseded fact, get_facts returns only the facts that are valid now.
• Forgetting. When Giulia says "forget my data", deleting her from conversation logs scattered across your own database is a project. With Korely it's one call, DELETE /v1/users/customer-giulia-4812/memories, and every memory and fact stored for her user_id in that project is physically deleted (the audit row keeps only counts and a pseudonym).

The trust angle

This deployment takes two shapes, and the data-ownership story differs:

• A "what you remember about me" screen: the end user sees what the bot remembers, because your UI lists get_profile and wires Correct and Forget to correct_fact and forget_fact. Correcting what the bot knows, and closing what is no longer true, become product features the user controls, not a support ticket; a "delete my data" button calls delete_all(user_id=...) for erasure.
• Pure B2B2C (the Giulia scenario, she's your customer, not ours): you own the data, and the deletion surface is API-side. Your privacy policy, your deletion endpoint wiring, our one-call bulk delete underneath. Memories are stored in the EU (Helsinki) either way. Choose the Europe processing region for the project if the text must also be read by a model in the EU.

Where to go next

Temporal facts explains supersede and point-in-time queries under the hood; memory model covers the full scoping model; the REST API reference is the published contract the snippets above come from.