# How Context Window Budgeting Works in TencentDB Agent Memory: Item Count, Character Budget, and Timeout Limits

> Learn how TencentDB Agent Memory uses item count, character budget, and timeout limits to manage context window budgeting and prevent prompt overflow and request stalls.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: deep-dive
- Published: 2026-08-31

---

**Context window budgeting in TencentDB Agent Memory uses three independent constraints—item count (`max_items`/`topK`), character budget (`char_budget`), and configurable HTTP timeouts—to prevent prompt overflow and request stalls.**

The TencentDB Agent Memory system implements a multi-layered defense against context window overflow. When assembling prompts for large language models, the system applies **hard limits at retrieval, rendering, and network layers**, ensuring no single request can exceed safe operational boundaries. This article examines the implementation based on the `TencentCloud/TencentDB-Agent-Memory` source code.

## Item-Count Budget: Limiting Retrieved Objects with `max_items` and `topK`

The first line of defense restricts how many items enter the pipeline. In [`MemoryCore/src/gateway/skill-handlers.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/skill-handlers.ts), the `handleListing` function determines the retrieval scope:

```ts
// MemoryCore/src/gateway/skill-handlers.ts
const topK = routing?.searchTopK ?? 20;               // default 20 items
...
if (!useSearch) {
  const r = await pre.core.list({
    user_id: pre.data.user_id,
    team_id: pre.data.team_id,
    agent_id: pre.data.agent_id,
    pagination: { limit: topK },                     // caps item count
  });
  items = r.items.map(...);
}

```

The **item-count budget** serves as a hard ceiling on database queries. Even without search filtering, the system never fetches more than `topK` records (default 20, configurable via `routing.searchTopK`).

The Python SDK enforces the same limit at the API boundary in [`client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/client.py):

```python

# MemoryCore/sdk/python/tencentdb_agent_memory/v3/client.py

max_items: int,
...
if len(deduped) > max_items:
    raise ParamError(f"{field} accepts at most {max_items} items, got {len(deduped)}")

```

This validation occurs before any data reaches the model, preventing unbounded record pulls that could exhaust token budgets downstream.

## Character Budget: Truncating Rendered Content with `char_budget`

After item selection, the system renders a textual block for prompt injection. The **character budget** (`char_budget`) constrains this rendered output regardless of how few items were retrieved.

In [`MemoryCore/src/gateway/skill-handlers.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/skill-handlers.ts), the handler builds an `<available_skills>` block and applies truncation:

```ts
// MemoryCore/src/gateway/skill-handlers.ts
const charBudget = pre.data.char_budget ?? 8000;      // default 8,000 chars
...
if (listing.length > charBudget) {
  const truncated = listing.slice(0, Math.max(0, charBudget - 32));
  listing = `${truncated}\n... [truncated]\n</available_skills>`;
}

```

The truncation preserves structural integrity by keeping the closing tag and adding a clear marker. The valid range is **0–64,000 characters**, with 8,000 as the conservative default.

Both SDKs expose `char_budget` directly:

- **TypeScript**: [`skill-client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/skill-client.ts) line 364 → `char_budget: params.char_budget`
- **Python**: [`skill_client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/skill_client.py) line 519 → `char_budget: Optional[int] = None`

This budget protects against verbose individual items—a scenario where 10 items might still overflow a token window if each contains lengthy documentation.

## Timeout Limits: Preventing Pipeline Stalls

The third constraint operates at the network layer. All SDK HTTP clients enforce **configurable request timeouts** (default 30 seconds) to prevent hung operations from blocking the entire pipeline.

TypeScript implementation in [`memory-core/typescript/src/v3/http.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/memory-core/typescript/src/v3/http.ts):

```ts
// memory-core/typescript/src/v3/http.ts
const timeout = opts.timeout ?? 30_000;
if (!Number.isFinite(timeout) || timeout <= 0) {
  throw new ParamError("timeout must be a positive number");
}
...
const timer = setTimeout(() => controller.abort(), this.timeout);

```

Python equivalent in [`sdk/memory-core/python/tencentdb_agent_memory/_v3_http.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/python/tencentdb_agent_memory/_v3_http.py):

```python

# sdk/memory-core/python/tencentdb_agent_memory/_v3_http.py

self.client = client or httpx.Client(timeout=timeout, verify=verify)
...
timeout: float = 30,
...
if isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or timeout <= 0:
    raise ParamError("timeout must be a positive number")

```

Timeout violations raise catchable exceptions, enabling callers to implement retry logic or circuit breakers without process termination.

## Token Budget: Final Assembly Protection

During prompt assembly, a fourth safeguard operates at the token level. In [`MemoryCore/src/offload/index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/index.ts), the `assemble` function calculates a **token budget** from model capacity and caller preferences:

```ts
// MemoryCore/src/offload/index.ts
const contextWindow = this._getContextWindow();
const budget = params.tokenBudget ? Math.min(params.tokenBudget, contextWindow) : contextWindow;

```

Messages are trimmed or discarded until the total token count fits within `budget`. This low-level enforcement complements the higher-level **character budget** and **item-count** limits, catching any overflow that might slip through earlier stages.

## Practical Implementation: Configuring All Three Budgets

The following examples demonstrate complete budget configuration in both SDKs:

```python

# Python SDK – request a listing with custom budgets

from tencentdb_agent_memory.v3 import SkillClient

client = SkillClient(
    endpoint="https://api.example.com",
    api_key="YOUR_KEY",
    service_id="memorycore",
    timeout=15                     # 15-second HTTP timeout

)

response = client.listing(
    user_id="u123",
    team_id="t456",
    agent_id="a789",
    char_budget=5000,              # limit rendered block to 5,000 chars

    max_items=10,                  # retrieve at most 10 skills

)
print(response["listing"])

```

```ts
// TypeScript SDK – same request with explicit budgets
import { SkillClient } from "@tencentdb/memory-core";

const client = new SkillClient({
  endpoint: "https://api.example.com",
  apiKey: "YOUR_KEY",
  serviceId: "memorycore",
  timeout: 20_000,                 // 20 s request timeout
});

const { listing } = await client.listing({
  user_id: "u123",
  team_id: "t456",
  agent_id: "a789",
  char_budget: 5000,
  max_items: 10,
});
console.log(listing);

```

## Key Source File References

| Component | File | Key Element |
|-----------|------|-------------|
| Character budget schema | [`MemoryCore/src/gateway/skill-schemas.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/skill-schemas.ts) | `char_budget: z.number().int().min(0).max(64_000).optional()` |
| Listing handler logic | [`MemoryCore/src/gateway/skill-handlers.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/skill-handlers.ts) | `topK` pagination and `charBudget` truncation |
| Token budget assembly | [`MemoryCore/src/offload/index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/index.ts) | `budget = params.tokenBudget ? Math.min(...) : contextWindow` |
| TypeScript HTTP timeout | [`memory-core/typescript/src/v3/http.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/memory-core/typescript/src/v3/http.ts) | `AbortController` with configurable timer |
| Python HTTP timeout | [`sdk/memory-core/python/tencentdb_agent_memory/_v3_http.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/python/tencentdb_agent_memory/_v3_http.py) | `httpx.Client(timeout=timeout)` |
| Python `char_budget` field | [`sdk/memory-core/python/tencentdb_agent_memory/v3/skill_client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/python/tencentdb_agent_memory/v3/skill_client.py) | `char_budget: Optional[int] = None` |
| Python `max_items` validation | [`sdk/memory-core/python/tencentdb_agent_memory/v3/client.py`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/python/tencentdb_agent_memory/v3/client.py) | `ParamError` on `len(deduped) > max_items` |

## Summary

- **Item-count budget** (`max_items`/`topK`): Hard caps database retrieval at 20 items by default, configurable via routing or SDK parameters.
- **Character budget** (`char_budget`): Truncates rendered prompt blocks to 0–64,000 characters (default 8,000), preserving XML structure with clear markers.
- **Timeout limits**: Enforces 30-second HTTP request ceilings by default, abortable and configurable per client instance.
- **Token budget**: Final assembly-stage check against model context windows, trimming messages to fit available capacity.

These four mechanisms operate in sequence—first limiting what enters, then constraining how it's presented, then governing how long retrieval may take, and finally ensuring token-level compliance before model submission.

## Frequently Asked Questions

### What happens if `char_budget` is set to zero?

Setting `char_budget` to zero disables the character limit entirely for that field, allowing unbounded rendered output. However, the item-count budget and token-budget assembly still apply downstream protection. Use with caution—zero removes a critical safeguard against prompt overflow.

### Can `max_items` and `topK` conflict?

They represent the same concept at different layers. `topK` controls the database query limit in `handleListing`, while `max_items` validates SDK inputs. When both are specified, the smaller effective value governs. The SDK raises `ParamError` if the caller explicitly requests more than `max_items` allows.

### Does the timeout apply to the entire operation or just HTTP transport?

The configured timeout applies to individual HTTP requests within the SDK clients. Complex operations involving multiple requests (search + listing + assembly) may accumulate longer total durations. Implement application-level timeouts for end-to-end operation caps.

### How does `char_budget` differ from `tokenBudget`?

`char_budget` operates on characters in the rendered listing block before tokenization, providing fast approximate sizing. `tokenBudget` operates on actual token counts during final prompt assembly, using the model's specific tokenizer. Character budgets offer caller control; token budgets ensure hard model constraints.