Production checklist
Go through this before real users reach your app. Each item links to the page that explains it.
Keys
- Make a key for production, name it after where it runs, and keep it in your server's environment. Never put it in a web page or a mobile app: whoever holds it can read every memory it reaches. See Keys.
- Use a different key for staging and for your own laptop, and keep their data in spaces of their own,
such as
test_user_1. Keys tell callers apart, not data. - Know how you will rotate it: make a new key, put it where the old one was, then revoke the old one. A revoked key stops working within seconds.
- When a user's own app or device must call Geniffy itself, give it a key limited to that user, with an expiry, never your server's key. It reaches their memory and nothing else, and erasing the user stops it. See A key for one user.
Spaces
- Bind a client to a space for every request that belongs to one of your users, at the edge of your request handling, and use only the bound client below it. A call that names no space writes to your own memory. See The one mistake to avoid.
- Name spaces after your own stable user ids, such as
user_8841: up to 128 letters, digits, dots, dashes or underscores. - A phone number finds the customer who is probably calling or texting, not the person who is: a number can be faked, and a withheld one is no number at all. Before your agent shares anything private from a memory found by number, confirm who it is speaking with (a PIN, a one-time code sent to the number you hold for them, or your own sign-in). Until then, save what the caller says in a space of its own: in your customer's memory, a later word on a date or a promise replaces the earlier one.
- Wherever your app deletes a user, or a user asks to be forgotten, call
forget_spacefor their space. It takes everything held for them, and only that, and it cannot be undone.
Adding
- Save a conversation as your framework already holds it; there is nothing to convert. See Conversations.
- If you sync records of your own (tickets, documents, a conversation that grows), add each under its own
external_id, so sending it again updates it rather than adding a copy. See Your own ids. - When you import history, pass
said_at, so what it teaches is dated by when it was said, not by the day you imported it. See Conversations from the past. - If what you add comes from places your users connect and disconnect (a mailbox, a drive, a CRM), add it
under a label such as
{"channel": "gmail"}. Then recall can keep to one place, and disconnecting deletes everything from it in one call. See Labels. - Catch
UnreadableErrorwhere people upload files or paste links.error.source.errorsays why in plain words, so you can show it to them. - You do not have to wait for learning before you answer. When you do need to,
sources.wait(id)returns the moment learning ends.
Recall
- Open every turn with
briefing(cue=...): it is read, not generated, so it costs a turn a fraction of a second. It comes back empty when nothing is known yet, so give your prompt a line for that. - Voice agents should never wait on
ask()orcontext()before they speak. Give the briefing a deadline of a second or two, and let the call go on without it when it is late. - Put the block
context()returns into your prompt as it is. It is never empty: when nothing is known it tells your model to say so, so do not add a fallback of your own. - Use
search()only where you want ranked memories with no judgement on them. See Recall.
Errors and retries
- Let the SDK retry. It retries reads on network errors, 408, 429 and 5xx, and adds only when the request never reached Geniffy or on 429, so a retry never saves a note twice.
- Catch
AuthenticationError: a wrong or revoked key. See Errors and limits. - Log the request id of every failed call next to your own log line. See Request ids.
Watching it
- Requests in the Geniffy app shows every call your keys make for 30 days: which key, which space, what was asked, what came back, how long it took, and which SDK sent it.
- Spaces in the Geniffy app warns you when memories arrive through the API with no space named.
Last updated October 16, 2026