/alibabacloud-agentloop-contextstore

name: alibabacloud-agentloop-contextstore
description: |
  Operate Alibaba Cloud CloudMonitor Service (CMS) AgentLoop ContextStore by using aliyun CLI with api version 2024-03-30. Use when users mention CloudMonitor, CMS, AgentLoop, agent loop, context, memory, experience, ContextStore, context store, 上下文库, 记忆库, 经验库, or ask to create/query/update/delete stores, write/search/update/delete context records, manage store API keys, or debug aliyun cms ContextStore commands.

AgentLoop ContextStore Skill

Scenario Description

This skill operates ContextStore resources under Alibaba Cloud CloudMonitor Service (CMS) AgentLoop. ContextStore persists long-running agent context in two store types:

• `memory`: user preferences, facts, episode summaries, and conversation-derived memories.
• `experience`: troubleshooting or task execution experience summarized from agent traces.

Architecture: `Aliyun CLI` + `CMS AgentLoop` + `ContextStore` + optional source `Log Service project/logstore` + store-level `API Key`.

Always confirm the target store `contextType` before data operations. Memory and experience stores share the same CLI product and subcommands, but their write schemas, filter field paths, and formatted outputs are different.

Installation

**Pre-check: Aliyun CLI >= 3.3.3 required** > Run `aliyun version` to verify >= 3.3.3. If not installed or version too low, run `curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash` to install/update, or see `references/cli-installation-guide.md` for installation instructions.

aliyun version

**Pre-check: Aliyun CLI plugin update required** > [MUST] run `aliyun configure set --auto-plugin-install true` to enable automatic plugin installation. > [MUST] run `aliyun plugin update` to ensure that any existing plugins are always up to date.

aliyun configure set --auto-plugin-install true
aliyun plugin update

**Pre-check: CMS plugin >= 0.2.4 required** > ContextStore subcommands and correct typed-value handling for `experience` / `metadata` / `config.metadataField` require the CMS plugin at version `0.2.4` or later. Earlier versions silently coerce nested numbers, booleans, arrays, and null values to strings. Verify and install if necessary: > > ```bash > aliyun plugin show --name cms > # If missing or older than 0.2.4: > aliyun plugin install --names cms --version 0.2.4 > # Or install the latest: > aliyun plugin install --names cms > ```

Environment Variables

No ContextStore-specific environment variables are required. Aliyun CLI credentials and region may come from a configured CLI profile, Alibaba Cloud environment variables, STS, OAuth, or an ECS RAM role.

Never read, echo, or print secret environment variable values. Use `aliyun configure list` only to check whether a valid profile or identity is available.

Authentication

> **Pre-check: Alibaba Cloud Credentials Required** > > **Security Rules:** > - **NEVER** read, echo, or print AK/SK values (e.g., `echo $ALIBABA_CLOUD_ACCESS_KEY_ID` is FORBIDDEN) > - **NEVER** ask the user to input AK/SK directly in the conversation or command line > - **NEVER** use `aliyun configure set` with literal credential values > - **ONLY** use `aliyun configure list` to check credential status > > ```bash > aliyun configure list > ``` > Check the output for a valid profile (AK, STS, or OAuth identity). > > **If no valid profile exists, STOP here.** > 1. Obtain credentials from [Alibaba Cloud Console](https://ram.console.aliyun.com/manage/ak) > 2. Configure credentials **outside of this session** (via `aliyun configure` in terminal or environment variables in shell profile) > 3. Return and re-run after `aliyun configure list` shows a valid profile

RAM Policy

ContextStore operations require CMS AgentLoop permissions for store, context, and API key APIs. See `references/ram-policies.md` for the full action list and a policy template.

> **[MUST] Permission Failure Handling:** When any command or API call fails due to permission errors at any point during execution, follow this process: > 1. Read `references/ram-policies.md` to get the full list of permissions required by this SKILL. > 2. If the `ram-permission-diagnose` skill is installed in the current environment, invoke it to guide the user through requesting the necessary permissions. Otherwise, surface the missing RAM action(s) plus the policy template from `references/ram-policies.md` and ask the user to attach the policy to the current RAM identity via the [Alibaba Cloud RAM Console](https://ram.console.aliyun.com/). > 3. Pause and wait until the user confirms that the required permissions have been granted before retrying.

Parameter Confirmation

> **IMPORTANT: Parameter Confirmation** -- Before executing any command or API call, > ALL user-customizable parameters (e.g., RegionId, instance names, CIDR blocks, > passwords, domain names, resource specifications, etc.) MUST be confirmed with the > user. Do NOT assume or use default values without explicit user approval.

| Parameter Name | Required/Optional | Description | Default Value | | --- | --- | --- | --- | | `--region` | Optional | Region override for the current CLI command. Confirm when the user does not want the configured default region. | CLI configured region | | `--workspace` | Required | AgentLoop workspace ID. | None | | `--context-store-name` | Required except `list-context-stores` | ContextStore name. | None | | `--context-type` | Required for create/write flows | Store type: `memory` or `experience`. | None | | `--memory-type` | Required for memory writes only | Memory write type: `short` or `long`. Never use for experience writes. | None | | `--context-id` | Required for single-record get/update/delete | Context record ID. | None | | `--items` | Required for `add-contexts` | JSON array of records to write. Schema depends on `contextType`. | None | | `--filter` | Optional | JSON filter for `search-context` or `delete-contexts`. Field paths