Skip to main content

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.

A plan caps how much your account stores

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​

FieldTypeDescription
idstring
memory_store_idstring
actor_idstring, nullableThe 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.
contentstringThe 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_typemanual | conversationWhether 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_idstring, nullableThe 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.
tagsobjectPer-memory key-value tags, matched at memory granularity by knowledge search.
metadataobjectArbitrary structured metadata attached to the memory
invalidated_atstring (date-time), nullableWhen 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_idstring, nullableThe memory that replaced this one, when it was superseded. Null for a valid memory and for a retracted one, which nothing replaced.
versionintegerThe 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_atstring (date-time)
updated_atstring (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:

Readactor_id
GET /v1/projects/{project_id}/memoriesquery; that actor's memories
every /memories/{memory_id} routequery; another actor's memory, or one of none, is 404
POST /v1/projects/{project_id}/knowledge/searchbody; that actor's memories, documents not narrowed
GET /v1/projects/{project_id}/memory-stores/{memory_store_id}/exportquery; that actor's memories
GET /v1/projects/{project_id}/memory-stores/{memory_store_id}/assertionsquery; 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:

SimilarityactionStatusWhat happens
≥ duplicate_thresholdskipped200The fact is already known; the existing memory is returned unchanged.
≥ supersede_thresholdsuperseded200The same fact, changed. The match is invalidated and the replacement is returned.
below bothcreated201A 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:

LevelSet onScope
Per requestduplicate_threshold / supersede_threshold on the create bodythat one call
Store defaultthe same two fields on the memory storethe corpus's dedup policy
Algorithmnull at both levelsthe 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.

FieldTypeDescription
idstring
memory_store_idstring
memory_idstring, nullableThe 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_idstring, nullableThe 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.
contentstringThe 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.
mechanismtool | rule | api | formationWhich 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_idstring, nullableThe 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_idstring, nullableThe 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_typestringWho 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_idstring
outcomecreated | superseded | skipped | retractedWhat 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.
similaritynumber, nullableThe 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.
declaredbooleanWhether 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_atstring (date-time)

Read it by memory, by store, or by the generation that wrote it:

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​

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"}'

Read what a store holds​

naturali list-memories \
--project-id proj_V1StGXR8Z5jdHi6B \
--memory-store-id mstore_V1StGXR8Z5jdHi6B \
--limit 20

Trace why the agent believes something​

naturali list-memories \
--project-id proj_V1StGXR8Z5jdHi6B \
--memory-store-id mstore_V1StGXR8Z5jdHi6B \
--include-invalidated true

Correct a fact​

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."