# Customer Memory

> The AI keeps a short note on each customer, so every agent knows the story before replying

Source: https://docs.soosh.io/features/customer-memory/

Customer memory gives every contact a short, always up-to-date note that agents see beside the chat. After a conversation goes quiet, your AI provider reads what happened and updates the note. It works for any kind of business (a shop, clinic, school, agency, hotel or property dealer) and answers what an agent needs before replying:

- **Stage**: where the customer stands: new, exploring, ready to buy, customer, needs support, at risk, not interested, or not relevant (spam, a wrong number, a test).
- **Mood**: shown only when it matters: happy, frustrated or angry.
- **Summary**: one or two sentences on who the customer is and where things stand now.
- **Next step**: the one thing to do next, such as "Send the price list for a Shopify store".
- **Open**: what your team still owes the customer, with the day it came up. These are promises your team made ("Promised", marked **Overdue** once their day has passed), unresolved problems ("Open issue"), and questions nobody answered ("Unanswered").
- **Details**: facts an agent would look up, as a label and value. The labels suit your business: name, email, city, budget, size, preferred time, appointment, course, property type and so on.
- **Orders and bookings**: orders, bookings, payments and invoices, with their number, amount and status. These come from your connected store and from what the chat shows, such as an order confirmation.
- **Notes**: anything else worth remembering, such as past problems or how the customer likes to be treated.

An agent who picks up a chat can read the card instead of scrolling back through weeks of messages.

## Turning it on

1. Go to **Chatbot → Settings → AI**.
2. Choose an **AI provider** and enter its **API key**, if you haven't already. Customer memory uses the same provider as AI replies.
3. Switch on **Customer memory**.
4. Optionally, pick a **Model for customer memory**. See [Choosing a model](#choosing-a-model).
5. Save.

Customer memory works on its own: **AI replies can stay off**. If the reply settings are hidden because AI replies are off, the memory model is still shown.

> **Note:** Memory starts with conversations from the last 7 days. Older chats are not read in bulk when you switch it on. A contact's memory starts the next time they talk to you.

## Where agents see it

Open a chat and look at the contact panel on the right. The **Customer memory** card shows everything above. At the bottom it says when the AI last updated it, and how many new messages it hasn't read yet. Press that line to update it.

The card updates live. When the memory changes, everyone with that chat open sees the new version without reloading.

### When the memory updates

The AI reads a conversation **30 minutes after it goes quiet**, meaning nobody has written for 30 minutes. One exchange gives one update, not one per message.

If you need it sooner, for example right before handing a chat over, press **Update from the latest messages** on the card. A refresh can run once a minute per contact.

A long, busy conversation is read in parts over several updates, oldest messages first, so nothing is skipped. While that happens the card says "Still reading earlier messages…".

### What the AI reads

The AI reads more than the text messages:

- **Calls**: who called, whether anyone answered and for how long, and the agent's after-call notes.
- **Handovers** between the AI assistant and your team, so it knows when "transfer me" was handled.
- **Internal notes** your agents write about the customer.
- **Media**, by name: a voice note (not transcribed, but it counts as a reply), a document and its file name, an image's caption, a shared location or contact card.
- **WhatsApp Flow forms**: the customer's answers, field by field.
- **Your connected store's orders**, so it doesn't note them twice.

Messages from one-time code templates are never sent to the AI.

### Rebuild from the whole chat

If a memory has gone wrong, open the **⋮** menu on the card and choose **Rebuild from the whole chat**. The AI clears what it wrote and reads the conversation again from the first message. What agents wrote, pinned or removed stays. A long chat takes a few minutes and costs one AI call per 80 messages.

When Soosh changes how memory works, each memory is rebuilt this way once, the next time that customer writes or an agent updates it.

## What agents can do

Agents can correct the memory, and the AI respects those corrections:

| Action | What happens |
|---|---|
| **Add something to remember** | Adds a note, or a detail if you write it as "Label: value" (for example "Budget: 50,000"). The AI never changes or removes it, and a detail you write replaces the AI's detail with the same label. |
| **Edit** a detail or note | It becomes the agent's. The AI no longer changes it. |
| **Pin** a detail or note | Keeps it at the top, exactly as it is. The AI won't touch it. |
| **Remove** a detail or note | Deletes it, and the AI won't add it back. |
| **Mark as done** on an open item | Closes it. The AI won't reopen the same item for a week. After that, the same words can be a new promise or question. |

Hover over a detail or note to see whether it was **Noted by AI** or **Written by an agent**. Agent-written ones are marked with ✎.

Every correction is recorded, so the AI learns what your team removed or fixed.

## Who can see it

- Customer memory is its own workspace component (it needs AI replies and knowledge) with its own permission: viewing the memory needs **customer memory read** (`chatbot.memory:read`) and changing it needs **customer memory write** (`chatbot.memory:write`), on top of access to the chat (**chat read** or **contacts read**). Agents only see memories for the chats they can open. Roles that could view or change memory through chat or contacts permissions got the matching customer memory permissions when it was split out.
- If **Agents See Current Conversation Only** is on (under **Chatbot → Settings → Human agents**), agents without **contacts read** do not see customer memory. The memory draws on earlier conversations, which those agents can't open. Admins and managers with contacts access still see it.
- When a contact is deleted, their memory and every correction made to it are deleted for good.

## Privacy and sensitive data

The AI keeps health or money details (an allergy, a budget, an insurance policy) only when the customer gave them and they matter for your service. It is told never to record payment card numbers, passwords, one-time codes, bank account numbers or government ID numbers.

As a safety net, Soosh also scrubs anything that looks like a card number, a long account or ID number, an IBAN, or the value of a password, PIN or code before saving a memory. The same applies to facts agents type in.

The messages themselves are sent to **your** AI provider under **your** API key, so that provider's data terms apply.

> **Careful:** The scrubbing catches common patterns, not every possible way of writing a secret. Ask customers not to send passwords or card details in chat, and remove any fact that shouldn't be there.

## Choosing a model

Every update is one call to your AI provider, billed to your API key. A memory note is short, so it doesn't need the model you may use for replies.

By default (**Smallest, recommended**), memory uses the provider's smallest model:

| Provider | Default memory model |
|---|---|
| OpenAI | `gpt-4o-mini` |
| Anthropic | `claude-haiku-4-5` |
| OpusMax | `claude-haiku-4-5-20251001` |
| Google | Same as the reply model, or pick one |

Google has no fixed default because its small models are retired often. If you use Google and AI replies are off, choose a memory model yourself.

If you change the AI provider, the memory model goes back to the new provider's default.

## Keeping costs down

Soosh only calls the AI when there is something worth reading:

- **Quiet conversations only.** Updates wait for 30 minutes of silence, so a long back-and-forth costs one call, not dozens.
- **Small talk is skipped.** If the new messages are only "ok", "thanks 👍", greetings, reactions, automated messages such as campaigns, or call-permission taps, no call is made. Anything else counts, however short ("Size 43, not 42"), and so does media a person sent.
- **A size limit per update.** Each call reads at most 80 messages, trimmed to fit a fixed size, and only messages since the last update.
- **Refresh has a cooldown** of one minute per contact.
- **Failures back off.** If your provider fails (an invalid key or no quota left), memory retries after 15 minutes, and the last error is shown on the card.

To spend less:

- Keep the **Smallest** model unless the notes aren't good enough.
- Turn customer memory off if your team doesn't use the card.

## Troubleshooting

| What you see | What to do |
|---|---|
| "Turn on Customer memory in Chatbot settings → AI" | Customer memory is off, or no AI provider and key are set up. |
| "Nothing remembered yet" | The conversation hasn't been quiet for 30 minutes yet, or held only small talk. Press **Update from the latest messages** to read it now. |
| "The last update didn't work: …" | Your AI provider refused the call. Check the API key, quota and model under **Chatbot → Settings → AI**. It retries on its own. Only people who can change chatbot settings see the provider's message. |
| "Memory is paused…" | What agents see for the same problem. Ask an admin to check **Chatbot → Settings → AI**. |
| The memory says something wrong | Remove or edit it, or use **Rebuild from the whole chat**. |
| "The memory was just updated; try again in a minute" | Refresh cooldown. Wait a minute. |
| The card is missing for some agents | **Agents See Current Conversation Only** is on, and those agents lack contacts read. See [Who can see it](#who-can-see-it). |

Developers can find how it works under the hood in the developer guide.