Python SDK
Give your app a memory from Python 3.9 or later. Write what each of your users tells you, and put what is known about them in front of your model, with where every line came from.
pip install geniffyMake a key in the Geniffy app under API keys and set it as GENIFFY_API_KEY.
from geniffy import Geniffy
client = Geniffy() # reads GENIFFY_API_KEY
mem = client.space("customer_1042") # one of your users; nothing else can read it
source = mem.memories.add("Priya Nair signs the Lumen renewal, and it comes up in March.")
mem.sources.wait(source.id) # learning usually takes a few seconds
prompt = f"{mem.context('Who signs the Lumen renewal?')}\n\nUser: Who signs the Lumen renewal?"Recall: fast reads every turn, a checked answer when it matters
mem.briefing(cue=user_message) # for your system prompt; read, not generated: fit for every turn
mem.search("renewal", limit=5) # the memories, ranked, fast
mem.search_full("port 6543") # the same, with the lessons, stories and open promises
mem.ask("Who signs the renewal?") # an answer in words, or answer=None and a message saying why
mem.context("Who signs the renewal?") # the memories an answer stands on, as a block for your promptbriefing() and search() make no model call, so they come back in a fraction of a second, voice calls included.
ask() and context() have a model judge whether anything bears on the question, which takes a couple of seconds
and never invents. context_full() returns the block with the memories behind it and an empty flag. See
Recall.
Voice agents: Pipecat
pip install "geniffy[pipecat]" and put GeniffyMemory between the user aggregator and the LLM. Before each reply
it gives the model the caller's briefing, and it saves the call as it goes. It needs Python 3.11 or later and
Pipecat 1.9 or later. See Pipecat.
from geniffy import AsyncGeniffy
from geniffy.pipecat import GeniffyMemory
geniffy = AsyncGeniffy() # once for the process
memory = GeniffyMemory(geniffy.space(f"user_{caller_id}")) # one per call, in front of the LLMAgents: open with the briefing, save every turn
system = mem.briefing(project="checkout", cue=task) # where things stand, what is due, the rules that apply,
# what happened, then the memories, each dated
run = mem.session(run_id, title="Refund agent", labels={"project": "checkout"})
run.save(messages) # after every turn: only what is new is sentbriefing_full() has the briefing's parts, and each can be read on its own: now(), episodes(), lessons()
and intentions(); set_intention(id, "done") marks a promise kept, and memory_health() says how well the
memory answers about its own work. save() sends only the messages after the last one it sent, 500 a call, into
one memory for the whole session. See The briefing and
Conversations.
Spaces: one memory per user
mem = client.space(f"user_{user.id}") # per request
client.memories.add("...") # no space: your own memory, the one the Geniffy app shows
client.spaces() # which spaces hold anything, most recently written first
client.forget_space("user_8841") # everything held for that user, gone, when they askA space exists from the first time you write to it; there is nothing to create. A blank space, or None,
raises instead of reaching your own memory, and an int id is taken as its digits. See
Keys and spaces.
Add
mem.memories.add("A note to remember", title="Call with Priya")
mem.memories.add(url="https://example.com") # a web page, read once
mem.memories.add(messages=chat_history) # a conversation, as your framework holds it
mem.memories.add(messages=chat_history, said_at=date(2025, 3, 4)) # one from the past, dated when it was said
mem.memories.add(ticket.body, external_id=f"ticket-{ticket.id}") # your own id: sent again, it is updated
mem.memories.add(email.body, labels={"channel": "email"}) # your own labels, to filter recall by
mem.memories.add_file("Pricing.pdf") # PDF, .docx, .pptx, .xlsx or text: a path, bytes or a file opened "rb"
mem.memories.add_many([{"text": "..."}, {"url": "https://..."}])A file or page that cannot be read raises UnreadableError; error.source is the source it left, with
the reason. See Add memories.
Read and correct
page = mem.memories.list(kind="people") # all, people, plan, pref or detail; newest first
mem.memories.list(labels={"channel": "email"}) # only what sources with these labels said
for m in mem.memories.iter(): # every memory, a page at a time
...
detail = mem.memories.get(42) # .memory.quote is the sentence it came from; .history its older values
mem.memories.correct(42, "Priya signs it, with Arjun co-signing.")
mem.memories.delete(42) # forget it for good
mem.profile("Priya Nair") # what is lastingly true about someone, and what is going on now
mem.export() # everything held, as the user's own copy
mem.brief("Priya Nair") # what to read before talking to them
mem.sources.list()
mem.sources.delete(source.id) # a source, and what only it taught
mem.sources.get(external_id="ticket-42") # by your own id
mem.sources.delete(external_id="ticket-42")
mem.sources.delete_labelled({"channel": "gmail"}) # every source with these labels, and what only they taught
mem.sources.delete_labelled({"channel": "gmail"}, keep=seen) # all but these external_ids: the end of a full syncsearch, context, ask and brief take labels= too. See Labels.
Files kept exactly, and Claude's memory tool
mem.files.put("/notes/lumen.md", "Priya Nair signs the Lumen renewal.\n") # creates or replaces it
mem.files.get("/notes/lumen.md").text # exactly what was put
mem.files.list("/notes/") # paths, sizes and times, by path
mem.files.move("/notes", "/archive/notes") # a file, or every file beneath a directory
mem.files.delete("/archive/notes/lumen.md") # a file, and what only it taught
mem.files.delete_prefix("/archive/") # every file under a prefixA file comes back exactly as it was put, and what it says is learned like a note titled by its path. See
Files kept exactly. geniffy.claude keeps Claude's memory tool in them:
pip install "geniffy[claude]" (Python 3.10 or later, as anthropic is), then pass
GeniffyMemoryTool(client.space(user_id)) in tools= to Anthropic's tool runner. See
Claude's memory tool.
Keys for one user, and profile sections
key = mem.keys.create(name="Ana's phone", expires_at=date(2026, 12, 31)) # reaches this user only
mem.keys.list(); mem.keys.revoke(key.id)
client.sections.create("billing", keywords=["invoice", "refund"]) # a profile section for every user
mem.sections.create("allergies", topics=["diet"]) # or for this user onlySee Keys and spaces and People.
Async
from geniffy import AsyncGeniffy
async with AsyncGeniffy() as client:
mem = client.space("customer_1042")
await mem.memories.add("Priya wants a demo on Tuesday.")
print(await mem.context("When is Priya's demo?"))Every call above has an awaited twin on AsyncGeniffy.
This month's use
client.usage() # tokens learned and waiting, written answers, what the plan includes, extra learning, when it resetsSaving, briefings and search are never counted; a plan counts what is learned and the answers ask() and
context() write. Past your plan nothing stops: what you add is
kept, found by search at once and learned next month, or at once with extra learning switched on (Settings, Plan and
usage). Only when what waits reaches ten months of the plan does adding raise UsageLimitError. See
GET /v1/usage and Plans and usage.
Errors, retries and request ids
Every error carries the API's own sentence: AuthenticationError (a wrong or revoked key),
NotFoundError, BadRequestError, UnreadableError, RateLimitError, UsageLimitError (this month's use is
up; never retried), InternalServerError and APIConnectionError, all subclasses of GeniffyError. Reads, and putting a file (the same text twice is the
same file), are retried twice on network errors, 408, 429 and 5xx. Adding is retried only when the request
never reached Geniffy, or on 429, so a retry never saves a note twice. Set max_retries= and timeout= on
the client to change that.
Every error carries the call's id as error.request_id. See Request ids.
A key reaches its owner's memory and every space beneath it. Keep it on your server.
Source and examples
The SDK is open source under the MIT license: Geniffy/geniffy-python. Runnable programs built on it, from a quickstart to a chat with Claude that remembers you, are in Geniffy/examples.