GeniffyDocs
Changelog Log In Get a key

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_space for 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 UnreadableError where people upload files or paste links. error.source.error says 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() or context() 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