Agent memory
With memory on, an agent remembers facts about each of your customers from one conversation to the next. Examples are their name, preferred language, an open order or a callback it promised. When the same customer comes back on any channel the agent knows them by, it picks up where it left off, without asking for everything again.
Memory is off by default. While it is off, nothing is stored or recalled, and the agent's prompts are exactly what they are without the feature.
Turning memory on
Memory needs two switches, and both must be on.
- Organization consent. An organization admin opens Organization → General → Data & privacy and turns on Remember customers. This is your organization agreeing that the platform may store facts about your end customers on your behalf.
- The agent's switch. Open the agent, choose Memory, and turn on Customer memory on the Settings tab.
You can configure an agent's memory before your organization gives consent. Nothing is stored until consent is on.
If you turn Remember customers off, every agent in the organization stops recalling and saving memories at once. Memories already stored are deleted 30 days later, unless you turn consent back on before then. The date is shown in the console.
Memory settings
On the agent's Memory → Settings tab you can set:
| Setting | Default | Range | What it does |
|---|---|---|---|
| Max memories injected | 8 | 1 to 50 | How many of the customer's most relevant memories the agent sees at the start of a conversation. It can look up others mid-conversation. |
| Retention (days) | 180 | 0 to 3,650 | A memory is deleted this many days after it was last written. 0 deletes memories at the next daily clean-up. |
| History budget (tokens) | 6,000 | 500 to 200,000 | In text conversations, earlier turns past this budget are summarised instead of resent in full. This keeps long chats, such as WhatsApp threads, fast. It applies whether memory is on or off. |
| Extraction instructions | (empty) | Up to 2,000 characters | Extra guidance for what to remember, for example "Remember order numbers and preferred language." It is added to the built-in rules, which already skip payment details and one-time codes. |
| Phone caller-ID disclosure | Contextual | Contextual: on calls, the agent uses memories to personalize but doesn't reveal personal details until the caller confirms who they are, because caller ID can be spoofed and phones can be shared. Trusted: the agent treats caller ID as proof of identity and uses every detail from the first turn. Use Trusted only on lines where callers are already verified. | |
| Allow unsigned widget user ids | Off | See Website widget. Leave this off in production. |
How a customer is recognized
Memory is per customer and per agent. Two agents never share memories, and the facts of one customer are never shown for another.
| Channel | Who the customer is | Notes |
|---|---|---|
| Phone (Twilio, Plivo, SIP) | The caller's number (the number called, for outbound calls) | Withheld, anonymous or restricted caller IDs get no memory. |
| The sender's number | ||
| Website widget | Your signed-in user's id, if you pass it (below). Otherwise an anonymous per-browser visitor id | A visitor id is lost when the visitor clears site data or switches browser. |
The same person on two channels, for example a phone call and a widget login, counts as two customers.
Website widget: identify signed-in users
Without any change, the widget remembers a visitor per browser. To recognize signed-in users on any device, pass your own user id and a signature your server computes. The signature stops anyone from impersonating another user by editing the id in their browser.
user_hash = hex(HMAC-SHA256(key = your widget identity secret, message = user_id))
The widget identity secret belongs to the project. To find it, open Connect → Channels, open your voice widget channel, and choose Reveal secret in the Signed-in visitors panel. It belongs on your server only. Never put it in page source, a mobile app bundle or a public repository.
If the secret is exposed, choose Rotate secret. Signatures made with the old secret stop working at once, so signed-in visitors are treated as anonymous until your server uses the new secret.
1. Compute user_hash on your server
- Node.js
- Python
import crypto from "node:crypto";
// VOISX_WIDGET_IDENTITY_SECRET comes from your server's secret store.
export function userHash(userId) {
return crypto
.createHmac("sha256", process.env.VOISX_WIDGET_IDENTITY_SECRET)
.update(String(userId), "utf8")
.digest("hex");
}
// e.g. in your page handler
app.get("/support", requireLogin, (req, res) => {
res.render("support", {
widgetUserId: req.user.id,
widgetUserHash: userHash(req.user.id),
});
});
import hashlib
import hmac
import os
def user_hash(user_id: str) -> str:
secret = os.environ["VOISX_WIDGET_IDENTITY_SECRET"].encode("utf-8")
return hmac.new(secret, str(user_id).encode("utf-8"), hashlib.sha256).hexdigest()
# e.g. Flask / FastAPI view
# return render_template("support.html",
# widget_user_id=user.id, widget_user_hash=user_hash(user.id))
Use a stable, opaque id such as your database user id, not an email address or phone number. It may be up to 128 characters, using letters, numbers and _ . : @ + - | = /, with no spaces. The id is never stored as is: the platform stores only a one-way hash of it, plus a masked label (for example user•••12) that is shown in the console.
2. Pass both values to the widget
Copy the widget embed code for your channel from the console, then add userId and userHash to the mount call:
<!-- The script tag from your widget embed code -->
<script src="..." data-public-key="vois_pk_..." async></script>
<script>
window.addEventListener("load", function () {
window.VoisChat.mount({
projectId: "<project id>",
agentId: "<agent id>",
channelId: "<channel id>",
publicKey: "vois_pk_...",
userId: "{{ widgetUserId }}",
userHash: "{{ widgetUserHash }}",
});
});
</script>
If you build your own client on the session WebSocket, send the same values as the user_id and user_hash query parameters. You can also send visitor_id, your own anonymous per-browser id (8 to 64 letters, numbers, _ or -), for visitors who are not signed in.
# India region. For the UAE region, use wss://uae.api.voisx.ai
wss://in.api.voisx.ai/widget/v1/realtime?key=vois_pk_...&agent_id=42&user_id=8812&user_hash=3b1f...e9
What happens with each input:
- A valid
user_hashmeans the visitor is remembered as your user. - A missing or wrong
user_hashmeans the user id is ignored, and the visitor is remembered per browser only. Allow unsigned widget user ids overrides this; use it only for testing. - No ids at all means no memory for that visitor.
What is stored and what is not
Stored, per customer and per agent:
- Short facts in plain language, such as "Prefers Arabic.", "Has an open refund for order 5521." or "Asked for a callback after 5 pm."
- A category (profile, preference, issue, commitment or other), an importance from 1 to 5, the conversation it came from, and timestamps.
- A one-way, keyed hash of the customer's identifier and a masked label for the console (
+97150•••123,WhatsApp +97150•••123,user•••12,Visitor 3f2a•••). The raw phone number or user id is not stored with memories.
Never stored:
- Payment card or bank details, government ID numbers, passwords, one-time codes or other credentials, and health information. The extraction step is told never to keep these. Every fact is also screened by a sensitive-data detector, and a flagged fact is discarded. If the detector itself is unavailable, the fact is discarded too.
- Anything about one customer in another customer's memory.
Where memories come from:
- After each conversation, the platform reads the transcript and keeps any durable facts. It merges a new fact with an existing one instead of piling up duplicates, and replaces facts that have become outdated. For WhatsApp and chat threads, which have no clear end, this runs once a thread has been idle for 30 minutes.
- During a conversation, the agent can save a fact when the customer asks it to ("remember that I'm vegetarian") and look up older memories.
- In the console, your team can add, edit and delete memories by hand.
Retention
Each memory expires Retention (days) after it was last written or updated. A daily clean-up permanently deletes expired memories, together with their search index entries. Lowering the retention re-dates the existing memories at once, so they are removed at the next daily clean-up. Deleting an agent deletes all its memories.
Memories follow the agent's own retention setting, not your organization's transcript and recording retention. A memory can therefore outlive the transcript it came from.
Forgetting
- The customer asks. If a customer says "forget that" or "forget everything about me", the agent removes those memories, or every memory it holds for them. It does this during the conversation and again after the conversation.
- From the console. On the agent's Memory → Customers tab, open the customer and choose Forget this customer, then type
FORGETto confirm. You can also delete single memories. To find someone, type their full phone number or user id; it is matched by hash.
Deletion is permanent: the rows and their search index entries are removed, not hidden. If removing a search index entry fails, the daily clean-up retries it.
See what the agent remembers
- Customers tab. The agent's Memory → Customers tab lists every customer the agent remembers, with masked ids, channel, number of memories and when they were last seen. Open a customer to see, add, edit or delete their memories. Each memory shows its category, importance (1 to 5), where it came from (Extracted, Saved by agent or Added by hand) and when it was last updated. A memory can be up to 500 characters.
- Playground. In the Playground Chat tab, enter a Customer id and choose the channel to act as, for example a phone number on Phone. The agent then treats you as that returning customer, and the Memory used this turn panel shows which memories it recalled for each message. See Playground.
Billing
Extracting, indexing and searching memories is metered usage on your organization's bill. There is no separate storage charge for memories. For prices, see voisx.ai/pricing.