# AUTO-GENERATED tier-A mirror spec — do not edit. # Source: openapi/runtime/memory-rules.yaml (runtime 0.71.2) # + policy: openapi/mirror-policies/memory-rules.json # Regenerate: node scripts/generate-mirror-specs.mjs openapi: 3.0.3 info: title: naturali.ai — Memory Rules API version: 1.0.0 description: >- Memory rules: a memory store's ingestion policy — which completed turns it reads, what handler proposes facts from them, and the store's own write algorithm deciding what lands. A fully runtime-backed module — this spec is generated verbatim from the runtime's own, re-rooted under /v1/projects/{project_id}. The project in the path is authorized by naturali and enforced upstream by the project's scoped credential. This module mirrors the upstream runtime verbatim (tier A, #304): paths are the runtime's own re-rooted under /v1/projects/{project_id}, and every field, method, status code and error shape passes through unchanged. Errors raised by the runtime arrive in its envelope; errors raised by naturali itself (authentication, project resolution, an unreachable runtime) use naturali's. contact: name: naturali.ai url: https://naturali.ai servers: - url: "{baseUrl}" description: Host of your naturali.ai deployment; every path carries the /v1 prefix. variables: baseUrl: description: Base host URL. default: https://api.naturali.ai tags: - name: Memory Rules description: What a memory store accepts from completed agent turns security: - bearerAuth: [] - oauth2: - mcp:access paths: /v1/projects/{project_id}/memory-rules: get: tags: - Memory Rules summary: List memory rules description: Returns memory rules, newest first. Narrow to one store with `memory_store_id` — that form is authorized against the store itself, so it answers "what feeds this store?" in one call. operationId: listMemoryRules x-iam-action: memories:ListMemoryRules parameters: - name: memory_store_id in: query description: Only the rules of this memory store schema: type: string example: mstore_V1StGXR8Z5jdHi6B - name: limit in: query description: Number of results per page schema: type: integer minimum: 1 maximum: 100 default: 50 - name: offset in: query description: Number of results to skip schema: type: integer default: 0 responses: "200": description: List of memory rules content: application/json: schema: type: object required: - data - total - limit - offset properties: data: type: array items: $ref: "#/components/schemas/MemoryRule" total: type: integer limit: type: integer offset: type: integer "401": description: Unauthorized "403": description: Forbidden "500": description: Internal server error post: tags: - Memory Rules summary: Create a memory rule description: 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`. operationId: createMemoryRule x-naturali-resource: kind: memory_store from: memory_store_id x-iam-action: memories:CreateMemoryRule requestBody: required: true content: application/json: schema: type: object required: - memory_store_id - on additionalProperties: false properties: memory_store_id: x-naturali-ref: memory-stores type: string description: The destination store, and the rule's owning scope example: mstore_V1StGXR8Z5jdHi6B on: $ref: "#/components/schemas/MemoryRuleEvent" source_agent_ids: type: array nullable: true description: Agents whose turns this rule reads. Omit or send `null` for every agent in the store's project. items: x-naturali-ref: agents type: string example: - agent_V1StGXR8Z5jdHi6B agent_id: x-naturali-ref: agents type: string nullable: true description: Handler agent (mutually exclusive with tool_id) tool_id: x-naturali-ref: tools type: string nullable: true description: Handler tool (mutually exclusive with agent_id) action: type: string nullable: true description: Operation id, for a tool handler preset_parameters: type: object nullable: true description: Merged into a tool handler's input before invocation. The turn's own fields are reserved and win. prompt: type: string nullable: true description: 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_id: x-naturali-ref: ai-providers type: string nullable: true description: Provider override for the built-in extractor's completion. Not valid with a handler. model: type: string nullable: true description: Model override for the built-in extractor's completion. Not valid with a handler. enabled: type: boolean default: true description: A disabled rule is kept and never fires responses: "201": description: Memory rule created content: application/json: schema: $ref: "#/components/schemas/MemoryRule" "400": description: Validation failed (e.g. agent_id and tool_id both set, or an extractor override combined with a handler) "401": description: Unauthorized "403": description: Forbidden "404": description: Memory store not found "500": description: Internal server error parameters: - $ref: "#/components/parameters/ProjectId" /v1/projects/{project_id}/memory-rules/{memory_rule_id}: get: tags: - Memory Rules summary: Get a memory rule description: Returns a specific memory rule operationId: getMemoryRule x-naturali-resource: kind: memory_rule from: memory_rule_id x-iam-action: memories:GetMemoryRule parameters: - name: memory_rule_id in: path required: true description: Memory rule ID schema: type: string example: mrule_V1StGXR8Z5jdHi6B responses: "200": description: Memory rule details content: application/json: schema: $ref: "#/components/schemas/MemoryRule" "401": description: Unauthorized "403": description: Forbidden "404": description: Memory rule not found patch: tags: - Memory Rules summary: Update a memory rule description: Updates a memory rule. Validation runs against the rule as it would stand after the change, so a one-field update cannot pair a handler with a stored extractor override from the side. operationId: updateMemoryRule x-naturali-resource: kind: memory_rule from: memory_rule_id x-iam-action: memories:UpdateMemoryRule parameters: - name: memory_rule_id in: path required: true description: Memory rule ID schema: type: string requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: on: $ref: "#/components/schemas/MemoryRuleEvent" source_agent_ids: type: array nullable: true description: Send `null` to widen the rule to every agent in the project items: x-naturali-ref: agents type: string agent_id: x-naturali-ref: agents type: string nullable: true tool_id: x-naturali-ref: tools type: string nullable: true action: type: string nullable: true preset_parameters: type: object nullable: true prompt: type: string nullable: true ai_provider_id: x-naturali-ref: ai-providers type: string nullable: true model: type: string nullable: true enabled: type: boolean responses: "200": description: Memory rule updated content: application/json: schema: $ref: "#/components/schemas/MemoryRule" "400": description: Validation failed "401": description: Unauthorized "403": description: Forbidden "404": description: Memory rule not found delete: tags: - Memory Rules summary: Delete a memory rule description: Deletes a memory rule. The assertions it wrote are kept; their `rule_id` becomes null. operationId: deleteMemoryRule x-naturali-resource: kind: memory_rule from: memory_rule_id x-iam-action: memories:DeleteMemoryRule parameters: - name: memory_rule_id in: path required: true description: Memory rule ID schema: type: string responses: "204": description: Memory rule deleted "401": description: Unauthorized "403": description: Forbidden "404": description: Memory rule not found parameters: - $ref: "#/components/parameters/ProjectId" components: schemas: MemoryRuleEvent: type: string enum: - agents.generation.completed - conversations.message.generated description: The event a firing reads. `agents.generation.completed` fires once per completed turn whatever the transport, and is the only event the built-in extractor may bind to. `conversations.message.generated` fires per persisted assistant reply and is conversation-backed, so it is for custom handlers. example: agents.generation.completed MemoryRule: type: object properties: id: type: string example: mrule_V1StGXR8Z5jdHi6B memory_store_id: x-naturali-ref: memory-stores type: string project_id: x-naturali-ref: projects type: string on: $ref: "#/components/schemas/MemoryRuleEvent" source_agent_ids: type: array nullable: true items: x-naturali-ref: agents type: string agent_id: x-naturali-ref: agents type: string nullable: true tool_id: x-naturali-ref: tools type: string nullable: true action: type: string nullable: true preset_parameters: type: object nullable: true prompt: type: string nullable: true ai_provider_id: x-naturali-ref: ai-providers type: string nullable: true model: type: string nullable: true enabled: type: boolean created_at: type: string format: date-time updated_at: type: string format: date-time parameters: ProjectId: name: project_id in: path required: true description: Project public ID (proj_ prefix). schema: type: string example: proj_V1StGXR8Z5jdHi6B securitySchemes: bearerAuth: type: http scheme: bearer description: A naturali API key (nat_sk_…) or a session JWT. oauth2: type: oauth2 description: "A connected app's OAuth access token, issued by this API's authorization server (discovery: /.well-known/oauth-authorization-server). Its one scope carries every operation, confined to the projects the user chose when approving the app." flows: authorizationCode: authorizationUrl: https://api.naturali.ai/authorize tokenUrl: https://api.naturali.ai/token refreshUrl: https://api.naturali.ai/token scopes: mcp:access: Every operation this API serves, on the projects the grant covers.