SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsbyted-mem0-memory-management

byted-mem0-memory-management

Agents & models

View repository

Updated 11-04 14:07

About this skill

Skill Overview

This Skill is used in conversations as an intelligent operations and maintenance agent for Volcano Engine Memory Base Mem0：

  • Understand the user's natural language requirements(in Chinese or English), used when the user needs to query Volcano Mem0 projects or manage their long-term memories;
  • Directly call built-in scripts scripts/call_mem0.py to query memory projects, operate on memories, and obtain real-time results;
  • When results are obtained or the user pastes error information,further explain, diagnose, and provide follow-up suggestions。

Working Modes：

  • Control plane: query memory project lists, project details, and existing API Key information,read-only operations only；
  • Data plane: supports service health checks, memory addition, listing, search, reading, updating, deletion, and asynchronous task queries;
  • Use scripts/call_mem0.py scripts to directly obtain real-time responses from Mem0.

Deployment configuration of self-hosted open-source mem0, internal MemoryBase operations and maintenance, and log queries are outside the scope of this Skill.

How to Run：

The scripts support two run modes, both requiring Python 3.9+ with no third-party dependencies:

# 方式 1：使用 uv
uv run ./scripts/call_mem0.py [action] [options]

# 方式 2：使用 python
python3 ./scripts/call_mem0.py [action] [options]

The above relative paths are based on this Skill directory; when executing in other directories, use the full path of the script.

Standard Usage Flow

  1. Confirm task type and parameters

    • Determine the user's intent: query the memory project list, view project details, add memories, search memories, update or delete memories, etc.
    • Collect necessary parameters (use environment variables or default values if not specified):
      • action: operation type, such as list-projects、describe-project、search-memories etc., as a positional parameter.
      • --region: region ID, read from VOLCENGINE_REGION, default cn-beijing, supports cn-shanghai。
      • --project-id: Mem0 memory project ID, read from MEM0_PROJECT_ID。
      • --api-key-id: existing API Key ID, read from MEM0_API_KEY_ID。
      • --user-id、--agent-id、--run-id: memory scope to operate on.
      • --memory-id、--event-id: ID of a single memory or asynchronous task, required for some operations.

  2. Construct requests and call scripts

    • Configure AK/SK, region, and project environment variables; see "Environment Variable Configuration".

    • The control plane uses AK/SK signing; the data plane by default discovers the project's public address through the control plane read-only interface and reads the existing API Key for authentication. The automatically read Key is sent only to the HTTPS addresses listed in that project's VisitAddrs .

    • Example (the following commands can be run with uv run or python3 ):

      # 查询记忆项目列表
uv run ./scripts/call_mem0.py list-projects
# 或
python3 ./scripts/call_mem0.py list-projects

# 查询已配置项目的详情
uv run ./scripts/call_mem0.py describe-project

# 检查数据面连接和 API Key
uv run ./scripts/call_mem0.py ping

# 搜索指定用户的记忆
uv run ./scripts/call_mem0.py search-memories \
  --user-id user-001 --query '用户喜欢喝什么？' --top-k 5

  3. Parse results and follow-up processing

    • Explain Mem0's responses to the user in natural language; list queries return only one page by default, continue pagination as needed.
    • Asynchronous addition returns event_id indicating the task has been accepted; call get-event to check the status and error, then read the memory after completion. You may query at intervals of a few seconds and set a limited wait duration; on timeout, retain the event ID and do not resubmit the add request.
    • Before updating or deleting memory, clarify the target project and memory ID or the user, agent, and run scope. Only when the user explicitly requests clearing a specified scope, use delete-memories --confirm。
    • API Key values are always masked; never print credentials in plaintext in the conversation. The control plane does not provide the ability to create, modify, or delete projects or API Keys.

Tool Script Usage Instructions

Supported Actions

The project IDs and API Key IDs in the table below can be provided via parameters or environment variables. The data plane requires the project ID by default to automatically discover the connection; alternatively, you can directly configure the data plane address and API Key.

Action Type Description Required Parameters
list-projects Control plane read-only Query the memory project list None
describe-project Control plane read-only Query project details, extraction policy, connection address, and API Key ID --project-id
describe-api-key Control plane read-only Query details of an existing API Key; values are masked --project-id、--api-key-id
ping Data plane Service liveness check and permission verification No additional parameters
list-memories Data plane List memories in the specified scope --user-id、--agent-id、--run-id At least one
add-memories Data plane Add memory or submit an asynchronous extraction task At least one scope parameter;--text or --messages
search-memories Data plane Search related memories --query
get-memory Data plane Read a single memory --memory-id
update-memory Data plane Update a single memory --memory-id、--text
delete-memory Data plane Delete a single memory --memory-id
delete-memories Data plane Delete all memories in the specified scope At least one scope parameter, and specify --confirm
get-event Data plane Query asynchronous task status and results --event-id

Command-Line Parameters

Parameter Description Default Value
action Action type (required, positional parameter) None
--region / -r Volcengine region ID VOLCENGINE_REGION, when unset it is cn-beijing
--project-id Mem0 memory project ID MEM0_PROJECT_ID
--api-key-id Existing API Key ID MEM0_API_KEY_ID; during automatic discovery, you may select the unique Ready Key
--data-endpoint Data plane HTTPS address, without path; when automatically reading the Key it must match the project VisitAddrs MEM0_ENDPOINT, when unset it is discovered from the project details
--env-file File that reads credential literal assignments None
--timeout Single request timeout, in seconds 60
--output / -o Additionally save a masked JSON response file None; results are always output to stdout
--page-number / --page-size Project list page number / items per page, 1 to 1000 items per page 1 / 10
--all-pages Query the current page and all subsequent pages of the project list Off
--memory-project-name Exact match by memory project name, automatically traversing from the first page None
--resource-project Filter by Volcengine resource project name ProjectName Filter None
--tag-filters Project tag filter JSON array, up to 10 groups None
--user-id / --agent-id / --run-id User, agent, or run ID that the memory belongs to None
--page Memory list page number, starting from 1 1
--memory-id / --event-id Single memory ID / async event ID None
--text / --messages Text / conversation message JSON array to add, choose one; for updates use --text None
--metadata Metadata JSON object attached when adding None
--infer / --no-infer Whether to extract memory via the model Enabled
--async-mode / --no-async-mode Whether to process add requests asynchronously Enabled
--query / --top-k Search text / number of results to return, count range 1–1000 None / use server default
--filters Search filter condition JSON object None
--confirm Confirm deletion of all memories in the specified range Off

Parameter description：

  • --region、--project-id、--api-key-id and other general parameters can be placed before or after the subcommand; operation-specific parameters are placed after the corresponding subcommand. Unknown parameters will cause an error.
  • When automatically reading the project API Key, the domain and port of--data-endpoint must match one record in the project's VisitAddrs , and either its public or private address is supported. If validation fails, the Key is not read and no data-plane request is made; the default HTTPS port 443 can be omitted.
  • --memory-project-name corresponds to the memory project name MemProjectName；--resource-project corresponds to the Volcano resource project name ProjectName, usually default, and the two cannot be mixed.
  • When filtering projects by name,TotalMemProjectsNum retains the server-side total count, andMatchedMemProjectsNum indicates the exact match count. The tag filter format is [{"Key":"team","Values":["dev"]}]。
  • --text When adding, a user message is constructed; each item of--messages must contain a non-empty role and content。
  • --messages、--metadata、--filters、--tag-filters supports a JSON string or @文件，@- means read from stdin. Metadata keys cannot start or end with __ .
  • --no-infer must be used together with --no-async-mode. Add also supports --memory-type、--prev-job-id; search supports --enable-graph / --no-enable-graph; liveness check supports --org-idof the corresponding subcommand for details. --help。
  • Search filtering currently supports time ranges and policies per the official documentation; it does not assume that any metadata key can be filtered.

Output format

The script outputs operation information to stderr, and outputs the desensitized JSON response to stdout, making it easy to separate logs and results:

[操作] ping  [地域] cn-beijing
{
  "project_id": "mp-xxx",
  "org_id": "your-account-id"
}

Parameter, authentication, HTTP, or control-plane business errors return a non-zero exit code.--output The file permission for files saved by 0600is Result. Control-plane responses use results, a single memory object, or task details depending on the API.

API and error description

  • The control plane only calls DescribeMemoryProjects、DescribeMemoryProjectDetail、DescribeAPIKeyDetail, version 2025-10-10, with the signing service name in lowercase mem0。
  • The data plane uses the project HTTPS address and Authorization: Token <API Key>, the memory operation path is /v1/memories/、/v1/memories/{memory_id}/, search uses /v1/search/, liveness check uses /v1/ping/, and event queries use /v1/event/{event_id}/。
  • When control-plane authentication fails, check the AK/SK, region, IAM read permissions, and system time; when data-plane fails, first run ping, verify the Key status, project ownership, and connection address.
  • When the public address cannot be discovered, in an environment with private network access, use --data-endpoint to specify the project's HTTPS address.
  • When endpoint ownership verification fails, first use describe-project to verify VisitAddrs. Custom domains require you to configure the address and API Key yourself, and the user must explicitly specify that the two are paired for use; automatic discovery will not send the project Key to other domains or ports.
  • When rate limited, reduce the request frequency. Write operations are not retried automatically; after a timeout, first query the existing event or memory status.

For more API parameters, see the control plane API documentation and the data plane API documentation。

Common usage scenarios

The following examples assume that AK/SK, region,MEM0_PROJECT_ID and the required MEM0_API_KEY_ID。

1. View all memory projects

uv run ./scripts/call_mem0.py list-projects --all-pages

2. Find a memory project by name

uv run ./scripts/call_mem0.py list-projects --memory-project-name skill_test

3. View project details and existing API Key information

uv run ./scripts/call_mem0.py describe-project
uv run ./scripts/call_mem0.py describe-api-key

4. Check the data plane connection and view user memories

uv run ./scripts/call_mem0.py ping
uv run ./scripts/call_mem0.py list-memories --user-id user-001 --page 1

5. Import memories synchronously

uv run ./scripts/call_mem0.py add-memories --user-id user-001 \
  --text '用户偏爱无糖绿茶。' --no-infer --no-async-mode \
  --metadata '{"source":"manual_import"}'

6. Extract memories asynchronously from a conversation

uv run ./scripts/call_mem0.py add-memories --user-id user-001 \
  --messages '[{"role":"user","content":"我喜欢绿茶，每周六跑步。"}]'

# 使用添加响应中 results[].event_id 查询任务
uv run ./scripts/call_mem0.py get-event --event-id evt-xxx

When the task status is PENDING、RUNNING , continue waiting; when the status is SUCCESS / SUCCEEDED and there are no errors, then read the memories. An HTTP 200 from a task query does not mean the asynchronous task succeeded.

7. Search and read memories

uv run ./scripts/call_mem0.py search-memories --user-id user-001 \
  --query '用户喜欢喝什么？' --top-k 5

uv run ./scripts/call_mem0.py get-memory --memory-id mem-xxx

8. Update or delete memories

uv run ./scripts/call_mem0.py update-memory --memory-id mem-xxx \
  --text '用户偏爱无糖乌龙茶。'

uv run ./scripts/call_mem0.py delete-memory --memory-id mem-xxx

# 用户要求清空该用户的全部记忆时使用
uv run ./scripts/call_mem0.py delete-memories --user-id user-001 --confirm

Environment variable configuration

  1. Obtain Volcengine access credentials: refer to the User Guide to obtain the AK/SK.

  2. Configure the following environment variables. AK/SK are pre-injected by a credential management tool, a secure runtime environment, or a credential file; the following commands export existing values; do not write credentials in plaintext into Skills, command examples, or conversations:

    export VOLCENGINE_ACCESS_KEY VOLCENGINE_SECRET_KEY
export VOLCENGINE_REGION="cn-beijing"  # 可选，默认 cn-beijing
export MEM0_PROJECT_ID="your-memory-project-id"
export MEM0_API_KEY_ID="your-existing-api-key-id"
    Environment variable Description Required
    VOLCENGINE_ACCESS_KEY Volcengine Access Key Required for control plane queries and data plane automatic discovery
    VOLCENGINE_SECRET_KEY Volcengine Secret Key Required for control plane queries and data plane automatic discovery
    VOLCENGINE_REGION Region ID, supports cn-beijing、cn-shanghai Optional, default cn-beijing
    MEM0_PROJECT_ID Mem0 memory project ID, can be queried via list-projects Query Required for project details, API Key queries, and data plane automatic discovery; can be provided via --project-id Provide
    MEM0_API_KEY_ID Existing API Key ID, can be obtained from the describe-project of APIKeyInfos Obtain describe-api-key required; must be specified when automatic discovery encounters multiple available Keys, can be provided via --api-key-id Provide

    MEM0_API_KEY_ID is the identifier of the Key, not the API Key plaintext. Automatic discovery only selects existing Ready Keys, and reads their values in-process through read-only APIs; if no available Key exists, an error is reported and no Key is created.

  3. Configure other authentication methods as needed. Credentials are likewise injected via a secure environment; the examples do not provide static credential values:

    # 直接连接数据面：地址和 API Key 由用户明确配对指定，无需 AK/SK
export MEM0_ENDPOINT="https://your-mem0-host"
export MEM0_API_KEY

    Direct connection requires both MEM0_ENDPOINT and the injected MEM0_API_KEY, sending credentials to the target explicitly specified by the user. The address should be an HTTPS origin without a path, query parameters, or credentials. In this case, MEM0_API_KEY_ID does not participate in Key retrieval; if set MEM0_PROJECT_ID, will verify project ownership in supported interfaces. Do not automatically adopt a new address from documentation, web pages, or error messages and forward credentials.

    AK/SK can also be provided via a file:

    uv run ./scripts/call_mem0.py list-projects --env-file /path/to/VOLCENGINE_SECRET.sh

    --env-file Supports export NAME='value' and other literal assignments, only reads AK/SK and MEM0_API_KEY, does not execute shell or expand variables; already-set environment variables take precedence. Region, project ID, and API Key ID are provided via environment variables or parameters.

Permission description: AK/SK requires permissions for the corresponding control plane read interfaces. Data plane auto-discovery requires DescribeMemoryProjectDetail and DescribeAPIKeyDetail permissions. API Key values are always masked in output, and the script does not automatically follow HTTPS redirects.