Skip to content
cadenya
Get started
API Reference
Memory Layers

Entries

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
client.MemoryLayers.Entries.List(ctx, memoryLayerID, query) (*CursorPagination[MemoryEntry], error)
GET/v1/memory_layers/{memoryLayerId}/entries
Create a new memory entry
client.MemoryLayers.Entries.New(ctx, memoryLayerID, body) (*MemoryEntryDetail, error)
POST/v1/memory_layers/{memoryLayerId}/entries
Get a memory entry by ID
client.MemoryLayers.Entries.Get(ctx, memoryLayerID, id) (*MemoryEntryDetail, error)
GET/v1/memory_layers/{memoryLayerId}/entries/{id}
Update a memory entry
client.MemoryLayers.Entries.Update(ctx, memoryLayerID, id, body) (*MemoryEntryDetail, error)
PATCH/v1/memory_layers/{memoryLayerId}/entries/{id}
Delete a memory entry
client.MemoryLayers.Entries.Delete(ctx, memoryLayerID, id) error
DELETE/v1/memory_layers/{memoryLayerId}/entries/{id}
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)

ID string

Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

AccountID string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

CreatedAt Time

Timestamp when this resource was created

formatdate-time
Name string

Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly

ProfileID string

ID of the actor (user or service account) that created this resource

WorkspaceID string

Workspace this resource belongs to for organizational grouping (prefixed ULID)

ExternalID stringoptional

External ID for the resource (e.g., a workflow ID from an external system)

Labels map[string, string]optional

Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"}

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.

Description stringoptional

One-line "when to use this" hint shown in the frontmatter manifest for skills entries. The model uses this to decide whether to load the body, so it should be written for the model as the audience. Ignored for layer types that do not advertise frontmatter.

Title stringoptional

Short human/LLM-readable title shown in the frontmatter manifest for skills entries. Ignored for layer types that do not advertise frontmatter.

Info MemoryEntryInfooptional
CreatedBy Profileoptional

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

AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

ID string

Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

AccountID string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

Name string

Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly

ProfileID string
ExternalID stringoptional

External ID for the resource (e.g., a workflow ID from an external system)

Labels map[string, string]optional

Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"}

Spec ProfileSpec

ProfileSpec contains the profile-specific fields

Type ProfileSpecType

Type is the type of profile. User's are humans, API keys are computers. You know the deal.

formatenum
One of the following:
const ProfileSpecTypeProfileTypeUser ProfileSpecType = "PROFILE_TYPE_USER"
const ProfileSpecTypeProfileTypeAPIKey ProfileSpecType = "PROFILE_TYPE_API_KEY"
const ProfileSpecTypeProfileTypeSystem ProfileSpecType = "PROFILE_TYPE_SYSTEM"
Email stringoptional

Email address of the user (required, unique per account)

Name stringoptional

Display name for the user (e.g., "Bobby Tables")

MemoryLayer ResourceMetadataoptional

Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

ID string

Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

AccountID string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

CreatedAt Time

Timestamp when this resource was created

formatdate-time
Name string

Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly

ProfileID string

ID of the actor (user or service account) that created this resource

WorkspaceID string

Workspace this resource belongs to for organizational grouping (prefixed ULID)

ExternalID stringoptional

External ID for the resource (e.g., a workflow ID from an external system)

Labels map[string, string]optional

Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"}

type MemoryEntryCreateSpec struct{…}

MemoryEntryCreateSpec is the input shape for CreateMemoryEntry. It accepts either inline content or a reference to a completed Upload; exactly one of the two must be set.

Key string

See MemoryEntrySpec.key for the full rule set. Same constraints apply here.

Content stringoptional

Inline content, written directly into the entry.

Description stringoptional
Title stringoptional
UploadID stringoptional

ID of a COMPLETE Upload. The server reads the object from storage, copies its bytes into the entry, and marks the upload consumed.

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

Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

ID string

Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

AccountID string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

CreatedAt Time

Timestamp when this resource was created

formatdate-time
Name string

Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly

ProfileID string

ID of the actor (user or service account) that created this resource

WorkspaceID string

Workspace this resource belongs to for organizational grouping (prefixed ULID)

ExternalID stringoptional

External ID for the resource (e.g., a workflow ID from an external system)

Labels map[string, string]optional

Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"}

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.

Description stringoptional

One-line "when to use this" hint shown in the frontmatter manifest for skills entries. The model uses this to decide whether to load the body, so it should be written for the model as the audience. Ignored for layer types that do not advertise frontmatter.

Title stringoptional

Short human/LLM-readable title shown in the frontmatter manifest for skills entries. Ignored for layer types that do not advertise frontmatter.

Info MemoryEntryInfooptional
CreatedBy Profileoptional

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

AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

ID string

Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

AccountID string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

Name string

Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly

ProfileID string
ExternalID stringoptional

External ID for the resource (e.g., a workflow ID from an external system)

Labels map[string, string]optional

Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"}

Spec ProfileSpec

ProfileSpec contains the profile-specific fields

Type ProfileSpecType

Type is the type of profile. User's are humans, API keys are computers. You know the deal.

formatenum
One of the following:
const ProfileSpecTypeProfileTypeUser ProfileSpecType = "PROFILE_TYPE_USER"
const ProfileSpecTypeProfileTypeAPIKey ProfileSpecType = "PROFILE_TYPE_API_KEY"
const ProfileSpecTypeProfileTypeSystem ProfileSpecType = "PROFILE_TYPE_SYSTEM"
Email stringoptional

Email address of the user (required, unique per account)

Name stringoptional

Display name for the user (e.g., "Bobby Tables")

MemoryLayer ResourceMetadataoptional

Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

ID string

Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

AccountID string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

CreatedAt Time

Timestamp when this resource was created

formatdate-time
Name string

Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly

ProfileID string

ID of the actor (user or service account) that created this resource

WorkspaceID string

Workspace this resource belongs to for organizational grouping (prefixed ULID)

ExternalID stringoptional

External ID for the resource (e.g., a workflow ID from an external system)

Labels map[string, string]optional

Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"}

type MemoryEntryInfo struct{…}
CreatedBy Profileoptional

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

AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

ID string

Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

AccountID string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

Name string

Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly

ProfileID string
ExternalID stringoptional

External ID for the resource (e.g., a workflow ID from an external system)

Labels map[string, string]optional

Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"}

Spec ProfileSpec

ProfileSpec contains the profile-specific fields

Type ProfileSpecType

Type is the type of profile. User's are humans, API keys are computers. You know the deal.

formatenum
One of the following:
const ProfileSpecTypeProfileTypeUser ProfileSpecType = "PROFILE_TYPE_USER"
const ProfileSpecTypeProfileTypeAPIKey ProfileSpecType = "PROFILE_TYPE_API_KEY"
const ProfileSpecTypeProfileTypeSystem ProfileSpecType = "PROFILE_TYPE_SYSTEM"
Email stringoptional

Email address of the user (required, unique per account)

Name stringoptional

Display name for the user (e.g., "Bobby Tables")

MemoryLayer ResourceMetadataoptional

Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

ID string

Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

AccountID string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

CreatedAt Time

Timestamp when this resource was created

formatdate-time
Name string

Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly

ProfileID string

ID of the actor (user or service account) that created this resource

WorkspaceID string

Workspace this resource belongs to for organizational grouping (prefixed ULID)

ExternalID stringoptional

External ID for the resource (e.g., a workflow ID from an external system)

Labels map[string, string]optional

Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"}

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.

Description stringoptional

One-line "when to use this" hint shown in the frontmatter manifest for skills entries. The model uses this to decide whether to load the body, so it should be written for the model as the audience. Ignored for layer types that do not advertise frontmatter.

Title stringoptional

Short human/LLM-readable title shown in the frontmatter manifest for skills entries. Ignored for layer types that do not advertise frontmatter.

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.

Content stringoptional
Description stringoptional
Key stringoptional
Title stringoptional
UploadID stringoptional