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

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, codexHandler.ts) that classify requests and extract session metadata.
• Injection Pipeline (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:

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:

{
  "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

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

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

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:

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.
• 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 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.

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