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