Memory tools

When memory is enabled for an identified conversation, Omnia exposes five memory tools: the four PromptKit platform tools, and memory__open, which Omnia adds beside memory__recall:

Tool	Purpose
memory__remember	Create or update durable memory
memory__recall	Search relevant memory
memory__open	Read the full body of a memory that recall returned as a preview
memory__list	Browse memories in the current scope
memory__forget	Soft-delete a memory

The tools are registered only for a verified user: the facade must have proved who the caller is. An anonymous or API-key conversation does not receive memory tools, even when the agent’s memory configuration is enabled, and the runtime logs that at info level.

memory__remember

Use this for a stable fact, preference, or user-requested memory. PromptKit defines content, type, confidence, category, and metadata; Omnia extends the schema with about_kind, about_key, purpose, title, and summary:

Field	Purpose
content	The durable observation (required)
type	Memory kind; defaults to general. The tool offers the memory service’s schema types as an enum — the bound MemoryPolicy’s schema, or the built-in set
confidence	Confidence from 0 to 1; defaults to 0.8
category	Consent category (for example memory:health) used by retention and consent policy
about_kind	Stable subject category used for deduplication
about_key	Stable identifier within that category
purpose	Why the memory is retained
title	Short title for long content
summary	One-line summary of long content
share	true to also propose the memory as knowledge for every user of the agent

Reusing about_kind and about_key supersedes the existing observation in place. Use that mechanism to correct a fact. Use memory__forget only when the fact should be removed entirely.

Sharing a memory with the agent

With share: true, the save asks memory-api for the agent tier. The memory is stored for the user at once, exactly as without share. On Enterprise with the brain store (MEMORY_STORE=brain), it is also queued for the shared-write gate. The gate publishes a de-identified copy to the agent’s shared tier only once enough distinct users have shared the same fact (MemoryPolicy spec.gate.minDistinctSubjects, at least 2). Until then it holds the copy, and rejects it if no one corroborates it within the window. A workspace can switch users’ shares off (spec.gate.accept.userShares: false); share is then accepted and the memory stays private. A fact that matches an existing shared memory is added to it as evidence instead. Nothing a tool call does writes shared memory directly. Other users see the shared copy only after the gate publishes it.

On Core there is no gate: share is accepted and the memory stays private. The legacy store ignores share too.

The guidance tells the model to share only facts useful to every user of the agent, such as a policy, a product detail or a procedure, and never personal facts about the user, their account or their circumstances.

The agent runtime shares with the conversation’s own agent. A conversation whose scope names no agent saves the memory privately. The share key is never stored in the memory’s metadata.

The dashboard’s MCP gateway serves no particular agent, so its memory__remember takes agent beside share: the name of an AgentRuntime in the workspace. The gateway sends that agent’s UID as the save’s share_agent_id, apart from the scope, so the user’s own copy stays in the user tier and the gateway’s memory__recall and memory__list find it at once; only the gate candidate targets the agent. A share without agent is a tool error, and so is an agent that does not exist or that the gateway cannot read. Neither saves anything.

memory__recall

Use this to search the tiers visible to the current scope.

Field	Purpose
query	Natural-language search text (required)
types	Restrict to specific memory types
limit	Maximum results to return
min_confidence	Minimum confidence threshold
kinds	Memory types to recall; merged into types
seed_name	Named entity from which to expand structural relations
relation_types	Relation types to follow during graph expansion
max_hops	Maximum graph hops, from 1 to 2
as_of	RFC 3339 timestamp at which active memory is evaluated

The response contains ranked memories. Each carries its tier and score in its metadata, and graph-expanded results also carry hop and via. A malformed kinds, relation_types, seed_name, max_hops or as_of returns an error to the agent instead of being ignored.

A memory whose body is larger than the policy’s recall.inlineThresholdBytes (8192 bytes by default) comes back as a preview: content is empty, and its metadata carries content_preview (the opening of the body) and has_full_body: true. The agent reads the rest with memory__open.

memory__open

Use this to read the full body of a memory that memory__recall returned as a preview.

Field	Purpose
memory_id	The memory’s id, from a memory__recall or memory__list result (required)

The result is one of:

status	Fields
opened	id, type, title (when the memory has one), content — the full body; parent_title and refs when present
not_found	id, message

On the brain store (MEMORY_STORE=brain), an opened memory also carries parent_title, the title of the document an ingested chunk belongs to, and refs, its media and artifact references, each {kind, ref, media_type?, sha256?, status, url?}. A media reference whose content is gone has status unavailable: the text is still returned. The legacy store returns neither field.

Open applies the same visibility as recall: the user’s own memories and the shared tiers the same scope recalls. An id the caller cannot see, an id that does not exist and an id that is not a memory id all return the same not_found result, so open reveals nothing about which ids exist.

memory__open is registered only together with memory__recall, and recall asks memory-api for previews only when open is registered beside it, so an agent is never handed a preview it cannot read.

memory__list and memory__forget

Use memory__list to browse the current scope, optionally filtering by type. Use memory__forget with a memory ID to remove a fact. Forgetting is a soft delete and prevents the memory from being recalled; it is not the update path.

Where the tool descriptions come from

The descriptions and extra fields above are not built into the agent runtime. memory-api renders them from the workspace’s effective MemoryPolicy, or from its built-in defaults when no policy is bound, and serves them at GET /api/v1/memory/tool-guidance. The agent runtime fetches them for each conversation with a verified user, and the dashboard’s memory MCP tools fetch the same guidance, so both present the same text. What the model reads therefore follows the policy:

Policy field	Effect on the tools
schema.types	memory__remember’s type enum: the types a user or user_for_agent write accepts (the built-in types without a policy). memory__recall’s kinds enum: every declared type
schema.relations	memory__recall’s relation_types enum
dedup.requireAboutForKinds	memory__remember names the types for which about_kind and about_key are required
recall.inlineThresholdBytes	memory__recall states the body size above which it returns a preview for memory__open

Two authored layers follow the derived text, and neither replaces it:

1. The MemoryPolicy’s toolGuidance notes, under “Notes for this workspace:”, added by memory-api.
2. The agent’s spec.memory.tools.notes, under “Notes for this agent:”, added by the agent runtime. The MCP gateway serves no particular agent, so it shows only the workspace notes.

Without a policy schema, kinds and relation_types are not restricted to a list: institutional ingestion may write types and relations the built-in schema does not name.

If memory-api cannot supply the guidance (for example, an older memory-api during an upgrade), each tool uses a short built-in description. That fallback still states the update rule and exposes about_kind, about_key, purpose, title, summary, share and the recall graph arguments, but offers no enums. A tool the guidance covers keeps any fallback field the guidance does not mention.

Identity and configuration

Memory tools and ambient retrieval are independent controls under AgentRuntime.spec.memory.tools and AgentRuntime.spec.memory.retrieval. Configure the agent in the AgentRuntime reference.