Memory Skills

Step 1: Configure the service endpoint and authentication

export MEMORY_BASE_URL="https://api-longmemory-cn-beijing.opentrust.net"
export MEMORY_API_KEY="<YOUR_API_KEY>"
export AGENT_ID="demo-report-agent-001"

Step 2: Write a procedural memory

A procedural memory should include the complete task objective, key steps, and execution results. Set memory_type to procedural_memory and provide a stable agent_id.

curl -sS -X POST "$MEMORY_BASE_URL/memories" \
  -H "Authorization: Token $MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "demo-report-agent-001",
    "memory_type": "procedural_memory",
    "messages": [
      {"role": "user", "content": "Task: Export a sales report for a specified month and region as CSV."},
      {"role": "assistant", "content": "Step 1: Open the report page and confirm that the monthly sales report is visible."},
      {"role": "assistant", "content": "Step 2: Select the monthly sales report and set the target month."},
      {"role": "assistant", "content": "Step 3: Set the region filter and wait for the report to refresh."},
      {"role": "assistant", "content": "Step 4: Select export as CSV and wait for the file download to complete."},
      {"role": "assistant", "content": "Step 5: Verify that the row count of the downloaded file matches the summary on the page. Task complete."}
    ]
  }'

The service processes writes asynchronously. The API first returns:

{
  "results": [
    {
      "message": "Memory processing has been queued for background execution",
      "status": "PENDING",
      "event_id": "<event_id>",
      "id": null
    }
  ]
}

PENDING indicates that the procedural memory has been queued for processing. The skill is generated after memory processing and quality checks are complete. Records with insufficient content or no clear steps may not generate a skill.

Step 3: View the generated skill

After a short wait, query the skill list for the agent:

curl -sS "$MEMORY_BASE_URL/skills?agent_id=$AGENT_ID&brief=true" \
  -H "Authorization: Token $MEMORY_API_KEY"

Sample response:

{
  "results": [
    {
      "id": "<skill_id>",
      "name": "export_report_to_file",
      "when_to_use": "Use when the user requests to download or export a specific report in a particular file format.",
      "version": 1
    }
  ]
}

brief=true returns a lightweight catalog that allows the agent to determine which skill to use. To retrieve the full content, replace <skill_id> with the ID returned by the list:

export SKILL_ID="<skill_id>"

curl -sS "$MEMORY_BASE_URL/skills/$SKILL_ID" \
  -H "Authorization: Token $MEMORY_API_KEY"

The following is a condensed version of a complete skill generated in an end-to-end test. The specific names and text may vary depending on the model and input:

{
  "id": "<skill_id>",
  "name": "export_report_to_file",
  "version": 1,
  "inputs": [
    {"name": "report_name", "desc": "The name of the report to select"},
    {"name": "report_parameters", "desc": "Filter conditions such as month and region"},
    {"name": "export_format", "desc": "The file format to export"}
  ],
  "outputs": [
    {"name": "downloaded_file", "desc": "The report file downloaded to the local machine"}
  ],
  "steps": [
    "Open the report page and confirm that the report list is visible",
    "Select the target report and set parameters such as month and region",
    "Wait for the report to refresh based on the filter conditions",
    "Select the export format and complete the file download",
    "Verify that the downloaded file matches the summary data on the page"
  ],
  "caveats": [
    "Do not start the export before the report has finished refreshing",
    "Verify file integrity after the download is complete"
  ]
}

Step 4: Retrieve the skill for a new task

When the agent receives a similar task, it can retrieve relevant skills directly by using the task description:

curl -sS -X POST "$MEMORY_BASE_URL/skills/search" \
  -H "Authorization: Token $MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Download a sales report and export it as a spreadsheet",
    "agent_id": "demo-report-agent-001",
    "top_k": 5,
    "smart_select": false
  }'

The following is a condensed response from an end-to-end test. The score varies with input, model, and data:

{
  "results": [
    {
      "id": "<skill_id>",
      "name": "export_report_to_file",
      "version": 1,
      "score": 0.6626
    }
  ],
  "selection": null
}

If you set smart_select: true, the system can also select the most relevant skill from the candidate results and provide a usage order. This mode is suitable for scenarios where a single task may require a combination of multiple skills.

Add new successful experience

When the same agent completes a similar task again, write the new execution process as a procedural_memory. The system determines whether the new experience belongs to an existing skill and updates the original skill when the new information is genuinely valuable.

For example, if a second execution adds "region filter" and "verify row count after export" steps, the same skill is updated from version 1 to version 2, and the source memories increase from 1 to 2.

Record failure experience

If an execution fails, add the following field when writing the memory:

"metadata": {
  "task_outcome": "failure"
}

For example, if the agent starts the export before the report has finished refreshing and the file is empty, the system can distill this failure cause into the pitfalls field of the skill to avoid the same issue in future executions.

View the full skill list

curl -sS "$MEMORY_BASE_URL/skills?agent_id=$AGENT_ID&brief=false" \
  -H "Authorization: Token $MEMORY_API_KEY"

Export skills

Export a single skill as Markdown:

curl -sS "$MEMORY_BASE_URL/skills/$SKILL_ID/export" \
  -H "Authorization: Token $MEMORY_API_KEY"

Export all skills for an agent:

curl -sS "$MEMORY_BASE_URL/skills/export?agent_id=$AGENT_ID" \
  -H "Authorization: Token $MEMORY_API_KEY" \
  -o skills.zip

Service Console WEBUI Operations

You can also view, search, and export Skills from the Data > Skills page in the console.