Mandatory Context Fields for MemoryCore Data Operations: Complete API Reference

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.

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 (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, 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 (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:

// 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 defines the structure:

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 (lines 76-89): Assembles messages and boundaryTimestamp into the recent context for L1 execution persistence.
• 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: 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.
• 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 (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, 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, 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 (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.

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