Memory Layers
Manage memory layers and their entries. Layers are named containers that can be composed into an objective’s memory stack; entries are the keyed values within a layer. System-managed layers (e.g., episodic layers created by the runtime) cannot be mutated through this API.
List memory layers
Create a new memory layer
Get a memory layer by ID
Update a memory layer
Delete a memory layer
ModelsExpand Collapse
MemoryLayer object { metadata, spec, info }
MemoryLayer is a named container of memory entries that can be composed into an objective’s memory stack. Layers are workspace-scoped resources. The layer type controls how its entries participate in the agent loop — see MemoryLayerType for details.
See “Memory stack composition” above for how layers compose at lookup time.
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
bundleKey: optional string
Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply.
description: optional string
Human-readable description of the layer’s purpose. Encouraged for user-created layers; system-managed layers may have a generated description.
expiresAt: optional string
For layers with a finite lifetime (e.g., episodic), the time at which the layer becomes eligible for cleanup. Set by the system; unset for persistent layers.
systemManaged: optional boolean
Server-set. True for layers managed by the system (e.g., episodic layers created automatically when an objective uses an episodic_key). System-managed layers cannot be assigned to objective stacks via the API and cannot be mutated by clients — their lifecycle is controlled entirely by the runtime.
A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces.
AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.
MemoryLayerInfo object { createdBy, entryCount, lastUsedAt }
A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces.
AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.
MemoryLayerSpec object { type, description, expiresAt, systemManaged }
description: optional string
Human-readable description of the layer’s purpose. Encouraged for user-created layers; system-managed layers may have a generated description.
expiresAt: optional string
For layers with a finite lifetime (e.g., episodic), the time at which the layer becomes eligible for cleanup. Set by the system; unset for persistent layers.
systemManaged: optional boolean
Server-set. True for layers managed by the system (e.g., episodic layers created automatically when an objective uses an episodic_key). System-managed layers cannot be assigned to objective stacks via the API and cannot be mutated by clients — their lifecycle is controlled entirely by the runtime.
Memory LayersEntries
Manage memory layers and their entries. Layers are named containers that can be composed into an objective’s memory stack; entries are the keyed values within a layer. System-managed layers (e.g., episodic layers created by the runtime) cannot be mutated through this API.
List memory entries
Create a new memory entry
Get a memory entry by ID
Update a memory entry
Delete a memory entry
ModelsExpand Collapse
MemoryEntry object { metadata, spec, info }
MemoryEntry is a single keyed value within a MemoryLayer. Entries are addressed by their key, which follows the S3 object key safe-character convention (see MemoryEntrySpec.key for the full rule). Keys are unique within a single layer; the same key may appear in multiple layers, in which case the LIFO stack-walk determines which one wins for a given objective.
MemoryEntry is the summary shape, returned by ListMemoryEntries. It does not carry the entry body — callers that need the body must fetch the entry individually via GetMemoryEntry, which returns a MemoryEntryDetail.
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
bundleKey: optional string
Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply.
MemoryEntrySpec is the metadata portion of an entry — the fields that identify and describe it, without the body. It appears on both the summary (MemoryEntry) and detail (MemoryEntryDetail) views.
key: string
The lookup key for this entry within its layer. Must conform to the S3 object key safe-characters spec: ASCII alphanumerics and the special characters !, -, _, ., *, ’, (, ), and /. Forward slashes may be used to suggest hierarchy (e.g., “skills/postmortem/write”), but lookups are flat — the key is a single opaque string, not a path.
Additional rules enforced by the service:
- May not begin or end with /
- May not contain consecutive slashes (//)
- May not begin with reserved prefixes (cadenya/, system/)
- Case-sensitive
- Unique within the parent layer
For skills entries, this key is also the id the model passes to memory_load_skill when it decides to load the entry’s content.
A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces.
AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
bundleKey: optional string
Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply.
MemoryEntryDetail object { content, metadata, spec, info }
MemoryEntryDetail is the full representation of an entry, including the resolved content body. Returned by GetMemoryEntry, CreateMemoryEntry, and UpdateMemoryEntry.
content: string
The resolved body of the entry. For entries created or updated via an upload_id, this is the ingested content, not the original upload handle. May be empty; an entry with only a key and description is valid (e.g., a stub skill being drafted, or an entry where the frontmatter alone is the payload).
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
bundleKey: optional string
Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply.
MemoryEntrySpec is the metadata portion of an entry — the fields that identify and describe it, without the body. It appears on both the summary (MemoryEntry) and detail (MemoryEntryDetail) views.
key: string
The lookup key for this entry within its layer. Must conform to the S3 object key safe-characters spec: ASCII alphanumerics and the special characters !, -, _, ., *, ’, (, ), and /. Forward slashes may be used to suggest hierarchy (e.g., “skills/postmortem/write”), but lookups are flat — the key is a single opaque string, not a path.
Additional rules enforced by the service:
- May not begin or end with /
- May not contain consecutive slashes (//)
- May not begin with reserved prefixes (cadenya/, system/)
- Case-sensitive
- Unique within the parent layer
For skills entries, this key is also the id the model passes to memory_load_skill when it decides to load the entry’s content.
A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces.
AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
bundleKey: optional string
Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply.
MemoryEntryInfo object { createdBy, memoryLayer }
A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces.
AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
bundleKey: optional string
Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply.
MemoryEntrySpec object { key, description }
MemoryEntrySpec is the metadata portion of an entry — the fields that identify and describe it, without the body. It appears on both the summary (MemoryEntry) and detail (MemoryEntryDetail) views.
key: string
The lookup key for this entry within its layer. Must conform to the S3 object key safe-characters spec: ASCII alphanumerics and the special characters !, -, _, ., *, ’, (, ), and /. Forward slashes may be used to suggest hierarchy (e.g., “skills/postmortem/write”), but lookups are flat — the key is a single opaque string, not a path.
Additional rules enforced by the service:
- May not begin or end with /
- May not contain consecutive slashes (//)
- May not begin with reserved prefixes (cadenya/, system/)
- Case-sensitive
- Unique within the parent layer
For skills entries, this key is also the id the model passes to memory_load_skill when it decides to load the entry’s content.
MemoryEntryUpdateSpec object { content, description, key, uploadId }
MemoryEntryUpdateSpec is the input shape for UpdateMemoryEntry. Fields present in the request’s update_mask are applied; unset fields are left alone. The source oneof is optional for updates — omit it to leave the body untouched, or set exactly one branch to replace it.