# Mandatory Context Fields for MemoryCore Data Operations: Complete API Reference

> Understand mandatory context fields for MemoryCore data operations. Discover required API parameters like session_id, messages, ratio, and more for efficient data handling.

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

---

**TLDR:** The MemoryCore API requires six mandatory context fields for all data operations—`session_id`, `messages`, `ratio`, `context_window`, `message_tokens`, and `instanceId`—plus the optional-but-critical `boundaryTimestamp` for context trimming, as strictly defined in [`MemoryCore/src/offload/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/types.ts).

The TencentDB-Agent-Memory repository provides a specialized memory management system for AI agents requiring large context window handling. When executing data operations such as offloading or updating agent memory, developers must supply specific mandatory context fields to ensure correct session association and token budgeting according to the core type definitions.

## Six Mandatory Fields in MemoryCore/src/offload/types.ts

According to the TypeScript interface definitions in [`MemoryCore/src/offload/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/types.ts) (lines 61-69), every MemoryCore data operation payload must contain these required fields:

- **session_id** (`string`): The unique identifier for the current agent session.
- **messages** (`Array<any>`): The complete list of message objects or task items comprising the operational context.
- **ratio** (`number`): The desired compression ratio applied when context exceeds the token window limit.
- **context_window** (`number`): The maximum token capacity for the model, typically defaulting to approximately 200,000 tokens.
- **message_tokens** (`number`): The calculated total token count of the supplied messages array.
- **instanceId** (`string`): The identifier for the specific memory-core instance handling the request.

### Service Authentication Mapping

The `instanceId` field corresponds to `auth.serviceId` in the authentication payload. As implemented in lines 145-147 of [`MemoryCore/src/offload/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/types.ts), the system maps your provided `instanceId` to the `serviceId` authentication field when forwarding requests to the core service instance.

## The Critical Optional Field: boundaryTimestamp

While the TypeScript interface marks `boundaryTimestamp` as optional, operational code in [`MemoryCore/src/offload_server/ingest-handler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/ingest-handler.ts) (lines 76-89) effectively requires this field for context trimming operations. This numeric timestamp establishes the precise cut-off point for recent context persistence during L1 execution, enabling accurate memory window management and historical data exclusion.

## Code Implementation Examples

### Request Payload Structure

When assembling data for off-load operations, your payload must match the core type definitions exactly:

```typescript
// Valid payload for MemoryCore data operations
const payload = {
  session_id: "sess_abc123xyz",                // mandatory
  messages: [{ role: "user", content: "..." }], // mandatory
  ratio: 0.85,                                 // mandatory
  context_window: 200000,                      // mandatory
  message_tokens: 35000,                       // mandatory
  instanceId: "memory-core-prod-01",            // mandatory (maps to auth.serviceId)
  boundaryTimestamp: Date.now()                // optional but required for trimming
};

```

### TypeScript Interface Definition

The source contract in [`MemoryCore/src/offload/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/types.ts) defines the structure:

```typescript
interface OffloadRequest {
  session_id: string;
  messages: any[];
  ratio: number;
  context_window: number;
  message_tokens: number;
  instanceId: string;
  boundaryTimestamp?: number;  // Optional in type, required for L1 execution
}

```

## Usage Patterns Across the Codebase

These mandatory context fields drive specific operations throughout the service:

- **[`MemoryCore/src/offload_server/ingest-handler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/ingest-handler.ts)** (lines 76-89): Assembles `messages` and `boundaryTimestamp` into the recent context for L1 execution persistence.
- **[`MemoryCore/src/offload/state-reporter.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/state-reporter.ts)**: Consumes `context_window` to generate accurate status reports on current memory utilization against limits.
- **[`MemoryCore/src/offload_server/offload-task-executor.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/offload-task-executor.ts)**: Retrieves and processes recent context files using the `session_id` and `instanceId` identifiers.

## Summary

- **Six strictly mandatory fields** (`session_id`, `messages`, `ratio`, `context_window`, `message_tokens`, `instanceId`) must appear in every MemoryCore data operation payload according to [`MemoryCore/src/offload/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/types.ts).
- **`instanceId` maps to `auth.serviceId`** during request forwarding to identify the handling service instance (lines 145-147).
- **`boundaryTimestamp`**, while technically optional in the interface, is operationally required for context trimming in [`ingest-handler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/ingest-handler.ts) (lines 76-89).
- Correct field inclusion ensures proper **session association**, **token budgeting**, and **compression ratio** application for large-context AI operations.

## Frequently Asked Questions

### What happens if I omit the ratio field in a MemoryCore request?

The service will reject the request or fail to compress context when limits are exceeded. As defined in [`MemoryCore/src/offload/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/types.ts), `ratio` is a mandatory number required for all off-load operations to determine compression aggressiveness when `message_tokens` exceeds `context_window`.

### How does instanceId relate to serviceId in the authentication payload?

The `instanceId` field in your request payload directly corresponds to `auth.serviceId` used during internal request forwarding. According to lines 145-147 in [`MemoryCore/src/offload/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload/types.ts), the system routes your request to the correct memory-core instance by mapping your provided `instanceId` to the authentication service identifier.

### Is boundaryTimestamp required for all MemoryCore data operations?

While technically optional in the TypeScript interface, `boundaryTimestamp` is mandatory for any operation involving recent context trimming. The implementation in [`MemoryCore/src/offload_server/ingest-handler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/offload_server/ingest-handler.ts) (lines 76-89) requires this timestamp to establish the cut-off point for L1 execution context persistence; omitting it will result in incomplete memory management.

### What is the default context_window value in MemoryCore?

The source code indicates `context_window` typically defaults to approximately 200,000 tokens, though you must explicitly provide this value in your payload as it is a mandatory field. Whether using the default or a custom limit, this field is required for the service to calculate compression needs and manage token budgets.