Use VikingDB storage

The viking backend uses Volcengine VikingDB memory as long-term storage. It is a managed service requiring no self-hosted vector store or local embedding — recommended for production. This backend also supports user profiles (get_user_profile), the only backend that does. The earlier viking_mem backend is deprecated and is automatically mapped to viking; both have the same behavior.

When to use

Production with persistence and managed operations;
When you want Volcengine’s memory capabilities, including user profiles;
You have a Volcengine account with the corresponding AK/SK or IAM credentials.

Usage

from veadk import Agent
from veadk.memory.long_term_memory import LongTermMemory

# index (collection name) must start with a letter, contain only letters/digits/underscores, length 1–128
ltm = LongTermMemory(backend="viking", app_name="ltm_demo")

agent = Agent(
    name="demo",
    instruction="Answer the user; when needed, use the `load_memory` tool to recall past conversations.",
    long_term_memory=ltm,
)

At init, if the collection does not exist, VeADK creates it from memory_type. You can also pass config explicitly via backend_config:

from veadk.memory.long_term_memory import LongTermMemory

ltm = LongTermMemory(
    backend="viking",
    index="ltm_demo",
    backend_config={
        "index": "ltm_demo",
        "volcengine_access_key": "your-ak",
        "volcengine_secret_key": "your-sk",
        "region": "cn-beijing",
        "volcengine_project": "default",
        "memory_type": ["sys_event_v1", "sys_profile_v1"],
    },
)

Get a user profile

profile = ltm.get_user_profile(user_id="user-42")
print(profile)

Parameters

Constructor parameters

backend_config supports the following settings:

Parameter	Type	Default	Description
`index`	`str`	No default; provided by `LongTermMemory`	Memory collection name; must follow VikingDB naming rules.
`volcengine_access_key`	`str \| None`	See below	Access key (AK). Reads `BYTEPLUS_ACCESS_KEY` in `byteplus` mode, otherwise `VOLCENGINE_ACCESS_KEY`. Falls back to VeFaaS IAM when absent.
`volcengine_secret_key`	`str \| None`	See below	Secret key (SK). Reads `BYTEPLUS_SECRET_KEY` in `byteplus` mode, otherwise `VOLCENGINE_SECRET_KEY`. Falls back to VeFaaS IAM when absent.
`session_token`	`str`	See below	STS temporary-credential token. Reads `BYTEPLUS_SESSION_TOKEN` in `byteplus` mode, otherwise `VOLCENGINE_SESSION_TOKEN`.
`cloud_provider`	`str`	Reads env `CLOUD_PROVIDER`, defaults to `volces`	Cloud provider, `volces` or `byteplus`; affects the service host and region. In `byteplus` mode the region is fixed to `cn-hongkong`.
`region`	`str`	See below	Region of the VikingDB memory.
`volcengine_project`	`str`	Reads env `DATABASE_VIKINGMEM_PROJECT`, defaults to `default`	VikingDB memory project name.
`memory_type`	`list[str]`	See below	Memory type list, used to create the collection and filter retrieval.

Credential resolution order

The backend prefers volcengine_access_key and volcengine_secret_key from explicit arguments or environment variables. When both are missing, it reads credentials from the VeFaaS IAM file, suitable for Volcengine cloud deployments.

Defaults for region and memory_type

region: in byteplus mode it is always cn-hongkong, ignoring the env var and any explicitly passed value; in other modes, when not set explicitly it reads env DATABASE_VIKING_REGION and defaults to cn-beijing if still empty.
memory_type: when not set explicitly, reads env DATABASE_VIKINGMEM_MEMORY_TYPE (a comma-separated string is parsed into a list); when still empty, defaults to ["sys_event_v1", "sys_profile_v1"].

Environment variables

Env var	Default	Description
`VOLCENGINE_ACCESS_KEY`	None	Volcengine Access Key.
`VOLCENGINE_SECRET_KEY`	None	Volcengine Secret Key.
`CLOUD_PROVIDER`	`volces`	Cloud provider, `volces` or `byteplus`.
`DATABASE_VIKING_REGION`	`cn-beijing` (ignored in `byteplus` mode, which is fixed to `cn-hongkong`)	Memory region.
`DATABASE_VIKINGMEM_PROJECT`	`default`	Memory project name.
`DATABASE_VIKINGMEM_MEMORY_TYPE`	`sys_event_v1,sys_profile_v1`	Memory types, comma-separated.

export VOLCENGINE_ACCESS_KEY="your-ak"
export VOLCENGINE_SECRET_KEY="your-sk"
export CLOUD_PROVIDER="volces"
export DATABASE_VIKING_REGION="cn-beijing"
export DATABASE_VIKINGMEM_PROJECT="default"
export DATABASE_VIKINGMEM_MEMORY_TYPE="sys_event_v1,sys_profile_v1"

index (the collection name) must follow VikingDB rules: start with an English letter, contain only letters, digits, and underscores, length 1–128; otherwise initialization fails.

viking is the only backend that supports get_user_profile(user_id), returning the user’s profile information; other backends return an empty string for that method.

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

Deployment

When to use

Usage

Get a user profile

Parameters

Constructor parameters

Credential resolution order

Defaults for region and memory_type

Environment variables

​When to use

​Usage

​Get a user profile

​Parameters

​Constructor parameters

​Credential resolution order

​Defaults for region and memory_type

​Environment variables

When to use

Usage

Get a user profile

Parameters

Constructor parameters

Credential resolution order

Defaults for region and memory_type

Environment variables