|
| 1 | +--- |
| 2 | +title: "TOS ContextBucket (tos_context)" |
| 3 | +--- |
| 4 | + |
| 5 | +The `tos_context` backend (`TosContextBucketLTMBackend`) uses the ContextBucket memory capability of Volcengine [TOS](https://www.volcengine.com/product/TOS) as long-term storage. It is a managed service: the server performs memory inference and retrieval, so no self-hosted vector store or local embedding is required. |
| 6 | + |
| 7 | +The backend maps `index` (or `app_name`) to a single **ContextBucket**, and maps the runtime `user_id` to a **ContextSet** under that bucket, so memories are naturally isolated per user. The corresponding ContextBucket and ContextSet are created automatically on first use (lazy ensure). |
| 8 | + |
| 9 | +## When to use |
| 10 | + |
| 11 | +- Production with persistence and managed operations; |
| 12 | +- When you want the ContextBucket memory capability of Volcengine TOS (server-side inference and retrieval); |
| 13 | +- When you want strong isolation by `user_id` (one ContextSet per user). |
| 14 | + |
| 15 | +## Requirements and installation |
| 16 | + |
| 17 | +The ContextBucket API is currently only available in a **pre-release (beta)** TOS SDK: `tos>=2.9.4b1`. VeADK's core dependency is the stable `tos>=2.8.4` (used by TOS object storage and Viking DB), so it does **not** install the beta for you. Before using `backend="tos_context"`, upgrade the TOS SDK explicitly: |
| 18 | + |
| 19 | +```bash |
| 20 | +pip install --upgrade "tos>=2.9.4b1" --pre |
| 21 | +``` |
| 22 | + |
| 23 | +<Callout type="warn"> |
| 24 | +pip / uv **ignore pre-releases by default**, so you must pass `--pre` (uv uses `--prerelease=allow`). Otherwise `2.9.4b1` won't be installed and you'll still hit the errors below at runtime. |
| 25 | +</Callout> |
| 26 | + |
| 27 | +## Common runtime errors and how to handle them |
| 28 | + |
| 29 | +`tos_context` is fail-closed: when a dependency or config requirement is not met, it **raises at initialization** rather than degrading silently or writing bad data. Common errors: |
| 30 | + |
| 31 | +| Error | Trigger | How to fix | |
| 32 | +| :--- | :--- | :--- | |
| 33 | +| `ImportError` | The `tos` SDK is not installed. | Install it: `pip install --upgrade "tos>=2.9.4b1" --pre`. | |
| 34 | +| `RuntimeError` | `tos` is installed but too old (e.g. `2.8.4`, or stable `2.9.2`); `TosClientV2` lacks the ContextBucket methods. | Upgrade to the pre-release: `pip install --upgrade "tos>=2.9.4b1" --pre`. The error message includes the installed version and this command. | |
| 35 | +| `ValueError` | `account_id` or `control_endpoint` is not configured. | Set the env vars `DATABASE_TOS_CONTEXT_ACCOUNT_ID` and `DATABASE_TOS_CONTEXT_CONTROL_ENDPOINT` (see the configuration table below). | |
| 36 | + |
| 37 | +<Callout type="info"> |
| 38 | +**Why a `RuntimeError` instead of an `ImportError` when `tos` is installed?** ContextBucket support was added as new methods on the existing `TosClientV2` class, so an older release still imports fine — it just lacks those methods. At initialization VeADK probes for the required methods (`hasattr`) to decide whether the installed SDK actually supports ContextBucket, turning a silent "imports but fails on call" problem into a clear, actionable error at startup. |
| 39 | +</Callout> |
| 40 | + |
| 41 | +## Configuration |
| 42 | + |
| 43 | +Authenticated via Volcengine AK/SK. Credentials are resolved in this order: explicit AK/SK **first** (env `VOLCENGINE_ACCESS_KEY` / `VOLCENGINE_SECRET_KEY`, with the STS token taken from `VOLCENGINE_SESSION_TOKEN`); **if both are not provided**, it falls back to the VeFaaS IAM credential file (`/var/run/secrets/iam/credential`) for the temporary AK/SK and STS token — the path used for keyless cloud deployments (VeFaaS / AgentKit). Other connection settings use the env prefix `DATABASE_TOS_CONTEXT_`; locally they can be placed under `database.tos_context.*` in `config.yaml` (flattened into the matching env vars). |
| 44 | + |
| 45 | +| Field | Env var | Default | Description | |
| 46 | +| :--- | :--- | :--- | :--- | |
| 47 | +| `volcengine_access_key` | `VOLCENGINE_ACCESS_KEY` | — | Volcengine Access Key (long-term or STS temporary AK). | |
| 48 | +| `volcengine_secret_key` | `VOLCENGINE_SECRET_KEY` | — | Volcengine Secret Key (long-term or STS temporary SK). | |
| 49 | +| `session_token` | `VOLCENGINE_SESSION_TOKEN` | — | STS security token for temporary credentials (optional; only needed with a temporary AK/SK). | |
| 50 | +| `account_id` | `DATABASE_TOS_CONTEXT_ACCOUNT_ID` | — | **Required**. Account ID for the ContextBucket control-plane APIs. | |
| 51 | +| `control_endpoint` | `DATABASE_TOS_CONTEXT_CONTROL_ENDPOINT` | — | **Required**. ContextBucket controller (control-plane) endpoint. | |
| 52 | +| `context_bucket_name` | `DATABASE_TOS_CONTEXT_BUCKET_NAME` | falls back to `index` | ContextBucket name. If unset, uses the `LongTermMemory` `index` (or `app_name`). | |
| 53 | +| `endpoint` | `DATABASE_TOS_CONTEXT_ENDPOINT` | `tos-cn-beijing.volces.com` | TOS data-plane endpoint. | |
| 54 | +| `region` | `DATABASE_TOS_CONTEXT_REGION` | `cn-beijing` | Region. | |
| 55 | + |
| 56 | +<Callout type="warn"> |
| 57 | +`account_id` and `control_endpoint` are required; a missing value raises `ValueError` at initialization (fail-closed — no silent degradation). |
| 58 | +</Callout> |
| 59 | + |
| 60 | +<Callout type="info"> |
| 61 | +The STS token reuses the global `VOLCENGINE_SESSION_TOKEN` convention (consistent with TOS object storage and other components); the standalone `DATABASE_TOS_CONTEXT_SECURITY_TOKEN` is no longer used. It is not needed when using long-term AK/SK. If `VOLCENGINE_ACCESS_KEY` / `VOLCENGINE_SECRET_KEY` are not both provided, the VeFaaS IAM credential file is read instead; a missing file raises `FileNotFoundError`. |
| 62 | +</Callout> |
| 63 | + |
| 64 | +## Usage |
| 65 | + |
| 66 | +```python |
| 67 | +from veadk import Agent |
| 68 | +from veadk.memory.long_term_memory import LongTermMemory |
| 69 | + |
| 70 | +# index maps to the ContextBucket name and must satisfy the bucket naming rules (see Callout below) |
| 71 | +ltm = LongTermMemory( |
| 72 | + backend="tos_context", |
| 73 | + index="demo-agent-memory", |
| 74 | + top_k=5, |
| 75 | +) |
| 76 | +agent = Agent( |
| 77 | + name="demo", |
| 78 | + long_term_memory=ltm, |
| 79 | + auto_save_session=True, # persist to long-term memory at session end |
| 80 | +) |
| 81 | +``` |
| 82 | + |
| 83 | +At init, if the ContextBucket doesn't exist, VeADK creates it; the first write/search for each `user_id` also creates the corresponding ContextSet if missing (enabling the `memory` scene). |
| 84 | + |
| 85 | +<Callout type="info"> |
| 86 | +`index` (the ContextBucket name) must follow TOS bucket naming rules: **length 3–63**, containing only **lowercase letters, digits, and hyphens (`-`)**, and not starting or ending with a hyphen. Use `DATABASE_TOS_CONTEXT_BUCKET_NAME` to override the bucket name derived from `app_name`/`index`. |
| 87 | +</Callout> |
| 88 | + |
| 89 | +<Callout type="info"> |
| 90 | +Memories are isolated by `user_id`: different `user_id`s write to different ContextSets, and retrieval only matches memories of the same `user_id`. Use a consistent `user_id` for cross-session recall. |
| 91 | +</Callout> |
0 commit comments