Memories
The individual facts inside a memory store — embedded, deduplicated, and superseded rather than deleted.
Overview
A memory is one fact: a sentence of content, a source_type saying whether
there is a source to point at, and tags. Writing one embeds it, so
knowledge search can rank it against a query alongside the
project's documents.
Memories are not a log. A near-duplicate write is skipped rather than appended, and a memory that gets contradicted is invalidated and pointed at its replacement instead of being removed — so what an agent recalls stays coherent while the history of how it got there stays readable.
This module is a verbatim mirror of the runtime: every field, method, status code and error shape is the runtime's own, re-rooted under the project in the path.
Free stores 1 GB, Pro 30 GB, Business 100 GB; an Enterprise ceiling is set by
contract. Creating a memory past that answers 403 PLAN_LIMIT_REACHED with
resource: "storage", and the plan, the limit and what your account is
holding as used in meta.
This holds however the write arrives: a call to this API, a
formation deploy or an agent's tool call.
The ceiling is your account's, not each project's: every project the
account pays for draws on the same figure, so one project may hold all of it.
Read where you stand from storage on
GET /v1/users/me/billing; the
usage route below reports one project at a time.
A memory counts for its text plus its embedding vector, which is about 4 kB
whatever the text — so many small memories cost far more than their words
suggest. The same ceiling covers files, documents and collection items; read
your current figure from the gb_day component of
GET /v1/projects/{project_id}/usage
under meter_type=storage.
Reading, updating metadata and deleting stay open at the ceiling; a create and
a PUT carrying content, which re-embeds and keeps the old version, are
refused.
See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Memories.
Data Model
Memory
| Field | Type | Description |
|---|---|---|
id | string | |
memory_store_id | string | |
actor_id | string, nullable | The end user the memory belongs to; null for none. Set on create and never changed; a replacement written by a supersede belongs to the same actor. |
content | string | The text this memory currently holds. Stored once per distinct text per store and shared with every assertion that stated it, so a memory carries no copy of its own. |
source_type | manual | conversation | Whether there is a source to point at. conversation means source_id names the conversation this fact was learned in; manual means there is nothing to point at — a direct API write, or an agent write made outside a conversation. |
source_id | string, nullable | The conversation this fact was learned in, when source_type is conversation; null when it is manual. Deliberately a loose pointer rather than a foreign key, so deleting the conversation leaves the id in place — the record of where the fact came from outlives its source. |
tags | object | Per-memory key-value tags, matched at memory granularity by knowledge search. |
metadata | object | Arbitrary structured metadata attached to the memory |
invalidated_at | string (date-time), nullable | When the memory stopped holding, whether a supersede replaced it or a retraction withdrew it. Null means the memory is currently valid. Invalidated memories are excluded from listing, from write deduplication, and from knowledge search, but remain readable by ID — with their original text — for audit. |
superseded_by_memory_id | string, nullable | The memory that replaced this one, when it was superseded. Null for a valid memory and for a retracted one, which nothing replaced. |
version | integer | The memory's write version, starting at 1 and incremented on every update. States a precondition against it with expected_version or If-Match on PUT /memories/{memory_id}. |
created_at | string (date-time) | |
updated_at | string (date-time) |
memory_store_id and content are required on create.
A write response adds action — see What a write returns.
Key Concepts
Listing is always per store
GET /v1/projects/{project_id}/memories
requires memory_store_id; there is no cross-store listing. That follows from
what a store is — a scope — and it means a caller cannot accidentally read one
customer's facts while paging through another's.
Give an agent long-term memory
lists its store this way.
Invalidated memories are left out by default. Pass include_invalidated=true to
see the full history, which is what you want when answering "why does the agent
think that?".
Memories of an end user
A store belongs to no one; each memory in it may belong to one
actor. A memory created with actor_id on
POST /v1/projects/{project_id}/memories
belongs to that actor, which must be in the project (400 ACTOR_NOT_FOUND
otherwise); it is set on create only, and a supersede's replacement keeps it.
Deleting the actor leaves its memories with actor_id: null.
A write compares, supersedes and creates among its own actor's memories only, or
among the memories of no actor when it names none: one fact known for two
actors is two memories, and supersedes naming another actor's memory is
400.
A read narrows to one actor when it names actor_id; without it, every actor's
memories are read:
| Read | actor_id |
|---|---|
GET /v1/projects/{project_id}/memories | query; that actor's memories |
every /memories/{memory_id} route | query; another actor's memory, or one of none, is 404 |
POST /v1/projects/{project_id}/knowledge/search | body; that actor's memories, documents not narrowed |
GET /v1/projects/{project_id}/memory-stores/{memory_store_id}/export | query; that actor's memories |
GET /v1/projects/{project_id}/memory-stores/{memory_store_id}/assertions | query; the writes that resolved into that actor's memories |
An agent's own memory follows the session's actor: retrieval
reads that actor's memories only, write_memory writes them, and a memory rule
writes a conversation turn's facts as memories of the conversation's actor. A
turn with no actor reads every memory and writes memories of no actor.
Where a fact came from
source_type says whether there is a source to point at. conversation means
source_id names the conversation the fact was learned in,
and is required with it; manual means there is nothing to point at — a direct
API write, or an agent write made outside a conversation — and rejects
source_id.
source_id is a loose pointer rather than a foreign key: deleting the
conversation leaves the id in place, so the record of where a fact came from
outlives its source.
What a write returns
Every write is resolved against what the store already holds, by cosine similarity to the closest valid memory:
| Similarity | action | Status | What happens |
|---|---|---|---|
≥ duplicate_threshold | skipped | 200 | The fact is already known; the existing memory is returned unchanged. |
≥ supersede_threshold | superseded | 200 | The same fact, changed. The match is invalidated and the replacement is returned. |
| below both | created | 201 | A new memory. |
Below supersede_threshold, cosine cannot tell "same fact, changed" from
"related but distinct" (prefers email vs prefers Portuguese), and embeddings
sit close on negations — so created is the outcome there. A near-duplicate
stays searchable; a wrongly retired fact does not.
On a supersede the retired memory's tags and metadata are shallow-merged
onto the replacement (incoming keys win), so a replacement stays inside every
tag-scoped search and policy the original satisfied.
Where the thresholds come from
Both cutoffs resolve per request, most specific first:
| Level | Set on | Scope |
|---|---|---|
| Per request | duplicate_threshold / supersede_threshold on the create body | that one call |
| Store default | the same two fields on the memory store | the corpus's dedup policy |
| Algorithm | null at both levels | the built-in constants |
The effective pair must satisfy supersede_threshold < duplicate_threshold.
Equal makes superseded unreachable; inverted swallows skipped. Both are
refused with 400, and the check runs against the effective pair — so a body
overriding only one value cannot invert it against the store's other one.
Writing by hand versus by agent
Every door consolidates, and they differ only in what supplies the fact. This
endpoint takes one you wrote. When an
agent has
knowledge_config.write_memory_store_id set, the write_memory tool becomes
available to it, and the agent spends it mid-turn at its own discretion
(Limit what an agent may do
sets it up). A memory rule on the store is the third: it
reads completed turns and writes what its handler proposes, as in
Give an agent long-term memory.
Which door a write came through is recorded on the assertion, not inferred from the result.
Project- and agent-scope guardrails gate every
write_memory call like any other tool call. A held call files an
approval whose proposed_action.tool_id is
native:write_memory; approving it writes the fact as the agent, to the store
write_memory_store_id names at decision time, held to the agent's
policy_ids then. Edited arguments need a non-empty string content, and
editing needs memories:CreateMemory and
memories:UpdateMemory on that store and tools:CallTool on
native:write_memory. A write_memory call records no tool execution, so a guard reading
runtime.*.tool_calls does not count it.
Every write is recorded
Every write attempt is appended to a ledger, whatever its outcome — a skip that left no trace would make "why is this fact not in the store?" unanswerable.
| Field | Type | Description |
|---|---|---|
id | string | |
memory_store_id | string | |
memory_id | string, nullable | The memory this assertion resolved into: the new memory for created and superseded, the existing memory that matched for skipped, the memory withdrawn for retracted. Null only once that memory has been deleted. |
superseded_memory_id | string, nullable | The memory this assertion retired, on a superseded outcome; null otherwise, a retraction included — it retires its own memory, which memory_id already names. Read back from memories.superseded_by_memory_id rather than stored here, because validity lives on the memory — where every read filters it — and exactly one memory is superseded per assertion. |
content | string | The text as asserted, which is not necessarily the memory's text: a skipped assertion records what was claimed, while the memory keeps what it already held. |
mechanism | tool | rule | api | formation | Which door the write came through. tool is the agent's write_memory call mid-turn; rule is a post-turn pass over the finished turn; api is POST /v1/projects/{project_id}/memories; formation is a memory resource in an applied template. It answers how, never who — the principal fields answer that. Open set — new mechanisms may be added in minor releases; clients must tolerate unknown values. |
rule_id | string, nullable | The memory rule whose firing wrote this, set only when mechanism is rule — the built-in extractor included, since that is a rule with no handler. Null once the rule has been deleted, and on assertions written before memory rules shipped. |
generation_id | string, nullable | The turn that asserted the fact — the origin of anything an agent wrote, and the edge a conversation is reachable from. Null on the api and formation doors, which have no generation behind them. |
principal_type | string | Who claimed the fact: user or api_key on the api and formation doors, agent on both agent doors — the extractor runs under the agent's identity. |
principal_id | string | |
outcome | created | superseded | skipped | retracted | What the write resolved to. created is a distinct fact, superseded is the same fact changed (the top match was invalidated and replaced), skipped is a fact already known, retracted is a fact that stopped holding with nothing replacing it. Open set — new outcomes may be added in minor releases; clients must tolerate unknown values. |
similarity | number, nullable | The cosine similarity the outcome was decided against — the top match's, or the declared target's when declared is true, where it decides nothing and only records how far apart the two statements were. Null when there was nothing to compare against, when the content could not be embedded, and on a retracted outcome, which compares nothing. |
declared | boolean | Whether the write named the memory it replaced (supersedes on create) instead of the thresholds choosing one. Always false on a created, skipped or retracted outcome. |
created_at | string (date-time) |
Read it by memory, by store, or by the generation that wrote it:
GET /v1/projects/{project_id}/memories/{memory_id}/assertionsGET /v1/projects/{project_id}/memory-stores/{memory_store_id}/assertionsGET /v1/projects/{project_id}/generations/{generation_id}/memory-assertions
Validity lives on the memory (invalidated_at, superseded_by_memory_id), not
on the assertion: it is the filter on every read, and an invalidation with no
replacement has no assertion to carry it.
Superseded, not deleted
An invalidated memory is excluded from listing, from deduplication and from
search — it stops affecting answers immediately — but the row stays, stamped with
invalidated_at and superseded_by_memory_id. Following that pointer forward,
or listing with include_invalidated=true, reconstructs the chain of what the
agent believed and when it changed.
Deleting a memory, by contrast, removes it.
GET /v1/projects/{project_id}/memory-stores/{memory_store_id}/export
streams one store's memories as newline-delimited JSON, oldest first, leaving out
invalidated ones unless include_invalidated asks for them.
Who may do what
Every route needs any project member.
Examples
Seed a store with a fact
- CLI
- SDK
- curl
naturali create-memory \
--project-id proj_V1StGXR8Z5jdHi6B \
--memory-store-id mstore_V1StGXR8Z5jdHi6B \
--content "Acme is on the enterprise plan and has a 4-hour response SLA." \
--source-type manual \
--tags '{"account":"acme"}'
const { data: memory } = await naturali.memories.createMemory({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: {
memory_store_id: 'mstore_V1StGXR8Z5jdHi6B',
content: 'Acme is on the enterprise plan and has a 4-hour response SLA.',
source_type: 'manual',
tags: { account: 'acme' },
},
});
console.log(memory?.action); // "created" or "skipped"
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/memories \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"memory_store_id": "mstore_V1StGXR8Z5jdHi6B",
"content": "Acme is on the enterprise plan and has a 4-hour response SLA.",
"source_type": "manual",
"tags": { "account": "acme" }
}'
Read what a store holds
- CLI
- SDK
- curl
naturali list-memories \
--project-id proj_V1StGXR8Z5jdHi6B \
--memory-store-id mstore_V1StGXR8Z5jdHi6B \
--limit 20
const { data: memories } = await naturali.memories.listMemories({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
query: { memory_store_id: 'mstore_V1StGXR8Z5jdHi6B', limit: 20 },
});
curl "https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/memories?memory_store_id=mstore_V1StGXR8Z5jdHi6B&limit=20" \
-H "Authorization: Bearer $NATURALI_TOKEN"
Trace why the agent believes something
- CLI
- SDK
- curl
naturali list-memories \
--project-id proj_V1StGXR8Z5jdHi6B \
--memory-store-id mstore_V1StGXR8Z5jdHi6B \
--include-invalidated true
const { data: history } = await naturali.memories.listMemories({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
query: {
memory_store_id: 'mstore_V1StGXR8Z5jdHi6B',
include_invalidated: true,
},
});
for (const memory of history?.data ?? []) {
if (memory.invalidated_at) {
console.log(memory.content, '→ replaced by', memory.superseded_by_memory_id);
}
}
curl "https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/memories?memory_store_id=mstore_V1StGXR8Z5jdHi6B&include_invalidated=true" \
-H "Authorization: Bearer $NATURALI_TOKEN"
Correct a fact
- CLI
- SDK
- curl
naturali update-memory \
--project-id proj_V1StGXR8Z5jdHi6B \
--memory-id mem_V1StGXR8Z5jdHi6B \
--content "Acme is on the enterprise plan and has a 2-hour response SLA."
const { data: memory } = await naturali.memories.updateMemory({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
memory_id: 'mem_V1StGXR8Z5jdHi6B',
},
body: {
content: 'Acme is on the enterprise plan and has a 2-hour response SLA.',
},
});
curl -X PUT https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/memories/mem_V1StGXR8Z5jdHi6B \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "content": "Acme is on the enterprise plan and has a 2-hour response SLA." }'