TencentDB-Agent-Memory v3 API Endpoints for Memory Operations: Complete Reference

The MemoryProxy service exposes six ops-only HTTP endpoints prefixed with /v3 that manage memory resources, rate limits, and session caches, all returning standardized JSON envelopes with distinct error code schemes.

The TencentDB-Agent-Memory repository provides a specialized MemoryProxy component that exposes v3 API endpoints for memory operations, enabling administrative control over instance caches, rate limiting policies, and session-level memory management. These endpoints run on localhost:8096 by default and implement a consistent request/response contract defined in MemoryProxy/v3-api-memoryproxy-doc.md.

v3 MemoryProxy API Architecture

The v3 endpoints follow a uniform architectural pattern. All requests target the base host localhost:8096 and return a JSON envelope containing code, message, and optional data fields. The API distinguishes between administrative operations (instance destruction, rate limiting) and session operations (cache refresh, skill archival).

Authentication varies by endpoint scope. The instance/proxy-destroy endpoint optionally accepts Authorization: Bearer <admin.apiKey> headers, while session and rate-limit endpoints operate without authentication headers.

Instance Management Endpoints

Destroy Proxy Instance Cache (POST /v3/instance/proxy-destroy)

This endpoint removes a proxy-side instance’s cache and its associated STS (Short-Term Storage) pool. It requires explicit authorization via Bearer token.

Request format:

{
  "instance_id": "string"
}

The instance_id must be non-empty and cannot contain / or .. characters to prevent path traversal attacks.

Response format:

{
  "code": 0,
  "message": "ok",
  "data": {
    "instance_id": "string",
    "cleaned": {
      "storage_backend": "string",
      "storage_ttl_deleted": 0,
      "storage_nottl_deleted": 0,
      "cos_pool_evicted": "string",
      "redis_skipped": "string"
    }
  }
}

Example request:

curl -X POST "http://localhost:8096/v3/instance/proxy-destroy" \
     -H "Authorization: Bearer <admin.apiKey>" \
     -H "Content-Type: application/json" \
     -d '{"instance_id":"mem-example001"}'

Rate Limit Administration Endpoints

The /v3/admin/rate-limits resource supports global and per-instance/model rate limiting with three HTTP methods.

Retrieve Rate Limits (GET /v3/admin/rate-limits)

Query parameters determine the response scope. When instance_id and model_id appear together, the endpoint returns dimension-specific limits; otherwise, it returns global configuration.

Global response format:

{
  "code": 0,
  "message": "ok",
  "data": {
    "enabled": true,
    "tpm": 100000,
    "qpm": 300,
    "window_seconds": 60,
    "overrides": []
  }
}

Per-dimension response format:

{
  "enabled": true,
  "instance_id": "mem-example001",
  "model_id": "claude-3-sonnet",
  "input_tpm": 50000,
  "qpm": 100,
  "source": "override",
  "global": false
}

Configure Rate Limits (PUT /v3/admin/rate-limits)

Accepts either global settings or paired instance/model overrides.

Request format:

{
  "input_tpm": 100000,
  "qpm": 300,
  "instance_id": "optional-string",
  "model_id": "optional-string"
}

Note that instance_id and model_id must appear together when specified.

Example request:

curl -X PUT "http://localhost:8096/v3/admin/rate-limits" \
     -H "Content-Type: application/json" \
     -d '{"input_tpm":100000,"qpm":300}'

Remove Rate Limits (DELETE /v3/admin/rate-limits)

Deletes rate-limit entries, reverting configurations to defaults. Accepts optional paired identifiers to target specific overrides.

Request format:

{
  "instance_id": "optional-string",
  "model_id": "optional-string"
}

Response format:

{
  "code": 0,
  "message": "ok",
  "data": {
    "tpm": 100000,
    "qpm": 300
  }
}

Or for dimension-specific deletions:

{
  "instance_id": "mem-example001",
  "model_id": "claude-3-sonnet",
  "deleted": true
}

Session Cache Management Endpoints

According to the source code in MemoryProxy/src/workbuddyHandler.ts, session endpoints manage runtime memory states without requiring authentication tokens.

Refresh Session Cache (POST /v3/session/refresh-cache)

Reloads Agent and Task details into the injection cache and pre-warms session memory. Implemented in workbuddyHandler.ts.

Request format:

{
  "session_key": "sess_1",
  "agent_source": "claude-code",
  "user_key": "optional-string",
  "space_id": "optional-string"
}

The agent_source parameter defaults to claude-code when omitted.

Response format:

{
  "code": 0,
  "message": "ok",
  "request_id": "refresh-<timestamp>",
  "data": {
    "refreshed": ["string"],
    "skipped": ["string"],
    "agent_refreshed": true,
    "task_refreshed": true,
    "took_ms": 150
  }
}

Example request:

curl -X POST "http://localhost:8096/v3/session/refresh-cache" \
     -H "Content-Type: application/json" \
     -d '{"session_key":"sess_1","agent_source":"claude-code","space_id":"mem-example001"}'

Force Archive Skill Buffer (POST /v3/session/force-archive-skill)

Bypasses normal threshold checks to immediately archive a session’s skill buffer. This permanent operation requires explicit justification via the reason field.

Request format:

{
  "session_key": "sess_1",
  "agent_source": "claude-code",
  "reason": "manual",
  "space_id": "optional-string"
}

Response format:

{
  "code": 0,
  "message": "ok",
  "request_id": "force-archive-<timestamp>",
  "data": {
    "status": "archived",
    "task_id": "optional-string",
    "archive_key": "optional-string",
    "archived_at_ms": 1704067200000
  }
}

Status values include "archived" (successful archival) or "empty" (no data to archive).

Example request:

curl -X POST "http://localhost:8096/v3/session/force-archive-skill" \
     -H "Content-Type: application/json" \
     -d '{"session_key":"sess_1","reason":"manual"}'

Error Handling Conventions

The v3 API endpoints for memory operations implement two distinct error code schemes as defined in MemoryProxy/src/turnSeq.ts and documented in MemoryProxy/v3-api-memoryproxy-doc.md:

• Instance and Admin endpoints (/v3/instance/proxy-destroy, /v3/admin/rate-limits): Return HTTP status codes (400, 401, 503) directly in the code field.
• Session endpoints (/v3/session/*): Return 5-digit application codes (40001, 40401, 50001) while maintaining standard HTTP status codes (400, 404, 500) at the transport layer.

This distinction allows monitoring systems to differentiate between transport failures and application-level business logic violations.

Source Code Implementation Reference

The v3 memory operation API contracts are implemented across four key files in the TencentDB-Agent-Memory repository:

• MemoryProxy/v3-api-memoryproxy-doc.md – Contains the canonical specification for all v3 ops endpoints, request/response schemas, and error code mappings.
• MemoryProxy/src/workbuddyHandler.ts – Implements the HTTP route handlers for session-related endpoints including refresh-cache and force-archive-skill.
• MemoryProxy/src/types.ts – Defines TypeScript interfaces for request payloads and response envelopes used throughout the v3 API surface.
• MemoryProxy/src/turnSeq.ts – Houses the core coordination logic for request routing, envelope construction, and error code normalization across all v3 endpoints.

Summary

• Six specialized endpoints provide complete control over memory operations: one for instance destruction, three for rate limit management, and two for session cache manipulation.
• Dual error code schemes distinguish between administrative endpoints (HTTP status codes) and session endpoints (5-digit application codes).
• Authentication requirements vary by sensitivity: instance destruction requires Bearer tokens, while rate limits and session operations are unauthenticated.
• Strict input validation prevents path traversal in instance IDs and enforces paired parameters for rate limit dimensions.
• Standardized JSON envelopes ensure consistent parsing across all http://localhost:8096/v3/* paths.

Frequently Asked Questions

What is the base URL for v3 memory operations?

All v3 API endpoints for memory operations target http://localhost:8096/v3/ by default. Individual paths append to this base, such as /v3/instance/proxy-destroy or /v3/session/refresh-cache. The MemoryProxy service binds to port 8096 as configured in the repository's deployment defaults.

How do I authenticate administrative operations?

The POST /v3/instance/proxy-destroy endpoint optionally accepts authentication via the Authorization: Bearer <admin.apiKey> header. Rate limit and session endpoints do not require authentication headers, making them suitable for internal service-to-service communication within the TencentDB-Agent-Memory architecture.

What is the difference between global and per-instance rate limits?

Global rate limits apply across all instances and models when no specific overrides exist. When you provide both instance_id and model_id parameters to the GET, PUT, or DELETE /v3/admin/rate-limits endpoints, you create or modify dimension-specific overrides that take precedence over global settings. Global configurations return fields like tpm and qpm, while dimension-specific responses include input_tpm, source, and global boolean flags.

Why do session endpoints use 5-digit error codes?

Unlike the instance and admin endpoints that return HTTP status codes (400, 401, 503) in the JSON code field, the session endpoints (/v3/session/refresh-cache and /v3/session/force-archive-skill) implement application-specific error codes (40001, 40401, 50001) as defined in MemoryProxy/src/turnSeq.ts. This design allows the client to distinguish between transport-layer failures (HTTP 500) and business logic violations (code 50001) while maintaining the same HTTP status for load balancer health checks.

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