Skip to main content

Memories Commands

See Memories module docs for permissions and data model.

soat list-memories​

List memories

  • Method: GET
  • Path: /api/v1/memories

Usage​

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

Options​

--memory-store-id​

Memory store to list memories from (mstore_...)

  • Source: query
  • Required: yes
  • Type: string
  • Example: mstore_V1StGXR8Z5jdHi6B
--include-invalidated​

Include invalidated memories — superseded or retracted. They are excluded by default; set this to audit what a store once held.

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

soat create-memory​

Create a memory

  • Method: POST
  • Path: /api/v1/memories

Usage​

soat create-memory --memory-store-id <string> --content <string>

Options​

--memory-store-id​

Memory store to add the memory to (mstore_...)

  • Source: body
  • Required: yes
  • Type: string
  • Example: mstore_V1StGXR8Z5jdHi6B
--content​

The text content of the memory

  • Source: body
  • Required: yes
  • Type: string
  • Example: The customer prefers email communication over phone calls
--source-type​

Whether there is a source to point at. conversation requires source_id; manual rejects it.

  • Source: body
  • Required: no
  • Type: enum("manual", "conversation")
  • Default: manual
  • Example: manual
--source-id​

The conversation this fact was learned in. Required when source_type is conversation, and rejected otherwise.

  • Source: body
  • Required: no
  • Type: string
  • Example: conv_V1StGXR8Z5jdHi6B
--tags​

Per-memory key-value tags, used for memory-granularity filtering by tags in search-knowledge.

  • Source: body
  • Required: no
  • Type: unknown
--metadata​

Arbitrary structured metadata attached to the memory

  • Source: body
  • Required: no
  • Type: unknown
  • Example: \{"evidence":"high","quarter":"Q3"\}
--supersedes​

The memory this write replaces, named outright. The declaration outranks the thresholds in both directions: the target is retired and the write returns superseded however similar or distant the two texts are. This is what reaches a contradiction cosine cannot see ("The office is in Lisbon" then "We closed the Lisbon office"). The target must be a still-valid memory in the same memory store, and the caller needs memories:UpdateMemory on it as well as memories:CreateMemory on the store.

  • Source: body
  • Required: no
  • Type: string
  • Example: mem_V1StGXR8Z5jdHi6B
--duplicate-threshold​

Cosine similarity at or above which the incoming content is a duplicate of an existing memory and the write is skipped. Overrides the store's duplicate_threshold for this call; falls back to the store's value, then to 0.95.

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

Cosine similarity at or above which the incoming content restates a fact that has changed: the top match is invalidated and a new memory replaces it. Overrides the store's supersede_threshold for this call; falls back to the store's value, then to 0.90. The effective pair must satisfy supersede_threshold < duplicate_threshold, and the check runs against the effective pair — so overriding only one value cannot invert it against the store's other one.

  • Source: body
  • Required: no
  • Type: number
  • Example: 0.9

soat get-memory​

Get a memory

  • Method: GET
  • Path: /api/v1/memories/{memory_id}

Usage​

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

Options​

--memory-id​

—

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

soat update-memory​

Update a memory

  • Method: PUT
  • Path: /api/v1/memories/{memory_id}

Usage​

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

Options​

--memory-id​

—

  • Source: path
  • Required: yes
  • Type: string
  • Example: mem_V1StGXR8Z5jdHi6B
--content​

Updated text content

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

Replaces the memory's tags. Pass null or an empty object to clear.

  • Source: body
  • Required: no
  • Type: unknown
--metadata​

Replaces the memory's metadata. Pass null to clear.

  • Source: body
  • Required: no
  • Type: unknown
--expected-version​

Refuses the write unless the memory is at this version.

  • Source: body
  • Required: no
  • Type: unknown

soat delete-memory​

Delete a memory

  • Method: DELETE
  • Path: /api/v1/memories/{memory_id}

Usage​

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

Options​

--memory-id​

—

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

soat retract-memory​

Retract a memory

  • Method: POST
  • Path: /api/v1/memories/{memory_id}/retract

Usage​

soat retract-memory --memory-id <string>

Options​

--memory-id​

—

  • Source: path
  • Required: yes
  • Type: string
  • Example: mem_V1StGXR8Z5jdHi6B
--expected-version​

Refuses the retraction unless the memory is at this version.

  • Source: body
  • Required: no
  • Type: unknown

soat list-memory-assertions​

List a memory's assertions

  • Method: GET
  • Path: /api/v1/memories/{memory_id}/assertions

Usage​

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

Options​

--memory-id​

—

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

soat get-memory-tags​

Get memory tags

  • Method: GET
  • Path: /api/v1/memories/{memory_id}/tags

Usage​

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

Options​

--memory-id​

Memory ID

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

soat replace-memory-tags​

Replace memory tags

  • Method: PUT
  • Path: /api/v1/memories/{memory_id}/tags

Usage​

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

Options​

--memory-id​

Memory ID

  • Source: path
  • Required: yes
  • Type: string
  • Example: mem_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-tags​

Merge memory tags

  • Method: PATCH
  • Path: /api/v1/memories/{memory_id}/tags

Usage​

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

Options​

--memory-id​

Memory ID

  • Source: path
  • Required: yes
  • Type: string
  • Example: mem_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