TOS ContextBucket

tos_context is a VeADK long-term memory backend that stores and retrieves memories with the ContextBucket capability of Volcengine TOS. Memory inference and retrieval run in the managed service, so you do not need to deploy a vector database or configure an embedding model. Each index maps to one ContextBucket. Within that bucket, every runtime user_id maps to an independent ContextSet. Use the same user_id across sessions when the application must recall a user’s existing memories.

When to use

You want a managed long-term memory service instead of operating a vector database;
You need to isolate memories by user_id;
You have a Volcengine account, ContextBucket service endpoints, and the required service permissions.

Prerequisites

VeADK 1.0.9 installed;
Your Volcengine account ID, the ContextBucket control endpoint, and the data endpoint for the target region;
AK/SK credentials that can access and create ContextBuckets and ContextSets and can write and search memories, or an IAM role with the same permissions for the AgentKit or VeFaaS runtime;
Network access to the configured control and data endpoints.

ContextBucket availability, control endpoints, and IAM permissions are provided by the TOS service and are separate from ordinary TOS Bucket permissions. If your account has not received ContextBucket enablement information, confirm the available regions, control endpoint, and least-privilege policy through your Volcengine service support channel before configuring this page.

Install the dependency

ContextBucket requires TOS SDK tos>=2.9.4b1. VeADK’s base dependencies also permit earlier TOS SDK releases, so upgrade the SDK separately in the VeADK environment:

python -m pip install --upgrade "tos>=2.9.4b1"

The version constraint explicitly includes the 2.9.4b1 pre-release, so pip does not require a separate --pre option. If your package manager or lockfile policy rejects pre-release dependencies, allow this dependency with the tool’s corresponding setting and regenerate the lockfile. Verify the installed version with:

python -c "from importlib.metadata import version; print(version('tos'))"

Configure credentials and endpoints

The following example supplies credentials through environment variables so that AK/SK values are not stored in code or configuration files:

export VOLCENGINE_ACCESS_KEY="your-access-key"
export VOLCENGINE_SECRET_KEY="your-secret-key"
export DATABASE_TOS_CONTEXT_ACCOUNT_ID="your-account-id"
export DATABASE_TOS_CONTEXT_CONTROL_ENDPOINT="your-control-endpoint"
export DATABASE_TOS_CONTEXT_ENDPOINT="tos-cn-beijing.volces.com"
export DATABASE_TOS_CONTEXT_REGION="cn-beijing"

Also set VOLCENGINE_SESSION_TOKEN when using temporary STS credentials. If AK and SK are not both provided, the backend uses the IAM role credentials of the AgentKit or VeFaaS runtime instead. Providing only AK or only SK does not form a valid credential pair.

The first initialization checks for and may create a ContextBucket. The first save or search for each user_id also checks for and may create a ContextSet. These operations create or access cloud resources and send session content to TOS. Before running the example, confirm that account permissions, costs, data processing, and retention policies meet your requirements.

Usage

The following example saves one session and then retrieves the same user’s long-term memory from a new session. Before running it, configure model credentials as described in Model configuration.

import asyncio

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

APP_NAME = "support-memory"
USER_ID = "user-42"


async def main() -> None:
    memory = LongTermMemory(
        backend="tos_context",
        index=APP_NAME,
        app_name=APP_NAME,
        top_k=5,
    )
    agent = Agent(
        name="support_agent",
        instruction=(
            "Before answering, use `load_memory` to retrieve long-term "
            "memories for the current user."
        ),
        long_term_memory=memory,
    )
    runner = Runner(agent=agent, app_name=APP_NAME, user_id=USER_ID)

    await runner.run(
        messages="Remember that I am allergic to peanuts.",
        session_id="session-1",
    )
    completed_session = await runner.session_service.get_session(
        app_name=APP_NAME,
        user_id=USER_ID,
        session_id="session-1",
    )
    await memory.add_session_to_memory(completed_session)

    response = await runner.run(
        messages="What food am I allergic to?",
        session_id="session-2",
    )
    print(response)


if __name__ == "__main__":
    asyncio.run(main())

After a successful run, the second session can retrieve the peanut allergy saved by the same user_id in the first session. If the ContextBucket named support-memory does not exist, initialization creates it. The first save also creates a memory-enabled ContextSet for user-42.

Pass backend configuration explicitly

In addition to environment variables, you can use backend_config for non-secret connection settings. The backend must ultimately receive a valid index; set it on the outer LongTermMemory object and VeADK fills it into the backend configuration.

from veadk.configs.database_configs import TOSContextBucketConfig
from veadk.memory.long_term_memory import LongTermMemory

memory = LongTermMemory(
    backend="tos_context",
    index="support-memory",
    backend_config={
        "account_id": "your-account-id",
        "tos_context_config": TOSContextBucketConfig(
            control_endpoint="your-control-endpoint",
            endpoint="tos-cn-beijing.volces.com",
            region="cn-beijing",
        ),
    },
)

Parameters

`LongTermMemory` parameters

Parameter	Type	Default	Description
`backend`	`str`	`"opensearch"`	Set to `"tos_context"` for this backend.
`index`	`str`	`""`	Default ContextBucket name. This backend requires a valid `index` or `app_name`; explicitly setting `index` is recommended.
`app_name`	`str`	`""`	Application name and the fallback value when `index` is not set.
`top_k`	`int`	`5`	Maximum number of memories returned by each search.
`backend_config`	`dict`	`{}`	Configuration passed to the selected backend. If the dictionary has no `index`, VeADK fills it from the outer `index` or `app_name`.

Backend configuration

Parameter	Type	Default	Description
`index`	`str`	Outer `index` or `app_name`	Required. Long-term memory isolation identifier and, when `context_bucket_name` is unset, the ContextBucket name. Normally set it on `LongTermMemory`.
`context_bucket_name`	`str \| None`	Reads `DATABASE_TOS_CONTEXT_BUCKET_NAME`, then uses `index`	ContextBucket name.
`account_id`	`str \| None`	Reads `DATABASE_TOS_CONTEXT_ACCOUNT_ID`	Required. Volcengine account ID that owns the ContextBucket.
`volcengine_access_key`	`str \| None`	Reads `VOLCENGINE_ACCESS_KEY`	Volcengine Access Key. It must be supplied with the Secret Key; otherwise the runtime IAM role is used.
`volcengine_secret_key`	`str \| None`	Reads `VOLCENGINE_SECRET_KEY`	Volcengine Secret Key. It must be supplied with the Access Key; otherwise the runtime IAM role is used.
`session_token`	`str`	Reads `VOLCENGINE_SESSION_TOKEN`, otherwise `""`	Session token required with temporary STS AK/SK credentials.
`tos_context_config`	`TOSContextBucketConfig`	The configuration class defaults	Control endpoint, data endpoint, and region settings.