Mount a Memory Store to an Identity and Template.
Mounts an existing Memory Store to an
An Identity-level Service Account Token can only operate on its own Identity. Operating on another Identity returns
HTTP 200 OK
Returns a Memory Store mount object.
When multiple Stores are mounted, the Agent sees the Memories from all Stores merged into a flat namespace by
(identity, template) pair. Sessions created by that Identity with the Template then receive the Store's Memory content automatically.
Repeated mounts: Calling again for the same Store updates its permission when access is supplied and preserves it when omitted. No duplicate mount is created; created_at remains the original mount time.
Path
POST /api/v1/forward/identities/{identity_id}/templates/{template_id}/memory_stores
Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <PAT, admin SAT, or SAT for this Identity> |
Content-Type | Yes | application/json |
403.
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
identity_id | string | Yes | Identity ID (idn_...). |
template_id | string | Yes | Template ID (tmpl_...). |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
memory_store_id | string | Yes | ID of the Memory Store to mount (memstore_...). It must be an active Store visible to the caller. |
access | string | No | read_only or read_write. If omitted, new mounts default to read_only and existing mounts retain their current permission. |
Example request
Example response
HTTP 200 OK
Response
Returns a Memory Store mount object.
Notes
When multiple Stores are mounted, the Agent sees the Memories from all Stores merged into a flat namespace by path. Identical paths can shadow each other. See Visibility in a Session.
Mount and permission changes apply to Sessions created afterward; existing Sessions are not updated automatically.
Errors
| HTTP | Type | Trigger |
|---|---|---|
| 400 | invalid_request_error | Invalid memory_store_id or access, an archived Store, or an attempt to make the system-managed default Store read-only. |
| 401 | authentication_error | The authentication token is missing or invalid. |
| 403 | permission_error | An Identity-level SAT tried to operate on another Identity. |
| 404 | not_found_error | The Identity, Template, or Memory Store does not exist or is not visible. |
| 500/502/503 | api_error | Forward or a dependent service failed. |