Attach a memory layer to a variation

JavaScript

import Cadenya from '@cadenya/cadenya';

const client = new Cadenya({
  apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});

const variationMemoryLayerAssignment = await client.agents.variations.addMemoryLayer(
  'agent_01HXKD2E5NQM3T9AYWCFMGWT9Y',
  'agentvar_01HXKD2E5NQM3T9AYWCF32BSPP',
  {
    workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
    memoryLayerId: 'memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH',
  },
);

console.log(variationMemoryLayerAssignment.id);

import os
from cadenya import Cadenya

client = Cadenya(
    api_key=os.environ.get("CADENYA_API_KEY"),  # This is the default and can be omitted
)
variation_memory_layer_assignment = client.agents.variations.add_memory_layer(
    agent_id="agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
    variation_id="agentvar_01HXKD2E5NQM3T9AYWCF32BSPP",
    workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
    memory_layer_id="memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
)
print(variation_memory_layer_assignment.id)

package main

import (
	"context"
	"fmt"
	"go.cadenya.com/cadenya-go"
	"go.cadenya.com/cadenya-go/option"
)

func main() {
	client := cadenya.NewClient(
		option.WithAPIKey("My API Key"),
	)
	variationMemoryLayerAssignment, err := client.Agents.Variations.AddMemoryLayer(
		context.TODO(),
		"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
		"agentvar_01HXKD2E5NQM3T9AYWCF32BSPP",
		cadenya.AgentVariationAddMemoryLayerParams{
			WorkspaceID:   cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
			MemoryLayerID: "memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", variationMemoryLayerAssignment.ID)
}

require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

variation_memory_layer_assignment = cadenya.agents.variations.add_memory_layer(
  "agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
  "agentvar_01HXKD2E5NQM3T9AYWCF32BSPP",
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
  memory_layer_id: "memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH"
)

puts(variation_memory_layer_assignment)

cadenya agents:variations add-memory-layer \
  --api-key 'My API Key' \
  --workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
  --agent-id agent_01HXKD2E5NQM3T9AYWCFMGWT9Y \
  --variation-id agentvar_01HXKD2E5NQM3T9AYWCF32BSPP \
  --memory-layer-id memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH

curl --request POST \
  --url https://api.cadenya.com/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{variationId}/memory_layer_assignments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "memoryLayerId": "memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
  "position": 123
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{variationId}/memory_layer_assignments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'memoryLayerId' => 'memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH',
    'position' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://api.cadenya.com/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{variationId}/memory_layer_assignments")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"memoryLayerId\": \"memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH\",\n  \"position\": 123\n}")
  .asString();

{
  "id": "avml_01HXKD2E5NQM3T9AYWCFX8AF59",
  "memoryLayer": {
    "id": "<string>",
    "name": "<string>"
  },
  "position": 123
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "<string>"
    }
  ]
}

POST

workspaces

{workspaceId}

agents

{agentId}

variations

{variationId}

memory_layer_assignments

JavaScript

import Cadenya from '@cadenya/cadenya';

const client = new Cadenya({
  apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});

const variationMemoryLayerAssignment = await client.agents.variations.addMemoryLayer(
  'agent_01HXKD2E5NQM3T9AYWCFMGWT9Y',
  'agentvar_01HXKD2E5NQM3T9AYWCF32BSPP',
  {
    workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
    memoryLayerId: 'memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH',
  },
);

console.log(variationMemoryLayerAssignment.id);

import os
from cadenya import Cadenya

client = Cadenya(
    api_key=os.environ.get("CADENYA_API_KEY"),  # This is the default and can be omitted
)
variation_memory_layer_assignment = client.agents.variations.add_memory_layer(
    agent_id="agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
    variation_id="agentvar_01HXKD2E5NQM3T9AYWCF32BSPP",
    workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
    memory_layer_id="memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
)
print(variation_memory_layer_assignment.id)

package main

import (
	"context"
	"fmt"
	"go.cadenya.com/cadenya-go"
	"go.cadenya.com/cadenya-go/option"
)

func main() {
	client := cadenya.NewClient(
		option.WithAPIKey("My API Key"),
	)
	variationMemoryLayerAssignment, err := client.Agents.Variations.AddMemoryLayer(
		context.TODO(),
		"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
		"agentvar_01HXKD2E5NQM3T9AYWCF32BSPP",
		cadenya.AgentVariationAddMemoryLayerParams{
			WorkspaceID:   cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
			MemoryLayerID: "memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", variationMemoryLayerAssignment.ID)
}

require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

variation_memory_layer_assignment = cadenya.agents.variations.add_memory_layer(
  "agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
  "agentvar_01HXKD2E5NQM3T9AYWCF32BSPP",
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
  memory_layer_id: "memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH"
)

puts(variation_memory_layer_assignment)

cadenya agents:variations add-memory-layer \
  --api-key 'My API Key' \
  --workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
  --agent-id agent_01HXKD2E5NQM3T9AYWCFMGWT9Y \
  --variation-id agentvar_01HXKD2E5NQM3T9AYWCF32BSPP \
  --memory-layer-id memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH

curl --request POST \
  --url https://api.cadenya.com/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{variationId}/memory_layer_assignments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "memoryLayerId": "memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
  "position": 123
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{variationId}/memory_layer_assignments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'memoryLayerId' => 'memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH',
    'position' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://api.cadenya.com/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{variationId}/memory_layer_assignments")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"memoryLayerId\": \"memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH\",\n  \"position\": 123\n}")
  .asString();

{
  "id": "avml_01HXKD2E5NQM3T9AYWCFX8AF59",
  "memoryLayer": {
    "id": "<string>",
    "name": "<string>"
  },
  "position": 123
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "<string>"
    }
  ]
}

Wire a memory layer into one variation so every objective it runs can read the layer’s entries through get_memory.

const assignment = await client.agents.variations.addMemoryLayer(agentId, variationId, {
  workspaceId,
  memoryLayerId: 'external_id:support-knowledge',
  position: 0,
});

console.log(assignment.id);        // 'avml_...' the assignment row, not the layer
console.log(assignment.position);  // 0

assignment, err := client.Agents.Variations.AddMemoryLayer(ctx, agentID, variationID,
	cadenya.AgentVariationAddMemoryLayerParams{
		WorkspaceID:   cadenya.String(workspaceID),
		MemoryLayerID: "external_id:support-knowledge",
		Position:      cadenya.Int(0),
	})
if err != nil {
	log.Fatal(err)
}
log.Println(assignment.ID)       // avml_... the assignment row, not the layer
log.Println(assignment.Position) // 0

assignment = cadenya.agents.variations.add_memory_layer(
  agent_id,
  variation_id,
  workspace_id: workspace_id,
  memory_layer_id: "external_id:support-knowledge",
  position: 0
)

puts assignment.id       # avml_... the assignment row, not the layer
puts assignment.position # 0

curl -X POST "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/agents/${AGENT_ID}/variations/${VARIATION_ID}/memory_layer_assignments" \
  -H "Authorization: Bearer ${CADENYA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "memoryLayerId": "external_id:support-knowledge", "position": 0 }'

`position` is cascade order

position decides who wins when two layers hold the same key. Lower is more specific, and the lowest position that has the key resolves it, the same idea as the memory cascade as a whole. So a variation with a general company-policy layer at position: 10 and a team-specific one at position: 0 reads the team layer’s version of a shared key, and falls through to the general layer for keys only it has. The numbers are yours to space out; they need not be contiguous. 0 and 10 work as well as 0 and 1, which leaves room to slot a layer between them later without renumbering.

One layer, once

A layer can be attached to a variation only once. Attaching the same memoryLayerId again is a 409, even at a different position, so change the position on the existing assignment rather than adding a second. The response returns the assignment’s own avml_... id. Hold onto it, or read it back from the variation’s info.memoryLayerAssignments, since that is the id you pass to remove or reposition the layer. The assignment carries no external ID; it is a join record.

Memory layers

The cascade, and how position resolves a key.

Update the assignment

Move a layer to a new position.

Remove the assignment

Unwire the layer from the variation.

Add an assignment

The tool-set and sub-agent equivalent.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspaceId

string

required

Workspace ID.

Example:

"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"

agentId

string

required

Agent ID. Accepts the canonical agent_… form or the external_id:<value> form.

Example:

"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y"

variationId

string

required

Variation ID. Accepts the canonical agentvar_… form or the external_id:<value> form.

Example:

"agentvar_01HXKD2E5NQM3T9AYWCF32BSPP"

Body

application/json

Attach a memory layer to a variation. The request is rejected when:

the layer is system-managed (FailedPrecondition)
the layer is already assigned to this variation (AlreadyExists)
the variation is already at the 10-assignment cap (FailedPrecondition)
the position is already in use on this variation (InvalidArgument)

memoryLayerId

string

required

Layer to attach. Accepts the canonical memlyr_… form or the external_id:<value> form.

Example:

"memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH"

position

integer<int32>

Position in the baseline cascade (lower = more specific). If omitted, the server appends at the most general end (max existing position + 1).

Response

VariationMemoryLayerAssignment attaches a single MemoryLayer to a variation at a given position in the variation's baseline memory cascade. A variation has at most one assignment per memory_layer_id.

Variations only support whole-layer attachments — entry pinning is an objective-level capability.

string

read-only

Assignment row id — handle for removing the assignment. Distinct from the referenced memory layer's id.

Example:

"avml_01HXKD2E5NQM3T9AYWCFX8AF59"

memoryLayer

object

The attached memory layer.

Show child attributes

position

integer<int32>

Position in the variation's baseline cascade. Position is specificity, CSS-style: a LOWER position is more specific and is consulted first; the highest-position assignment is the most general fallback. Gaps are fine — only relative position matters. Positions must be unique within a variation; a request that would collide with an existing assignment's position is rejected with InvalidArgument.

​position is cascade order

​One layer, once

​Related

Memory layers

Update the assignment

Remove the assignment

Add an assignment

Authorizations

Path Parameters

Body

Response

`position` is cascade order

One layer, once

Related