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

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, the handleListing function determines the retrieval scope:

// 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:

# 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, the handler builds an <available_skills> block and applies truncation:

// 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 line 364 → char_budget: params.char_budget
• Python: 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:

// 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:

# 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, the assemble function calculates a token budget from model capacity and caller preferences:

// 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 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"])

// 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	char_budget: z.number().int().min(0).max(64_000).optional()
Listing handler logic	MemoryCore/src/gateway/skill-handlers.ts	topK pagination and charBudget truncation
Token budget assembly	MemoryCore/src/offload/index.ts	budget = params.tokenBudget ? Math.min(...) : contextWindow
TypeScript HTTP timeout	memory-core/typescript/src/v3/http.ts	AbortController with configurable timer
Python HTTP timeout	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	char_budget: Optional[int] = None
Python max_items validation	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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}