GeniffyDocs
Changelog Log In Get a key

Memories

Add notes, pages, conversations and files; list, read, correct and forget memories. This page is generated from the API's own spec, so it says exactly what the API does.

Add a note, a web page or a conversation

POST/v1/memories
Parameter In Type Description
X-Geniffy-Space header string One of your own users, for every call this client makes. Leave it out for your own memory; a blank one is refused. (up to 128 characters)

Body (application/json)

Field Type Description
text string optional A note to remember (at least 1 character; up to 2,000,000 characters)
url string optional Or a web page, read once (at least 4 characters; up to 2,000 characters)
messages array of Message optional Or a conversation or an agent's session, as your framework already holds it: content as a string, blocks or parts, with its tool calls and results. Who said what is kept, so the user's words become facts about the user; a tool's output is never a fact about anyone, and is how Geniffy learns what happened. System and developer messages are skipped. (up to 500 items)
title string optional What to call it in the app (up to 300 characters)
said_at string optional When it was said or written, for a note or conversation from the past: an ISO 8601 date or time (2026-03-04, 2026-03-04T09:30:00Z). Left out, now. What it teaches is dated by it (up to 40 characters)
timezone string optional Where it was said: an IANA zone (America/Los_Angeles) or an offset (+05:30), so "tomorrow", "Friday" and "the end of the month" are read on the clock of whoever said them. Left out: the offset said_at or the messages' times carry, else the user's own zone (PUT /v1/timezone), else UTC (up to 64 characters)
external_id string optional Your own id for this source, such as a ticket's or a document's. Send again under the same id and the source is updated, not added twice: only what changed is learned, and what was removed is taken back. One id names one source in each space (up to 300 characters)
session string optional With messages, for an agent or a chat saving as it goes: your id for the session. Each call adds its messages to one memory for the whole session, so send only the turns that are new since the last call. However long the session gets, it stays one source (at least 1 character; up to 200 characters)
labels object optional Up to 20 of your own name/value pairs, such as {"channel": "email", "project": "apollo"}, to filter what you recall by. A name is letters, digits, dots, dashes or underscores. Sent again under the same external_id, they replace the old ones (nothing is learned again); left out, they are kept; {} clears them
space string optional One of your own users. Leave it out for your own memory; a blank one is refused. (up to 128 characters)

Returns 201

Field Type Description
source object required

Memories, newest first

GET/v1/memories
Parameter In Type Description
kind query all, people, plan, pref, detail
limit query integer (at least 1; at most 200; default 50)
cursor query integer (at least 0; default 0)
space query string One of your own users. Leave it out for your own memory; a blank one is refused. (up to 128 characters)
label query array of string A label to keep to, as name:value (label=channel:email). Repeat it for another name, which must match too, or for another value of the same name, which may match instead
X-Geniffy-Space header string One of your own users, for every call this client makes. Leave it out for your own memory; a blank one is refused. (up to 128 characters)

Returns 200

Field Type Description
memories array of Memory required
counts object required
total integer required
next integer optional

Add up to a hundred at once

POST/v1/memories/batch

One item failing does not take the rest down: each comes back with what happened to it, in the order sent. A batch that only ever succeeded or failed as a whole would make the caller re-send ninety-nine good items to retry one bad one.

Parameter In Type Description
X-Geniffy-Space header string One of your own users, for every call this client makes. Leave it out for your own memory; a blank one is refused. (up to 128 characters)

Body (application/json)

Field Type Description
items array of object required Up to 100 at a time, each what POST /v1/memories takes. Each may name its own space. An item that is not valid comes back with its error; the rest are added (at least 1 item; up to 100 items)
space string optional The space for any item that names none (up to 128 characters)

Returns 202

Field Type Description
results array of BatchRow required
added integer required
failed integer required

Add a file: PDF, Word, PowerPoint, Excel or text

POST/v1/memories/file
Parameter In Type Description
X-Geniffy-Space header string One of your own users, for every call this client makes. Leave it out for your own memory; a blank one is refused. (up to 128 characters)

Body (multipart/form-data)

Field Type Description
file string required
title string optional
space string optional
external_id string optional Your own id for this source, such as a ticket's or a document's. Send again under the same id and the source is updated, not added twice: only what changed is learned, and what was removed is taken back. One id names one source in each space (up to 300 characters)
labels string optional The labels as JSON, such as {"channel": "email"} (up to 10,000 characters)

Returns 201

Field Type Description
source object required

One memory, the sentence it came from, and its history

GET/v1/memories/{memory_id}
Parameter In Type Description
memory_id path integer
space query string One of your own users. Leave it out for your own memory; a blank one is refused. (up to 128 characters)
X-Geniffy-Space header string One of your own users, for every call this client makes. Leave it out for your own memory; a blank one is refused. (up to 128 characters)

Say what we got wrong, and what is right

PATCH/v1/memories/{memory_id}

The wrong memory is marked and never used again, and what is right is learned as a new one, with its own source. Nothing is quietly overwritten: a correction leaves a trail.

Parameter In Type Description
memory_id path integer
X-Geniffy-Space header string One of your own users, for every call this client makes. Leave it out for your own memory; a blank one is refused. (up to 128 characters)

Body (application/json)

Field Type Description
text string required What is right instead (at least 1 character; up to 2,000 characters)
space string optional One of your own users. Leave it out for your own memory; a blank one is refused. (up to 128 characters)

Forget a memory for good

DELETE/v1/memories/{memory_id}
Parameter In Type Description
memory_id path integer
space query string One of your own users. Leave it out for your own memory; a blank one is refused. (up to 128 characters)
X-Geniffy-Space header string One of your own users, for every call this client makes. Leave it out for your own memory; a blank one is refused. (up to 128 characters)
Last updated November 3, 2026