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

> Explore TencentDB Agent Memory v3 API endpoints for memory operations. Get complete reference for request/response formats of memory resources, rate limits, and session caches.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: api-reference
- Published: 2026-08-26

---

**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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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:**

```json
{
  "instance_id": "string"
}

```

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

**Response format:**

```json
{
  "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:**

```bash
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:**

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

```

**Per-dimension response format:**

```json
{
  "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:**

```json
{
  "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:**

```bash
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:**

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

```

**Response format:**

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

```

Or for dimension-specific deletions:

```json
{
  "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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/workbuddyHandler.ts).

**Request format:**

```json
{
  "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:**

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

```

**Example request:**

```bash
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:**

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

```

**Response format:**

```json
{
  "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:**

```bash
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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/turnSeq.ts) and documented in [`MemoryProxy/v3-api-memoryproxy-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/workbuddyHandler.ts)** – Implements the HTTP route handlers for session-related endpoints including `refresh-cache` and `force-archive-skill`.
- **[`MemoryProxy/src/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/types.ts)** – Defines TypeScript interfaces for request payloads and response envelopes used throughout the v3 API surface.
- **[`MemoryProxy/src/turnSeq.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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.