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
type MemoryLayer struct{…}
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.
Metadata ResourceMetadata
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
Spec MemoryLayerSpec
Description stringOptional
Human-readable description of the layer’s purpose. Encouraged for user-created layers; system-managed layers may have a generated description.
ExpiresAt TimeOptional
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 boolOptional
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.
Metadata AccountResourceMetadata
Spec ProfileSpec
type MemoryLayerInfo struct{…}
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.
Metadata AccountResourceMetadata
Spec ProfileSpec
type MemoryLayerSpec struct{…}
Description stringOptional
Human-readable description of the layer’s purpose. Encouraged for user-created layers; system-managed layers may have a generated description.
ExpiresAt TimeOptional
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 boolOptional
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
type MemoryEntry struct{…}
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.
Metadata ResourceMetadata
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
Spec MemoryEntrySpec
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.
Metadata AccountResourceMetadata
Spec ProfileSpec
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
type MemoryEntryDetail struct{…}
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).
Metadata ResourceMetadata
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
Spec MemoryEntrySpec
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.
Metadata AccountResourceMetadata
Spec ProfileSpec
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
type MemoryEntryInfo struct{…}
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.
Metadata AccountResourceMetadata
Spec ProfileSpec
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
type MemoryEntrySpec struct{…}
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.
type MemoryEntryUpdateSpec struct{…}
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.