# Runtime Configuration Options for TencentDB Agent Memory: Complete Environment Variable Guide

> Explore runtime configuration options for TencentDB Agent Memory. This guide details environment variables for gateway limits, vector stores, COS storage, and security policies.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: api-reference
- Published: 2026-08-24

---

**TencentDB Agent Memory reads all runtime settings from environment variables centralized in [`MemoryCore/src/utils/env-config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/env-config.ts), eliminating scattered `process.env` calls while controlling gateway limits, vector store connections, COS storage, and security policies.**

TencentDB Agent Memory (TencentCloud/TencentDB-Agent-Memory) provides a modular architecture for database agent memory management. Understanding the **runtime configuration options for TencentDB Agent Memory** is essential for production deployments, as the service exposes all operational parameters through environment variables parsed in a single configuration module.

## Centralized Configuration Architecture

The project eliminates scattered `process.env` access by consolidating all environment variable parsing in [`MemoryCore/src/utils/env-config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/env-config.ts). This design satisfies internal security scanners while providing type-safe helper functions that expose settings to the rest of the application.

### Configuration Helper Functions

The following functions read and validate environment variables at runtime:

- `resolveMaxBodyBytes()` – Returns the effective request body size limit.
- `readVdbEnvConfig()` – Builds a connection object for the vector store backend.
- `readCosEnvConfig()` – Returns COS configuration or `null` when disabled.
- `readCosToolEnvConfig(fallback)` – Merges environment values with fallback defaults for the `tdai_read_cos` tool.
- `readApiTraceEnabled()` – Boolean flag controlling API trace logging.
- `resolveV3StrictIsolation()` – Boolean enforcing strict tenant isolation on data-plane endpoints.

## Gateway and Vector Store Configuration

The gateway and vector database settings control request handling limits and backend connectivity.

The `MEMORY_MAX_BODY_BYTES` variable defines the maximum allowed request body size through `resolveMaxBodyBytes()`, defaulting to 1 MiB (`DEFAULT_MAX_BODY_BYTES`). Vector store connection parameters use the `VDB_` prefix: `VDB_ENDPOINT` specifies the per-instance URL, `VDB_USER` defaults to `"root"`, `VDB_API_KEY` handles authentication, and `VDB_DATABASE` selects the target database (defaulting to `"default"`).

```typescript
// Example: initialise the vector store client using runtime config
import { readVdbEnvConfig } from '@/utils/env-config';
import { createVectorStore } from '@/db/client';

const vdb = readVdbEnvConfig();          // {url, user, apiKey, database}
const client = createVectorStore(vdb);   // client is now ready to use

```

## Cloud Object Storage (COS) Integration

COS integration supports both direct storage operations and the `tdai_read_cos` tool, controlled through nine environment variables. When `COS_SECRET_ID` is absent, COS functionality remains disabled (`null`).

**Core COS Variables:**
- `COS_SECRET_ID` – Enables COS when present; required for authentication.
- `COS_SECRET_KEY` – Optional secret key for permanent credentials.
- `COS_TOKEN` – Optional temporary session token.
- `COS_URL` – Endpoint URL for COS API requests.
- `COS_PATH_PREFIX` – Default prefix for object paths.

**Tool-Specific Variables:**
- `COS_BUCKET` – Target bucket name for `tdai_read_cos` operations.
- `COS_REGION` – Geographic region (defaults to `"ap-guangzhou"`).
- `COS_PREFIX` – Path prefix for the read tool (defaults to `"test_read_cos/"`).
- `COS_DOMAIN` – Optional custom domain override.

The `readCosEnvConfig()` function returns a `CosEnvConfig` object when enabled, while `readCosToolEnvConfig(fallback)` merges runtime values with fallback defaults.

## Observability and Security Controls

Two critical boolean flags control tracing verbosity and data isolation.

**API Tracing:**
The `TDAI_API_TRACE_ENABLED` variable defaults to `true`, enabling metadata API trace logs to stdout. Disable this in production to reduce noise using `readApiTraceEnabled()`.

```typescript
// Example: enable/disable API trace logging
import { readApiTraceEnabled } from '@/utils/env-config';

if (readApiTraceEnabled()) {
  console.log('Metadata API tracing is enabled');
}

```

**Request Isolation:**
The `V3_STRICT_ISOLATION` variable controls enforcement of strict team-agent-user triple validation on `/v3` data-plane endpoints. Defaulting to `false` for local development, production deployments should enable this to ensure multi-tenant isolation via `resolveV3StrictIsolation()`.

```typescript
// Example: enforce strict isolation on /v3 endpoints
import { resolveV3StrictIsolation } from '@/utils/env-config';
import { Router } from 'express';

const router = Router();

router.use('/v3', (req, res, next) => {
  if (resolveV3StrictIsolation() && !req.headers['x-team-id']) {
    return res.status(422).send('Missing isolation fields');
  }
  next();
});

```

## Knowledge Service Configuration

While [`env-config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/env-config.ts) handles core Memory settings, the Knowledge service maintains separate configuration in [`MemoryKnowledge/src/config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/config.ts). This module defines defaults for embedding models, OpenAI API keys, and token limits including `OPENAI_API_KEY`, `EMBEDDING_MODEL`, and `KNOWLEDGE_MAX_TOKENS`.

## Summary

- **TencentDB Agent Memory** centralizes all runtime configuration in [`MemoryCore/src/utils/env-config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/env-config.ts) to eliminate scattered environment variable access.
- **Gateway limits** and **vector store connectivity** are controlled via `MEMORY_MAX_BODY_BYTES` and `VDB_*` variables, accessed through `resolveMaxBodyBytes()` and `readVdbEnvConfig()`.
- **COS integration** uses nine distinct variables spanning authentication, endpoints, and tool-specific paths, parsed by `readCosEnvConfig()` and `readCosToolEnvConfig()`.
- **Security and observability** rely on `TDAI_API_TRACE_ENABLED` and `V3_STRICT_ISOLATION`, which toggle API logging and strict tenant isolation via `readApiTraceEnabled()` and `resolveV3StrictIsolation()`.
- The **Knowledge service** maintains independent settings in [`MemoryKnowledge/src/config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/config.ts) for embedding and LLM configurations.

## Frequently Asked Questions

### How do I disable COS integration in TencentDB Agent Memory?

Set `COS_SECRET_ID` to an empty value or omit it entirely. The `readCosEnvConfig()` function returns `null` when this variable is absent, effectively disabling all COS functionality without raising errors.

### What is the default request body size limit and how do I increase it?

The default limit is 1 MiB (1048576 bytes) defined by `DEFAULT_MAX_BODY_BYTES`. Override this by setting `MEMORY_MAX_BODY_BYTES` to your desired byte value; `resolveMaxBodyBytes()` will parse this as an integer at runtime.

### Where should I configure OpenAI API keys for the Knowledge service?

OpenAI keys and embedding model settings belong in [`MemoryKnowledge/src/config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/config.ts), not the main [`env-config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/env-config.ts) module. This separation allows the Knowledge service to maintain distinct provider credentials independent of the core Memory gateway configuration.

### Why does strict isolation default to false and when should I enable it?

`V3_STRICT_ISOLATION` defaults to `false` to support local development workflows where team headers may not be present. Enable this in production deployments by setting the variable to `true`, ensuring `resolveV3StrictIsolation()` enforces mandatory team-agent-user triple validation on all `/v3` endpoints.