MemoryStores

Create a memory store

Creates a new memory store configuration in a project

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

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/memory-stores
  • 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

namestring required

Memory store name

descriptionstring

Optional description

tagsTagBag

Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with 400 VALIDATION_FAILED, never coerced. Keys are opaque and stored verbatim, so cost_center and costCenter are two different tags. Matched by JSONB containment wherever tags are read: the ?tags= filter and knowledge search.

Keys beginning system. are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with 400 RESERVED_TAG_KEY. They are read and filtered like any other tag.

The bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is 400 VALIDATION_FAILED with meta.limit naming the bound it crossed. system.* keys are the platform's and do not count against the 50.

duplicate_thresholdnumber nullable

The store's dedup policy: cosine similarity at or above which an incoming fact is already known and the write is skipped. null (the default) uses the algorithm constant 0.95. A single POST /v1/projects/{project_id}/memories call may override it; the agent tool and the post-turn rule never can.

supersede_thresholdnumber nullable

Cosine similarity at or above which an incoming fact restates a known one that has changed: the matched memory is invalidated and replaced. null (the default) uses the algorithm constant 0.90. Must be lower than the effective duplicate_threshold, or the write is rejected with 400 VALIDATION_FAILED — equal makes superseded unreachable and inverted swallows skipped.

Example request

{
  "name": "Product Documentation",
  "description": "Retrieves product docs for support queries",
  "tags": {
    "team": "finance",
    "env": "prod"
  },
  "duplicate_threshold": 0.95,
  "supersede_threshold": 0.9
}

Response

Memory store created

idstring
project_idstring
namestring
descriptionstring nullable
tagsTagBag

Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with 400 VALIDATION_FAILED, never coerced. Keys are opaque and stored verbatim, so cost_center and costCenter are two different tags. Matched by JSONB containment wherever tags are read: the ?tags= filter and knowledge search.

Keys beginning system. are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with 400 RESERVED_TAG_KEY. They are read and filtered like any other tag.

The bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is 400 VALIDATION_FAILED with meta.limit naming the bound it crossed. system.* keys are the platform's and do not count against the 50.

duplicate_thresholdnumber nullable

The store's duplicate cutoff, or null when it has never been set. Reported as null rather than as the constant it resolves to: a store with no policy must read differently from one pinned to today's default.

supersede_thresholdnumber nullable

The store's supersede cutoff, or null when it has never been set.

created_atstring date-time
updated_atstring date-time

Example response

{
  "id": "mstore_V1StGXR8Z5jdHi6B",
  "project_id": "proj_V1StGXR8Z5jdHi6B",
  "name": "Product Documentation",
  "description": "Retrieves product docs for support queries",
  "tags": {
    "team": "finance",
    "env": "prod"
  },
  "duplicate_threshold": 0.95,
  "supersede_threshold": 0.9
}

Changes

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