GeniffyDocs
Changelog Log In Get a key

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.

Terminal
pip install geniffy

Make 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 prompt

briefing() 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 LLM

Agents: 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 sent

briefing_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 ask

A 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 sync

search, 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 prefix

A 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 only

See 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 resets

Saving, 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.

Last updated October 16, 2026