# How to Integrate TencentDB Agent Memory with Other Agent Frameworks via MemoryProxy

> Seamlessly integrate TencentDB Agent Memory with agent frameworks using MemoryProxy. Inject skills memory and knowledge into LLM requests without altering your agent code.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: how-to-guide
- Published: 2026-08-29

---

**Integrate TencentDB Agent Memory with any agent framework by routing LLM requests through the MemoryProxy on port 8096, which injects skills, memory, and knowledge assets into OpenAI Responses API payloads without requiring changes to your agent code.**

TencentDB Agent Memory provides a **MemoryProxy** component that acts as a reverse proxy between your agent framework and upstream LLM providers. According to the TencentCloud/TencentDB-Agent-Memory source code, this proxy intercepts requests, enriches them with contextual assets from MemoryCore, and forwards them to the target model. This guide explains the architecture, configuration steps, and code patterns needed to connect external agents via the MemoryProxy.

## Understanding the MemoryProxy Architecture

The MemoryProxy operates as an intermediary layer that processes LLM requests through three distinct phases: classification, session handling, and asset injection.

### Core Components

The proxy consists of several key layers defined in the repository:

- **LLM Front-end (Port 8096)**: Exposes `/v1/*` and `/:agent/:spaceId/v1/*` endpoints that mirror the OpenAI Responses API. This layer accepts incoming requests from your agent framework.
- **Ops API (`/v3/*`)**: Management plane for proxy operations including instance destruction, rate-limit configuration, and session cache refresh.
- **Agent Adapters**: TypeScript handlers ([`workbuddyHandler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/workbuddyHandler.ts), [`codexHandler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/codexHandler.ts)) that classify requests and extract session metadata.
- **Injection Pipeline** ([`injection/index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/injection/index.ts)): Pre-warms and prepares asset blocks that get appended to request payloads.

### Request Processing Pipeline

Every request passing through the proxy executes three logical steps as implemented in [`MemoryProxy/src/workbuddyHandler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/workbuddyHandler.ts):

1. **Classification**: The `classifyWorkbuddyRequest` or `classifyCodexRequest` function determines if a request is auxiliary (pass-through) or main (requires injection).
2. **Session Handling**: Functions like `extractWorkbuddySessionId` pull the session identifier from headers or body, create a Langfuse turn context, and initialize the conversation state machine via `handleSessionInit`.
3. **Asset Injection & Forwarding**: The pipeline fetches skills and prompts from MemoryCore, injects them as `<tdai_injections>` blocks into `body.input[0].content[]`, forwards the enriched request to the upstream LLM, and asynchronously processes the SSE stream for usage tracking and L0 memory writes.

## Configuring the Integration

Connecting an external agent framework requires minimal configuration changes, primarily involving endpoint redirection and session management.

### Pointing Your Agent to the Proxy

Configure your agent's LLM client to use the proxy endpoint instead of the direct OpenAI or provider URL:

- Set the base URL to `http://<proxy-host>:8096`
- Maintain the standard OpenAI request structure (`model`, `input`, `stream` parameters)
- Ensure your agent uses the **OpenAI Responses API** format (not Chat Completions), as this is the wire protocol expected by the proxy's adapter handlers

### Session Management

The proxy requires a stable session identifier to maintain conversation continuity and retrieve the correct memory assets:

- Include the `session-id` HTTP header: `session-id: <your-session-identifier>`
- Alternatively, embed the session ID in the JSON body under `client_metadata.session_id`
- The proxy uses this ID to fetch relevant skills and prompts associated with the specific `team_id`, `agent_id`, and `user_id`

### Upstream LLM Configuration

Specify the target LLM provider in the proxy configuration:

```json
{
  "url": "https://api.openai.com/v1",
  "apiKey": "<upstream-api-key>"
}

```

Store this in `config/upstream` or supply it via environment variables. The proxy will forward enriched requests to this endpoint while preserving the authorization headers.

## Implementing the Integration

The following examples demonstrate practical integration patterns using cURL and Node.js.

### Basic cURL Request

```bash
curl -X POST http://localhost:8096/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <upstream-api-key>" \
  -H "session-id: my-session-001" \
  -d '{
        "model": "gpt-4o-mini",
        "stream": true,
        "input": [
          { "type":"message", "role":"user", "content":"Explain the PR workflow." }
        ]
      }'

```

This request triggers the full pipeline: classification as a main request, injection of relevant assets, and streaming response forwarding.

### Node.js Implementation

```javascript
import fetch from "node-fetch";

const proxyUrl = "http://localhost:8096/v1/chat/completions";
const body = {
  model: "gpt-4o-mini",
  stream: false,
  input: [
    { type: "message", role: "user", content: "What is the current release schedule?" }
  ]
};

const resp = await fetch(proxyUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <upstream-key>",
    "session-id": "release-session-42"
  },
  body: JSON.stringify(body)
});

const data = await resp.json();
console.log(data);

```

## Managing Assets via the v3 API

Before the proxy can inject assets, you must create them using the TypeScript SDK or direct API calls.

### Creating Skills with the SDK

```typescript
import { MemoryClient } from "@tencentdb-agent-memory/memory-sdk-ts-v2";

const client = new MemoryClient({
  endpoint: "http://127.0.0.1:8420",
  apiKey: "sk-mem-xxxx",
  serviceId: "instance-001",
  teamId: "team-01",
  agentId: "agent-01",
  userId: "usr-01"
});

const skill = await client.createSkill({
  name: "release-notes",
  content: `You are a release-notes generator. Use the latest tags from the repo to build a markdown summary.`,
  resources: []
});

console.log("Created skill:", skill.skill_id);

```

Once created, any proxy request matching the same `teamId/agentId/userId` context automatically receives this skill in the injection block.

### Refreshing Session Cache

Force the proxy to reload assets for a specific session:

```bash
curl -X POST http://localhost:8096/v3/session/refresh-cache \
  -H "Content-Type: application/json" \
  -d '{
        "session_key": "my-session-001",
        "agent_source": "workbuddy",
        "space_id": "mem-example001"
      }'

```

## Security and Authentication

The proxy implements tiered authentication based on endpoint sensitivity:

| Endpoint | Authentication | Headers |
|----------|---------------|---------|
| `/v3/instance/proxy-destroy` | Bearer token | `Authorization: Bearer <admin.apiKey>` |
| `/v3/admin/rate-limits` | None | - |
| LLM forward (`/v1/*`) | Bearer token + optional user key | `Authorization: Bearer <upstream-key>`, `x-tdai-user-key` |
| Metadata (`/v3/meta/*`) | Bearer + service ID | `Authorization: Bearer <key>`, `x-tdai-service-id` |

The proxy assumes upstream gateways handle user-level ACL validation for management operations.

## Summary

- **MemoryProxy** acts as a reverse proxy on port 8096 that intercepts OpenAI Responses API calls and injects memory assets transparently.
- **Three-phase processing**: Classification via `classifyWorkbuddyRequest`, session extraction via `extractWorkbuddySessionId`, and asset injection via the pipeline in [`injection/index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/injection/index.ts).
- **Zero code changes** required in downstream agents; simply redirect the base URL and provide a stable `session-id` header.
- **Asset management** occurs through the v3 API using the `@tencentdb-agent-memory/memory-sdk-ts-v2` package or direct HTTP calls.
- **Observability** built-in via Langfuse integration and async stream tapping for usage reporting and L0 memory writes.

## Frequently Asked Questions

### What agent frameworks are compatible with MemoryProxy?

Any agent framework that uses the **OpenAI Responses API** format is compatible. This includes Codex, WorkBuddy, and custom agents built with libraries like LangChain or LlamaIndex, provided they can target a custom base URL and use the Responses API wire protocol rather than the older Chat Completions format.

### Does the proxy support streaming responses?

Yes. The proxy fully supports Server-Sent Events (SSE) streaming. When `stream: true` is set in the request body, the proxy forwards the SSE stream from the upstream LLM while asynchronously tapping the stream to report usage metrics to Langfuse and trigger post-conversation memory writes without blocking the client connection.

### How does the proxy determine which skills to inject?

The proxy extracts `team_id`, `agent_id`, and `user_id` from the session context (derived from the `session-id` header or metadata) and queries MemoryCore for assets matching these identifiers. The `injectWorkbuddyAssets` function in [`workbuddyHandler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/workbuddyHandler.ts) then appends the relevant prompts and skills as a `<tdai_injections>` block within the request payload's content array.

### What is the difference between the v1 and v3 API endpoints?

The `/v1/*` endpoints handle LLM forwarding and asset injection, acting as the data plane for agent requests. The `/v3/*` endpoints (Ops API) provide the control plane for proxy management, including session cache refresh, instance destruction, and rate-limit configuration, as documented in [`MemoryProxy/v3-api-memoryproxy-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/v3-api-memoryproxy-doc.md).