Memory Rules
A memory store's ingestion policy: which completed agent turns feed it, and who decides what is worth keeping.
Overview
A memory rule lives on the destination store, because the question it answers — what feeds this corpus? — is a property of the store, not of any one agent. One store can carry several rules, one agent can feed two stores under different rules, and "what feeds this store?" is one listing rather than a sweep over every agent in the project.
That makes it the opposite half of the write_memory tool an agent gets from
knowledge_config.write_memory_store_id:
write_memory tool | memory rule | |
|---|---|---|
| Who decides | the agent, mid-turn, at its discretion | the platform, after every completed turn |
| What it is | a capability grant | an ingestion policy |
| Reads | the agent's whole context | exactly one turn's transcript |
| Lives on | the agent | the memory store |
Give an agent long-term memory uses a rule; Limit what an agent may do uses the tool.
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.
See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Memory Rules.
Data Model
MemoryRule
| Field | Type | Description |
|---|---|---|
policy_ids | string[] | The policies every handler the rule starts acts under. Empty for one written without any, which does not run until a write gives it one. |
id | string | |
memory_store_id | string | |
project_id | string | |
on | generations.completed | conversation_messages.generated | The event a firing reads. generations.completed fires once per completed turn whatever the transport, and is the only event the built-in extractor may bind to. conversation_messages.generated fires per persisted assistant reply and is conversation-backed, so it is for custom handlers. |
source_agent_ids | string[], nullable | |
agent_id | string, nullable | |
tool_id | string, nullable | |
action | string, nullable | |
preset_parameters | object, nullable | |
prompt | string, nullable | |
ai_provider_id | string, nullable | |
model | string, nullable | |
enabled | boolean | |
created_at | string (date-time) | |
updated_at | string (date-time) |
memory_store_id is the destination store and the rule's
owning scope: deleting the store deletes its rules. source_agent_ids names the
agents whose turns the rule reads; null is every agent in the
project. The handler is an agent (agent_id) or a tool
(tool_id), never both; a tool handler takes an action, and
preset_parameters merged into its input, where the turn's own fields are
reserved and win. prompt, ai_provider_id and model override the built-in
extractor's task instructions, provider and model. A disabled rule is kept and
never fires.
Key Concepts
Which turns a rule reads
on | Fires | Fit |
|---|---|---|
generations.completed | once per completed turn — conversation or bare, streaming or not | turn-level extraction, and the only event the built-in extractor may bind to |
conversation_messages.generated | once per persisted assistant reply | conversation-backed only; for a custom handler |
source_agent_ids narrows further. Leave it out and every agent in the project
feeds the store.
Give an agent long-term memory
binds one agent on generations.completed.
Handlers propose, the store decides
A handler reads one turn's transcript and answers with candidate facts:
{ "facts": [{ "content": "Customer prefers email", "tags": { "kind": "preference" } }] }
| Handler | Set | Behaviour |
|---|---|---|
| built-in extractor | neither agent_id nor tool_id | a tool-less completion over the transcript, asking for atomic facts. prompt, ai_provider_id and model tune it |
| agent | agent_id | the agent is generated against the transcript and its reply is parsed as the contract above |
| tool | tool_id (+ action) | the tool is called with the turn's context plus preset_parameters, and its output is parsed as the contract above |
The three built-in extractor fields cannot be combined with a handler: a handler makes its own model call, or none, so they would be accepted and ignored.
Every candidate then goes through the store's own
write algorithm on its effective
thresholds, and each write appends an
assertion with mechanism: "rule". A
handler can propose garbage and cannot corrupt the store. A rule never blocks or
fails the turn it reads: a handler that throws, times out or answers with
nonsense contributes nothing.
Firings on generations.completed also record a summary on the
originating generation's extraction field, keyed by rule
id — a store can carry several rules, so one flat pair of counts could not say
which produced them.
Give an agent long-term memory
reads both: the fact the built-in extractor stored and the turn's extraction.
Handler authority
A rule's handler runs under the rule's own policy_ids, whoever started the turn
it reads: a tool handler's call, and every tool call an agent handler's turn
makes, is authorized by that grant alone. A handler the grant may not start
(tools:CallTool or agents:CreateAgentGeneration) is never called. A rule
with empty policy_ids contributes nothing until a write gives it some.
policy_ids is required on create (400 VALIDATION_FAILED). The writer must
hold every grant the policies carry
(403 POLICY_GRANT_NOT_HELD), and a policy a rule names cannot be deleted
(409 POLICY_HAS_DEPENDENTS).
Who may do what
Every route needs any project member. Every route is authorized against the store the rule belongs to.
Examples
Add a rule to a store
With no handler the built-in extractor runs; pol_V1StGXR8Z5jdHi6B allows
memories:CreateMemory (Handler authority).
- CLI
- SDK
- curl
naturali create-memory-rule \
--project-id proj_V1StGXR8Z5jdHi6B \
--memory-store-id mstore_V1StGXR8Z5jdHi6B \
--on generations.completed \
--source-agent-ids agent_V1StGXR8Z5jdHi6B \
--policy-ids pol_V1StGXR8Z5jdHi6B
const { data: memoryRule } = await naturali.memoryRules.createMemoryRule({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: {
memory_store_id: 'mstore_V1StGXR8Z5jdHi6B',
on: 'generations.completed',
source_agent_ids: ['agent_V1StGXR8Z5jdHi6B'],
policy_ids: ['pol_V1StGXR8Z5jdHi6B'],
},
});
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/memory-rules \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"memory_store_id": "mstore_V1StGXR8Z5jdHi6B",
"on": "generations.completed",
"source_agent_ids": ["agent_V1StGXR8Z5jdHi6B"],
"policy_ids": ["pol_V1StGXR8Z5jdHi6B"]
}'
Read one store's policy
- CLI
- SDK
- curl
naturali list-memory-rules \
--project-id proj_V1StGXR8Z5jdHi6B \
--memory-store-id mstore_V1StGXR8Z5jdHi6B
const { data: memoryRules } = await naturali.memoryRules.listMemoryRules({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
query: { memory_store_id: 'mstore_V1StGXR8Z5jdHi6B' },
});
curl "https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/memory-rules?memory_store_id=mstore_V1StGXR8Z5jdHi6B" \
-H "Authorization: Bearer $NATURALI_TOKEN"
Turn a rule off without losing it
- CLI
- SDK
- curl
naturali update-memory-rule \
--project-id proj_V1StGXR8Z5jdHi6B \
--memory-rule-id mrule_V1StGXR8Z5jdHi6B \
--enabled false
const { data: memoryRule } = await naturali.memoryRules.updateMemoryRule({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
memory_rule_id: 'mrule_V1StGXR8Z5jdHi6B',
},
body: { enabled: false },
});
curl -X PATCH https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/memory-rules/mrule_V1StGXR8Z5jdHi6B \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "enabled": false }'