API Endpoints for Context Offloading and Querying in TencentDB Agent Memory

TencentDB Agent Memory exposes three REST endpoints under /v2/offload/—ingest for pushing context, query-mmd for retrieval, and compact for maintenance—each requiring Bearer authentication and returning JSON envelopes with unique request IDs.

The TencentCloud/TencentDB-Agent-Memory repository provides a scalable memory service for AI agents that stores contextual data outside the application process. Understanding the API endpoints for context offloading and querying is essential for implementing efficient session management and reducing memory pressure on your agents.

Core Offload API Endpoints

All offload operations route through MemoryCore/src/offload_server/router.ts, which registers handlers for the /v2/offload/ prefix. The implementation delegates to specific handlers while enforcing common validation and storage resolution logic.

POST /v2/offload/ingest

The ingest endpoint accepts payloads containing session texts, embeddings, and metadata for persistent storage. In MemoryCore/src/offload_server/router.ts (lines 56-64), the router forwards validated requests to handleIngest, which writes data to the configured backend.

curl -X POST https://<memory-host>/v2/offload/ingest \
  -H "Authorization: Bearer <your-service-token>" \
  -H "Content-Type: application/json" \
  -d '{
        "session_id": "sess-12345",
        "messages": [
          { "role": "user",   "content": "How do I reset my password?" },
          { "role": "assistant", "content": "You can reset it via the account settings." }
        ],
        "metadata": { "app": "my-app" }
      }'

// Node.js (fetch) – offload ingestion
const fetch = require('node-fetch');

async function ingestContext() {
  const resp = await fetch('https://<memory-host>/v2/offload/ingest', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer <your-service-token>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      session_id: 'sess-12345',
      messages: [
        { role: 'user', content: 'How do I reset my password?' },
        { role: 'assistant', content: 'You can reset it via the account settings.' }
      ],
      metadata: { app: 'my-app' }
    })
  });

  const result = await resp.json();
  console.log(result);
}
ingestContext();

POST /v2/offload/query-mmd

To retrieve offloaded context, clients call the query-mmd endpoint. The router validates incoming payloads against MmdQuerySchema defined in MemoryCore/src/offload_server/schemas.ts before invoking handleMmdQuery (router.ts lines 66-75). The request body must include a session_id and optionally accepts a limit parameter to control result set size.

curl -X POST https://<memory-host>/v2/offload/query-mmd \
  -H "Authorization: Bearer <your-service-token>" \
  -H "Content-Type: application/json" \
  -d '{
        "session_id": "sess-12345",
        "limit": 10
      }'

// Node.js (fetch) – query offloaded data
async function queryContext() {
  const resp = await fetch('https://<memory-host>/v2/offload/query-mmd', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer <your-service-token>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ session_id: 'sess-12345', limit: 10 })
  });

  const result = await resp.json();
  console.log(result);
}
queryContext();

POST /v2/offload/compact

The compact endpoint triggers maintenance operations on stored data to reclaim space and improve lookup performance. Handled by handleCompaction (router.ts lines 77-84), this endpoint is typically invoked by administrative processes rather than application code.

curl -X POST https://<memory-host>/v2/offload/compact \
  -H "Authorization: Bearer <your-service-token>"

Shared Request Processing Pipeline

All three endpoints share common middleware logic implemented in the router file.

Authentication via parseV2Auth

Every request passes through parseV2Auth, which extracts the service identifier from request headers. Missing or invalid credentials immediately return HTTP 401, preventing unauthorized access to stored context.

Storage Adapter Resolution

The router obtains a StorageAdapter instance via deps.resolveStorage (using the authenticated service ID) or falls back to deps.getStorage for the default backend. If no storage is available, the API returns HTTP 503 Service Unavailable.

Request Tracing

Each response includes a unique identifier generated by makeRequestId() for distributed tracing and debugging purposes. This ID appears in every JSON response envelope, enabling correlation across distributed systems.

Key Implementation Files

The offload API surface consists of the following source files:

• MemoryCore/src/offload_server/router.ts – Registers routes and dispatches to handlers
• MemoryCore/src/offload_server/schemas.ts – Defines MmdQuerySchema for request validation
• MemoryCore/src/offload_server/types.ts – Describes configuration and dependency interfaces
• MemoryCore/src/offload_server/ingest-handler.ts – Implements storage logic for the ingest endpoint
• MemoryCore/src/offload_server/mmd-handler.ts – Implements query-mmd retrieval logic
• MemoryCore/src/offload_server/compact/compaction-handler.ts – Implements the compact maintenance operations

Summary

• Three REST endpoints comprise the offload API: /v2/offload/ingest, /v2/offload/query-mmd, and /v2/offload/compact
• Bearer token authentication is enforced via parseV2Auth with 401 responses for invalid credentials
• Storage resolution uses deps.resolveStorage or deps.getStorage, returning 503 when backends are unavailable
• Request tracing is provided via makeRequestId() in all response envelopes
• Schema validation for queries occurs through MmdQuerySchema before handler execution

Frequently Asked Questions

What authentication method does TencentDB Agent Memory require?

The offload API requires Bearer token authentication passed via the Authorization header. The parseV2Auth function validates these credentials, and requests without valid tokens receive an HTTP 401 response.

How do I retrieve specific session context from the offload storage?

Send a POST request to /v2/offload/query-mmd with a JSON body containing the session_id you stored during ingestion. You may optionally include a limit parameter to restrict the number of returned items. The router validates your payload against MmdQuerySchema before executing the query.

What happens if the storage backend is unavailable?

If deps.resolveStorage or deps.getStorage fails to return a valid StorageAdapter, the API responds with HTTP 503 Service Unavailable. This indicates that the memory service cannot currently process the request due to backend connectivity issues.

When should I use the compact endpoint?

The /v2/offload/compact endpoint triggers maintenance operations that reclaim storage space and optimize lookup performance. You should schedule this operation during low-traffic periods or as part of automated maintenance routines, as it is handled by handleCompaction and may impact performance during execution.

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