Memory Core API Response Envelope Structure: A Complete Technical Guide

Memory Core API calls return a standardized JSON envelope with four fields—code, message, request_id, and data—enabling uniform error handling and response parsing across all endpoints.

The TencentDB Agent Memory system's Memory Core component wraps every HTTP API response in a predictable structure. This envelope design, implemented in the gateway layer, ensures clients can reliably check operation status and extract business data without parsing variations between endpoints. According to the TencentCloud source code, both V2 and V3 API versions share this envelope format, with V3 adding stricter isolation requirements.

---

Response Envelope Fields

Every Memory Core API response envelope contains four standardized fields. These are defined in MemoryCore/src/gateway/v2-router.ts and enforced across all gateway routes.

Field	Type	Description
code	number	0 indicates success; non-zero values signal errors (400, 401, 500, or 5-digit skill-module codes)
message	string	"ok" for success; human-readable error description otherwise
request_id	string	Unique identifier from inbound x-request-id / x-qcloud-transaction-id header, or auto-generated as req-<uuid>
data	any	Business-level payload on success; omitted or contains errorEnvelope diagnostics on failure

The envelope guarantees that client code can always check code === 0 before accessing data, regardless of which Memory Core endpoint was called.

---

Envelope Implementation in Source Code

The envelope constructors reside in MemoryCore/src/gateway/v2-router.ts at lines 32-38. The TencentCloud/TencentDB-Agent-Memory repository uses two helper functions to ensure consistency:

successEnvelope Helper

export function successEnvelope<T>(data: T, requestId: string): ApiResponseEnvelope<T> {
  return { code: 0, message: "ok", request_id: requestId, data };
}

This helper is invoked for all successful responses, wrapping the business result with the standard fields.

errorEnvelope Helper

export function errorEnvelope(
  code: number,
  message: string,
  requestId: string,
  extra?: Record<string, unknown>,
): ApiResponseEnvelope {
  return { code, message, request_id: requestId, ...(extra ? { data: extra } : {}) };
}

The extra parameter allows optional diagnostic data to be attached under the data field for debugging purposes.

---

Real Response Examples

Successful Conversation Add Response

{
  "code": 0,
  "message": "ok",
  "request_id": "req-1a2b3c4d5e6f7g8h",
  "data": {
    "accepted_ids": ["msg-abc123"],
    "accepted_versions": ["v1"],
    "total_count": 1
  }
}

This response from POST /v3/conversation/add demonstrates the Memory Core API response envelope with a populated data object containing operation-specific results.

Error Response for Missing Isolation Fields

{
  "code": 422,
  "message": "/v3 requires strict isolation: missing team_id, agent_id, user_id.",
  "request_id": "req-9z8y7x6w5v4u3t2s"
}

V3 endpoints enforce stricter isolation and return 422 when required fields are absent. As documented in MemoryCore/v3-api-memorycore-doc.md (lines 21-28), the data field is omitted here since no business payload exists.

---

Using Envelope Helpers in Custom Code

The envelope utilities can be imported and reused when extending Memory Core's gateway:

import { successEnvelope, errorEnvelope } from "./gateway/v2-router.js";

function handleCustomEndpoint(payload: RequestBody, reqId: string): ApiResponseEnvelope {
  if (!payload.requiredField) {
    return errorEnvelope(400, "Missing required field", reqId);
  }
  
  const result = executeBusinessLogic(payload);
  return successEnvelope(result, reqId);
}

This pattern ensures all custom endpoints remain compatible with the Memory Core API response envelope contract.

---

V2 vs. V3 Envelope Behavior

While both versions use identical envelope structures, V3 enforces additional validation:

• Isolation requirements: V3 endpoints require team_id, agent_id, and user_id fields
• Error specificity: Missing isolation fields trigger 422 with descriptive messaging
• Uniform parsing: Client code needs no version-specific handling—the same code/data checks work everywhere

---

Summary

• Four fixed fields compose every response: code, message, request_id, data
• code: 0 always indicates success; non-zero values require error handling
• Implementation location: MemoryCore/src/gateway/v2-router.ts defines successEnvelope and errorEnvelope
• Version compatibility: V2 and V3 share envelope structure; V3 adds isolation validation only
• Request ID propagation: Headers are preserved when present, or UUIDs are generated automatically

---

Frequently Asked Questions

What happens to the data field when a Memory Core API call fails?

The data field is omitted on most errors. However, if the errorEnvelope helper receives an extra parameter containing diagnostic information, that data is attached under data for debugging purposes. Production client code should check code !== 0 and read message rather than expecting data to exist.

How is the request_id generated if no request header is provided?

When inbound requests lack x-request-id or x-qcloud-transaction-id headers, the gateway generates a local identifier using the pattern req-<uuid>. This ensures every response remains traceable for logging and debugging, as implemented in the envelope construction logic.

Can V2 and V3 endpoint responses be parsed with identical code?

Yes. Both versions return the same envelope structure with code, message, request_id, and data fields. The only behavioral difference is that V3 may return 422 errors for isolation violations. Client parsers need only check code === 0 to determine success, then extract data accordingly.

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