TypeScript SDK
Give your app a memory from TypeScript or JavaScript. It has no dependencies: it uses the platform's
fetch, on Node 18 or later, Deno, Bun and edge runtimes.
npm install geniffyMake a key in the Geniffy app under API keys and set it as GENIFFY_API_KEY.
import { Geniffy } from "geniffy";
const client = new Geniffy(); // reads GENIFFY_API_KEY
const mem = client.space("customer_1042"); // one of your users; nothing else can read it
const source = await mem.memories.add("Priya Nair signs the Lumen renewal, and it comes up in March.");
await mem.sources.wait(source.id); // learning usually takes a few seconds
const context = await mem.context("Who signs the Lumen renewal?");
const prompt = `${context}\n\nUser: Who signs the Lumen renewal?`;context() never returns an empty string. Ask about something that was never stored and it returns one
sentence, There is nothing stored about this yet. Say so rather than guessing.: a model reads silence
as permission to invent.
Recall: fast reads every turn, a checked answer when it matters
await mem.briefing({ cue: userMessage }); // for your system prompt; read, not generated
await mem.search("renewal", { limit: 5 }); // the memories, ranked, fast
await mem.searchFull("port 6543"); // the same, with the lessons, stories and open promises
await mem.ask("Who signs the renewal?"); // { answer, memories }, or answer: null and a message
await mem.context("Who signs the renewal?"); // the memories an answer stands on, as a prompt blockbriefing() and search() make no model call, so they come back in a fraction of a second. ask() and
context() have a model judge whether anything bears on the question, which takes a couple of seconds and never
invents. See Recall.
Agents: open with the briefing, save every turn
const system = await mem.briefing({ project: "checkout", cue: task }); // where things stand, what is due, the
// rules that apply, what happened, then
// the memories, each dated
const run = mem.session(runId, { title: "Refund agent", labels: { project: "checkout" } });
await run.save(messages); // after every turn: only what is new is sentbriefingFull() has the briefing's parts, and each can be read on its own: now(), episodes(), lessons() and
intentions(); setIntention(id, "done") marks a promise kept, and memoryHealth() 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
const mem = client.space(`user_${user.id}`); // per request
await client.memories.add("..."); // no space: your own memory, the one the Geniffy app shows
await client.spaces(); // which spaces hold anything, most recently written first
await client.forgetSpace("user_8841"); // everything held for that user, gone, when they askA blank space, undefined or null throws a TypeError instead of reaching your own memory, and an integer
id is taken as its digits.
Add
await mem.memories.add({ text: "Pilots run for 6 weeks.", title: "GTM plan" });
await mem.memories.add({ url: "https://example.com" }); // a web page, read once
await mem.memories.add({ messages: chatHistory }); // a conversation, as your framework holds it
await mem.memories.add({ messages: chatHistory, saidAt: "2025-03-04" }); // one from the past, dated when it was said
await mem.memories.add({ text: ticket.body, externalId: `ticket-${ticket.id}` }); // your own id: sent again, it is updated
await mem.memories.add({ text: email.body, labels: { channel: "email" } }); // your own labels, to filter recall by
await mem.memories.addFile(fileOrBlob, { filename: "Pricing.pdf" }); // PDF, .docx, .pptx, .xlsx or text
await mem.memories.addMany([{ text: "..." }, { url: "https://..." }]);Messages from OpenAI, Anthropic, Gemini and the Vercel AI SDK type-check as they are. A file or page
that cannot be read rejects with UnreadableError; error.source is the source it left, with the
reason.
Read and correct
const page = await mem.memories.list({ kind: "people" }); // all, people, plan, pref or detail; newest first
await mem.memories.list({ labels: { channel: "email" } }); // only what sources with these labels said
for await (const m of mem.memories.iterate()) { /* every memory */ }
const { memory, history } = await mem.memories.get(42); // memory.quote is the sentence it came from
await mem.memories.correct(42, "Priya signs it, with Arjun co-signing.");
await mem.memories.delete(42); // forget it for good
await mem.profile("Priya Nair"); // what is lastingly true about someone, and what is going on now
await mem.export(); // everything held, as the user's own copy
await mem.brief("Priya Nair"); // what to read before talking to them
await mem.sources.list();
await mem.sources.delete(source.id); // a source, and what only it taught
await mem.sources.get({ externalId: "ticket-42" }); // by your own id
await mem.sources.delete({ externalId: "ticket-42" });
await mem.sources.deleteLabelled({ channel: "gmail" }); // every source with these labels, and what only they taught
await mem.sources.deleteLabelled({ 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
await mem.files.put("/notes/lumen.md", "Priya Nair signs the Lumen renewal.\n"); // creates or replaces it
const { text } = await mem.files.get("/notes/lumen.md"); // exactly what was put
await mem.files.list({ prefix: "/notes/" }); // by path, without the text
await mem.files.move("/notes", "/archive/notes"); // a file, or every file beneath a directory
await mem.files.delete("/archive/notes/lumen.md"); // a file, and what only it taught
await mem.files.deletePrefix("/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:
betaMemoryTool(geniffyMemoryHandlers(client.space(userId))), with betaMemoryTool from
@anthropic-ai/sdk/helpers/beta/memory, in the tools of Anthropic's tool runner. It needs @anthropic-ai/sdk
0.72 or later, an optional peer dependency; geniffy itself still has none. See
Claude's memory tool.
Keys for one user, and profile sections
const key = await mem.keys.create({ name: "Ana's phone", expiresAt: "2026-12-31" }); // reaches this user only
await mem.keys.list(); await mem.keys.revoke(key.id);
await client.sections.create({ name: "billing", keywords: ["invoice", "refund"] }); // a profile section for every user
await mem.sections.create({ name: "allergies", topics: ["diet"] }); // or for this user onlySee Keys and spaces and People.
This month's use
await 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 throw 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 extend 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 on 429, so a retry
never saves a note twice. Pass { maxRetries, timeout } to the constructor to change that.
Every error carries the call's id as error.requestId. 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-typescript. Runnable programs built on it, from a quickstart to a chat with Claude that remembers you, are in Geniffy/examples.