Memory Layers
MemoryService manages memory layers and their entries at the WORKSPACE level. Layers are named containers that can be composed into an objective's memory stack; entries are the keyed values within a layer.
All operations are implicitly scoped to the workspace determined by the JWT token. System-managed layers (e.g., episodic layers created by the runtime) cannot be mutated through this API.
Authentication: Bearer token (JWT) Scope: Workspace-level operations
List memory layers
Create a new memory layer
Get a memory layer by ID
Update 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.
Memory stacks are LIFO: when an objective resolves a key, layers are walked from the top of the stack downward, and the first matching entry wins.
Metadata ResourceMetadata
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.
Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS).
Metadata AccountResourceMetadata
Spec ProfileSpec
type MemoryLayerInfo struct{…}
Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS).
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
MemoryService manages memory layers and their entries at the WORKSPACE level. Layers are named containers that can be composed into an objective's memory stack; entries are the keyed values within a layer.
All operations are implicitly scoped to the workspace determined by the JWT token. System-managed layers (e.g., episodic layers created by the runtime) cannot be mutated through this API.
Authentication: Bearer token (JWT) Scope: Workspace-level operations
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
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.
Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS).
Metadata AccountResourceMetadata
Spec ProfileSpec
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, title, and description is valid (e.g., a stub skill being drafted, or an entry where the frontmatter alone is the payload).
Metadata ResourceMetadata
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.
Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS).
Metadata AccountResourceMetadata
Spec ProfileSpec
type MemoryEntryInfo struct{…}
Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS).
Metadata AccountResourceMetadata
Spec ProfileSpec
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.