Memory Proxy v3 API: Administrative Operations Guide for TencentDB-Agent-Memory

The Memory Proxy v3 API is a set of six administrative (ops) endpoints that expose management functionality for the Memory Proxy service on port 8096, handling instance destruction, rate-limit configuration, and session cache operations rather than LLM inference.

The Memory Proxy v3 API provides the operational backbone for the TencentDB-Agent-Memory repository, offering tools to maintain and tune the proxy instance without interrupting the primary LLM request flow. Unlike the inference-focused routes such as /v1/messages, this administrative surface enables deployment scripts and monitoring tools to manage runtime health and integration with Memory Core and Memory Knowledge components.

Core Purpose and Architecture

The Memory Proxy v3 API serves a distinct function from the standard LLM-forwarding routes. While endpoints like /:agent/:spaceId/v1/* handle model inference traffic, the v3 endpoints focus exclusively on ops and management tasks. These routes return a uniform JSON envelope containing code, message, and data fields, with session-related calls optionally including a request_id for traceability.

According to the MemoryProxy/v3-api-memoryproxy-doc.md specification, the API exposes six distinct operations designed for deployment automation and administrative maintenance.

The Six Administrative Endpoints

The v3 API surface is organized into three functional groups: instance lifecycle management, rate-limit administration, and session cache operations.

Instance Destruction

The POST /v3/instance/proxy-destroy endpoint clears a proxy-side instance's cache and releases its STS pool resources. This operation requires administrative authentication via an API key, making it the only authenticated endpoint in the v3 suite. The implementation resides in MemoryProxy/src/systemUserPassthrough.ts, which handles the cache invalidation logic and resource cleanup.

Rate-Limit Configuration

Three endpoints manage global and dimension-specific rate limiting:

• GET /v3/admin/rate-limits: Queries current rate-limit settings
• PUT /v3/admin/rate-limits: Updates or creates rate-limit entries
• DELETE /v3/admin/rate-limits: Resets specific dimensions to default values

These public (unauthenticated) endpoints allow dynamic tuning of traffic throttling without service restarts. The logic is implemented in MemoryProxy/src/tdai/admin/rateLimits.ts, supporting dimensions such as "global" with configurable limit and window_sec parameters.

Session Cache Operations

Two endpoints manage session-specific resources:

Session Cache Refresh (POST /v3/session/refresh-cache): Re-pulls agent and task details while pre-warming the injection cache for a specific session. This operation is handled by MemoryProxy/src/tdai/session/refreshCache.ts.

Force-Archive Skill Buffer (POST /v3/session/force-archive-skill): Manually triggers the archiving of a session's skill buffer, implemented in MemoryProxy/src/tdai/session/forceArchiveSkill.ts.

Authentication Model

The v3 API employs a tiered authentication strategy. While the proxy-destroy endpoint requires a valid admin API key passed via the Authorization: Bearer header, the remaining five endpoints are public by design. This separation ensures that routine maintenance tasks—such as rate-limit adjustments and cache refreshes—can be performed without exposing unnecessary authentication surfaces, while protecting destructive operations like instance destruction.

Implementation and Source Files

The actual handlers for the v3 API are distributed across the MemoryProxy source tree:

• MemoryProxy/src/systemUserPassthrough.ts: Implements the proxy-destroy handler that clears caches and releases STS pool resources.
• MemoryProxy/src/tdai/admin/rateLimits.ts: Contains the GET, PUT, and DELETE logic for rate-limit management.
• MemoryProxy/src/tdai/session/refreshCache.ts: Handles the session cache refresh operation.
• MemoryProxy/src/tdai/session/forceArchiveSkill.ts: Implements the force-archive skill endpoint.
• MemoryProxy/v3-api-memoryproxy-doc.md: The official API specification document (卷三) detailing request/response formats and error handling.

Practical Usage Examples

The following curl commands demonstrate typical interactions with the Memory Proxy v3 API. Replace ADMIN_API_KEY with your administrative token where required.

Destroy a proxy instance (requires admin authentication):

curl -X POST http://localhost:8096/v3/instance/proxy-destroy \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instance_id":"my-space-id"}'

Retrieve current rate-limit configuration:

curl http://localhost:8096/v3/admin/rate-limits

Update a global rate limit to 1000 requests per 60 seconds:

curl -X PUT http://localhost:8096/v3/admin/rate-limits \
  -H "Content-Type: application/json" \
  -d '{"dimension":"global","limit":1000,"window_sec":60}'

Reset a rate-limit dimension to defaults:

curl -X DELETE http://localhost:8096/v3/admin/rate-limits \
  -H "Content-Type: application/json" \
  -d '{"dimension":"global"}'

Refresh a session's injection cache:

curl -X POST http://localhost:8096/v3/session/refresh-cache \
  -H "Content-Type: application/json" \
  -d '{"session_id":"my-session-id"}'

Force-archive a session's skill buffer:

curl -X POST http://localhost:8096/v3/session/force-archive-skill \
  -H "Content-Type: application/json" \
  -d '{"session_id":"my-session-id"}'

Summary

• The Memory Proxy v3 API provides six administrative endpoints for managing the proxy service on port 8096, distinct from LLM inference routes.
• Instance destruction requires admin authentication and clears STS pool resources via MemoryProxy/src/systemUserPassthrough.ts.
• Rate-limit management supports dynamic configuration through GET, PUT, and DELETE operations on /v3/admin/rate-limits.
• Session operations include cache refresh and force-archive functionality for maintaining injection caches and skill buffers.
• The API uses a uniform response envelope ({code, message, data}) with selective request tracing, balancing operational accessibility with security for destructive operations.

Frequently Asked Questions

What distinguishes the Memory Proxy v3 API from the v1 endpoints?

The v1 endpoints handle LLM inference traffic and message forwarding, while the v3 API exclusively manages administrative and operational tasks such as rate limiting, cache management, and instance destruction. The v3 routes return standardized operational envelopes rather than model responses.

Is authentication required for all Memory Proxy v3 API endpoints?

No. Only the POST /v3/instance/proxy-destroy endpoint requires an admin API key via Bearer token authentication. The remaining five endpoints—including rate-limit queries and session cache operations—are public by design to facilitate automated monitoring and maintenance.

How does the proxy-destroy operation affect running sessions?

The proxy-destroy operation clears the proxy-side instance cache and releases STS (Security Token Service) pool resources associated with the specified instance_id. This is a destructive administrative action that requires authentication and should be used during deployment changes or instance recycling, not during active inference sessions.

Where can I find the complete API specification for the Memory Proxy v3 API?

The complete specification is documented in MemoryProxy/v3-api-memoryproxy-doc.md (卷三) within the TencentDB-Agent-Memory repository. This file defines the six ops endpoints, request/response schemas, error handling patterns, and authentication requirements for the administrative surface.

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