Skip to main content

MemoryStores Commands

See MemoryStores module docs for permissions and data model.

soat list-memory-stores​

List memory stores

  • Method: GET
  • Path: /api/v1/memory-stores

Usage​

soat list-memory-stores

Options​

--project-id​

Project ID (required if not using project key auth)

  • Source: query
  • Required: no
  • Type: string
  • Example: proj_V1StGXR8Z5jdHi6B

soat create-memory-store​

Create a memory store

  • Method: POST
  • Path: /api/v1/memory-stores

Usage​

soat create-memory-store --name <string>

Options​

--project-id​

Project ID (required if not using project key auth)

  • Source: body
  • Required: no
  • Type: string
  • Example: proj_V1StGXR8Z5jdHi6B
--name​

Memory store name

  • Source: body
  • Required: yes
  • Type: string
  • Example: Product Documentation
--description​

Optional description

  • Source: body
  • Required: no
  • Type: string
  • Example: Retrieves product docs for support queries
--tags​

Optional key-value tags. Scopes the memory store in knowledge search, where every requested pair must match exactly.

  • Source: body
  • Required: no
  • Type: unknown
--duplicate-threshold​

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 /api/v1/memories call may override it; the agent tool and the post-turn rule never can.

  • Source: body
  • Required: no
  • Type: number \| null
  • Example: 0.95
--supersede-threshold​

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.

  • Source: body
  • Required: no
  • Type: number \| null
  • Example: 0.9

soat get-memory-store​

Get a memory store

  • Method: GET
  • Path: /api/v1/memory-stores/{memory_store_id}

Usage​

soat get-memory-store --memory-store-id <string>

Options​

--memory-store-id​

—

  • Source: path
  • Required: yes
  • Type: string
  • Example: mstore_V1StGXR8Z5jdHi6B

soat update-memory-store​

Update a memory store

  • Method: PUT
  • Path: /api/v1/memory-stores/{memory_store_id}

Usage​

soat update-memory-store --memory-store-id <string>

Options​

--memory-store-id​

—

  • Source: path
  • Required: yes
  • Type: string
  • Example: mstore_V1StGXR8Z5jdHi6B
--name​

Memory store name

  • Source: body
  • Required: no
  • Type: string
--description​

Optional description

  • Source: body
  • Required: no
  • Type: string \| null
--tags​

Optional key-value tags. Replaces the stored bag; null clears it.

  • Source: body
  • Required: no
  • Type: unknown
--duplicate-threshold​

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 /api/v1/memories call may override it; the agent tool and the post-turn rule never can.

  • Source: body
  • Required: no
  • Type: number \| null
  • Example: 0.95
--supersede-threshold​

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.

  • Source: body
  • Required: no
  • Type: number \| null
  • Example: 0.9

soat delete-memory-store​

Delete a memory store

  • Method: DELETE
  • Path: /api/v1/memory-stores/{memory_store_id}

Usage​

soat delete-memory-store --memory-store-id <string>

Options​

--memory-store-id​

—

  • Source: path
  • Required: yes
  • Type: string
  • Example: mstore_V1StGXR8Z5jdHi6B

soat list-memory-store-assertions​

List a memory store's write assertions

  • Method: GET
  • Path: /api/v1/memory-stores/{memory_store_id}/assertions

Usage​

soat list-memory-store-assertions --memory-store-id <string>

Options​

--memory-store-id​

—

  • Source: path
  • Required: yes
  • Type: string
  • Example: mstore_V1StGXR8Z5jdHi6B
--mechanism​

Only assertions that came through this door.

  • Source: query
  • Required: no
  • Type: enum("tool", "rule", "api", "formation")
--outcome​

Only assertions that resolved this way.

  • Source: query
  • Required: no
  • Type: enum("created", "superseded", "skipped")
--generation-id​

Only assertions made during this generation. A generation that does not exist matches nothing rather than widening to the whole store.

  • Source: query
  • Required: no
  • Type: string
  • Example: gen_V1StGXR8Z5jdHi6B
--from​

Only assertions recorded at or after this instant (ISO 8601).

  • Source: query
  • Required: no
  • Type: string
--to​

Only assertions recorded at or before this instant (ISO 8601).

  • Source: query
  • Required: no
  • Type: string

soat export-memories​

Export a memory store's memories as NDJSON

  • Method: GET
  • Path: /api/v1/memory-stores/{memory_store_id}/export

Usage​

soat export-memories --memory-store-id <string>

Options​

--memory-store-id​

Memory store whose memories are exported

  • Source: path
  • Required: yes
  • Type: string
  • Example: mem_store_V1StGXR8Z5jdHi6B
--include-invalidated​

Include memories that were retracted or superseded

  • Source: query
  • Required: no
  • Type: boolean
  • Default: false

soat get-memory-store-tags​

Get memory store tags

  • Method: GET
  • Path: /api/v1/memory-stores/{memory_store_id}/tags

Usage​

soat get-memory-store-tags --memory-store-id <string>

Options​

--memory-store-id​

Memory store ID

  • Source: path
  • Required: yes
  • Type: string
  • Example: mstore_V1StGXR8Z5jdHi6B

soat replace-memory-store-tags​

Replace memory store tags

  • Method: PUT
  • Path: /api/v1/memory-stores/{memory_store_id}/tags

Usage​

soat replace-memory-store-tags --memory-store-id <string> --tags <object>

Options​

--memory-store-id​

Memory store ID

  • Source: path
  • Required: yes
  • Type: string
  • Example: mstore_V1StGXR8Z5jdHi6B
--tags​

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, knowledge search, and the IAM soat:ResourceTag/<key> condition. 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.

  • Source: body
  • Required: yes
  • Type: object

soat merge-memory-store-tags​

Merge memory store tags

  • Method: PATCH
  • Path: /api/v1/memory-stores/{memory_store_id}/tags

Usage​

soat merge-memory-store-tags --memory-store-id <string> --tags <object>

Options​

--memory-store-id​

Memory store ID

  • Source: path
  • Required: yes
  • Type: string
  • Example: mstore_V1StGXR8Z5jdHi6B
--tags​

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, knowledge search, and the IAM soat:ResourceTag/<key> condition. 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.

  • Source: body
  • Required: yes
  • Type: object