Create a new memory layer

client.MemoryLayers.New(ctx, workspaceID, body) (*MemoryLayer, error)

POST/v1/workspaces/{workspaceId}/memory_layers

Creates a new memory layer in the workspace

ParametersExpand Collapse

workspaceID string

body MemoryLayerNewParams

Metadata param.Field[CreateResourceMetadata]

CreateResourceMetadata contains the user-provided fields for creating a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id, created_at) are excluded since they are set by the server.

Spec param.Field[MemoryLayerSpec]

ReturnsExpand 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)

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)

BundleKey stringOptional

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.

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 MemoryLayerSpec

Type MemoryLayerSpecType

formatenum

One of the following:

const MemoryLayerSpecTypeMemoryLayerTypeUnspecified MemoryLayerSpecType = "MEMORY_LAYER_TYPE_UNSPECIFIED"

const MemoryLayerSpecTypeMemoryLayerTypeEpisodic MemoryLayerSpecType = "MEMORY_LAYER_TYPE_EPISODIC"

const MemoryLayerSpecTypeMemoryLayerTypeSkills MemoryLayerSpecType = "MEMORY_LAYER_TYPE_SKILLS"

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.

formatdate-time

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.

Info MemoryLayerInfoOptional

CreatedBy ProfileOptional

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

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

Configuration for a profile.

Type ProfileSpecType

Whether this profile represents a human user, an API key, or a system principal.

formatenum

One of the following:

const ProfileSpecTypeProfileTypeUnspecified ProfileSpecType = "PROFILE_TYPE_UNSPECIFIED"

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 profile. Required and unique within an account for user profiles.

Name stringOptional

Display name (e.g., “Bobby Tables”).

EntryCount int64Optional

Number of entries currently in this layer.

formatint32

LastUsedAt TimeOptional

Timestamp of the most recent objective that resolved against this layer. Useful for surfacing unused layers in the dashboard.

formatdate-time

Create a new memory layer

package main

import (
  "context"
  "fmt"

  "github.com/cadenya/cadenya-go"
  "github.com/cadenya/cadenya-go/option"
  "github.com/cadenya/cadenya-go/shared"
)

func main() {
  client := cadenya.NewClient(
    option.WithAPIKey("My API Key"),
  )
  memoryLayer, err := client.MemoryLayers.New(
    context.TODO(),
    "workspaceId",
    cadenya.MemoryLayerNewParams{
      Metadata: cadenya.F(shared.CreateResourceMetadataParam{
        Name: cadenya.F("name"),
      }),
      Spec: cadenya.F(cadenya.MemoryLayerSpecParam{
        Type: cadenya.F(cadenya.MemoryLayerSpecTypeMemoryLayerTypeUnspecified),
      }),
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", memoryLayer.Metadata)
}

{
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "bundleKey": "bundleKey",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "spec": {
    "type": "MEMORY_LAYER_TYPE_UNSPECIFIED",
    "description": "description",
    "expiresAt": "2019-12-27T18:11:19.117Z",
    "systemManaged": true
  },
  "info": {
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    },
    "entryCount": 0,
    "lastUsedAt": "2019-12-27T18:11:19.117Z"
  }
}

Returns Examples

{
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "bundleKey": "bundleKey",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "spec": {
    "type": "MEMORY_LAYER_TYPE_UNSPECIFIED",
    "description": "description",
    "expiresAt": "2019-12-27T18:11:19.117Z",
    "systemManaged": true
  },
  "info": {
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    },
    "entryCount": 0,
    "lastUsedAt": "2019-12-27T18:11:19.117Z"
  }
}