Memory Rules

Create a memory rule

Creates an ingestion rule on a memory store. With neither agent_id nor tool_id the built-in extractor runs, configurable through prompt, ai_provider_id and model.

post/v1/projects/{project_id}/memory-rules

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/memory-rules
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Request body

memory_store_idstring required

The destination store, and the rule's owning scope

on'generations.completed' | 'conversation_messages.generated' required

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_idsstring[] nullable

Agents whose turns this rule reads. Omit or send null for every agent in the store's project.

agent_idstring nullable

Handler agent (mutually exclusive with tool_id)

tool_idstring nullable

Handler tool (mutually exclusive with agent_id)

actionstring nullable

Operation id, for a tool handler

preset_parametersobject nullable

Merged into a tool handler's input before invocation. The turn's own fields are reserved and win.

promptstring nullable

Replaces the built-in extractor's task instructions. The JSON response contract and the transcript are always appended. Not valid with a handler.

ai_provider_idstring nullable

Provider override for the built-in extractor's completion. Not valid with a handler.

modelstring nullable

Model override for the built-in extractor's completion. Not valid with a handler.

enabledboolean

A disabled rule is kept and never fires

Example request

{
  "memory_store_id": "mstore_V1StGXR8Z5jdHi6B",
  "on": "generations.completed",
  "source_agent_ids": [
    "agent_V1StGXR8Z5jdHi6B"
  ]
}

Response

Memory rule created

idstring
memory_store_idstring
project_idstring
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_idsstring[] nullable
agent_idstring nullable
tool_idstring nullable
actionstring nullable
preset_parametersobject nullable
promptstring nullable
ai_provider_idstring nullable
modelstring nullable
enabledboolean
created_atstring date-time
updated_atstring date-time

Example response

{
  "id": "mrule_V1StGXR8Z5jdHi6B",
  "on": "generations.completed"
}

Changes

No recorded changes to this operation across all 1 revision of this API.