# How to Integrate Agents with TencentDB Agent Memory Using MemoryProxy for Zero-Code Integration

> Easily integrate AI agents with TencentDB Agent Memory using MemoryProxy. Route HTTP requests for zero-code integration without client SDK modifications. Learn how now.

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

---

**You can integrate any AI agent with TencentDB Agent Memory by routing HTTP requests through the MemoryProxy layer and enabling the WorkBuddy routing switch, eliminating the need for client-side SDK modifications or code changes.**

TencentDB Agent Memory provides a production-ready zero-code integration path that intercepts LLM requests at the network layer. By deploying the MemoryProxy component in front of your upstream LLM endpoint, your agent automatically receives session management, asset injection, and persistent memory capabilities without requiring changes to your existing application code.

## Architecture of the MemoryProxy Layer

The TencentDB Agent Memory system is organized into three logical layers that share a single configuration schema defined in [`MemoryProxy/src/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/types.ts).

- **Memory Core** (port 8420): Handles raw LLM request forwarding and credit accounting.
- **Memory Knowledge** (port 8421): Manages knowledge-tool injection for search and retrieval operations.
- **Memory Proxy** (port 8096): Acts as an LLM reverse-proxy with automatic asset injection, implementing the `ProxyConfig` interface for unified settings.

The **MemoryProxy** sits between your agent and the upstream LLM provider (OpenAI-compatible or Anthropic). When `workbuddyRequestRouting.enabled` is set to `true` in the configuration, the proxy activates the **WorkBuddy handler** ([`MemoryProxy/src/workbuddyHandler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/workbuddyHandler.ts)), which implements a 10-step pipeline to process requests without client-side intervention.

## The 10-Step WorkBuddy Request Pipeline

According to the source code in [`workbuddyHandler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/workbuddyHandler.ts), every request traverses a strict pipeline that handles authentication, session initialization, and asset injection before reaching the LLM provider.

The pipeline executes the following sequence:

1. **`verifyUserKey`**: Validates the Bearer token or `x-api-key` header against the authentication service (lines 22-34).
2. **JSON body parsing**: Extracts the request payload for inspection.
3. **`classifyWorkbuddyRequest`**: Distinguishes between auxiliary paths (`/compact`, `/trace_summarize`) and main LLM requests using the `x-openai-memgen-request` header (lines 122-148).
4. **Auxiliary passthrough**: Routes administrative requests directly upstream without injection.
5. **`extractWorkbuddySessionId`**: Retrieves the session identifier from the `session-id` header or `body.client_metadata.session_id` (lines 161-174).
6. **Langfuse context initialization**: Prepares tracing metadata for the current turn.
7. **`handleSessionInit`**: Delegates to the generic session initialization flow using the Responses API wire format to build or recover `<session_context>` blocks (lines 99-128).
8. **Pre-warm injection cache**: Loads agent-specific assets (skills, knowledge, TD AI memory) via the injection pipeline ([`injection/index.js`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/injection/index.js)).
9. **`injectWorkbuddyAssets`**: Inserts a `<tdai_injections>` block into the first developer message using `buildWorkbuddyInjectionBlock` (lines 221-242).
10. **`forwardToUpstream` and `consumeWorkbuddyStream`**: Forwards the modified request to the LLM provider, then tees the SSE stream to Langfuse reporting, TD AI L0 writes (`recordTdaiTurn`), and skill extraction triggers (`triggerSkillExtractIfReady`).

## Enabling Zero-Code Integration

To activate zero-code integration, deploy the MemoryProxy and update your agent configuration to point to the proxy endpoint instead of the native LLM API.

### Step 1: Deploy the MemoryProxy

Run the proxy using the official Docker image, mounting your configuration file:

```bash
docker run -p 8096:8096 \
  -v /path/to/config.yaml:/etc/memory-proxy.yaml \
  tencentcloud/tdai-memory-proxy:latest

```

### Step 2: Configure Proxy Settings

Create a [`config.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/config.yaml) that enables WorkBuddy routing and specifies which assets to inject. The schema follows the `ProxyConfig` interface defined in [`MemoryProxy/src/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/types.ts):

```yaml
server:
  host: "0.0.0.0"
  port: 8096

upstream:
  url: "https://api.openai.com/v1"
  apiKey: ""  # Optional global key

injection:
  enabled: true
  injectors:
    - "skill"
    - "knowledge"
    - "tdai-memory"

workbuddyRequestRouting:
  enabled: true  # Activates zero-code handling

tdai:
  enabled: true
  endpoint: "https://tdai.tencentyun.com"
  apiKey: "TD_AI_API_KEY"
  memory:
    enabled: true
    inject: true
    writeL0: true

```

### Step 3: Point Your Agent to the Proxy

Update your agent's API base URL to the MemoryProxy endpoint. The proxy accepts standard OpenAI-compatible requests:

```bash
curl -X POST http://localhost:8096/workbuddy/myspace/v1/chat/completions \
  -H "Authorization: Bearer USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "stream": true,
    "input": [{
      "type": "message",
      "role": "user",
      "content": [{"type": "text", "text": "Explain database indexing strategies."}]
    }],
    "client_metadata": {"session_id": "sess_001"}
  }'

```

The proxy automatically creates or reuses sessions, injects skill and knowledge tool definitions, and writes the user turn to TD AI memory (L0) without additional client code.

### Step 4: Use Management APIs for Cache Control

Without restarting the proxy, you can refresh session caches or force-archive skill buffers using the `/v3/*` management APIs documented in [`MemoryProxy/v3-api-memoryproxy-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/v3-api-memoryproxy-doc.md):

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

```

## Automatic Features You Gain

By routing through MemoryProxy, you automatically enable the following capabilities defined in the TencentDB Agent Memory source code:

- **Session Persistence**: The `SessionStore` (backed by Redis or ProxyStorage) maintains per-session state across requests, recovered via `handleSessionInit` in [`session/store.js`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/session/store.js).
- **Dynamic Asset Injection**: The injection pipeline ([`injection/index.js`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/injection/index.js)) dynamically loads skill, knowledge, and TD AI memory injectors and caches them for performance.
- **TD AI L0 Memory Writes**: The `recordTdaiTurn` function in [`tdai/recorder.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tdai/recorder.ts) persists user turns to the TD AI kernel with automatic retry logic (`withL0Retry`).
- **Skill Extraction**: `triggerSkillExtractIfReady` in [`skill/handler-glue.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/skill/handler-glue.ts) automatically fires `/v3/skill/extract` when conversation thresholds are met.
- **Observability**: Langfuse generation events and failure reports are emitted automatically via `langfuseReportGeneration` and `langfuseReportFailure` in [`langfuse.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/langfuse.ts).
- **Rate Limiting**: Admin operations and rate limits are exposed through the `/v3/*` ops API interface.

## Summary

- **MemoryProxy** (port 8096) acts as a zero-code integration layer that intercepts LLM requests and enriches them with TencentDB Agent Memory capabilities.
- Enable zero-code integration by setting `workbuddyRequestRouting.enabled: true` in the `ProxyConfig` schema defined in [`MemoryProxy/src/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/types.ts).
- The **WorkBuddy handler** implements a 10-step pipeline ([`workbuddyHandler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/workbuddyHandler.ts)) that handles authentication, session initialization, asset injection, and upstream forwarding automatically.
- Your agent only needs to change its API endpoint to `http://<proxy>:8096/workbuddy/<spaceId>/v1/chat/completions`; no SDK modifications are required.
- Management APIs under `/v3/*` allow runtime cache refreshes and skill buffer archives without service restarts.

## Frequently Asked Questions

### What is the difference between MemoryProxy and MemoryCore?

**MemoryCore** (port 8420) handles raw LLM request forwarding and credit accounting, while **MemoryProxy** (port 8096) provides the reverse-proxy layer with asset injection, session management, and TD AI memory integration. The proxy sits in front of your upstream LLM provider and can optionally route to MemoryCore for specific operations, but for zero-code integration, you only interact with MemoryProxy.

### Do I need to modify my existing agent code to use TencentDB Agent Memory?

**No.** Zero-code integration requires only configuration changes. Point your agent's HTTP client to the MemoryProxy endpoint (`http://<host>:8096/workbuddy/<spaceId>/...`) instead of the native OpenAI or Anthropic URL. The proxy handles authentication, session context building, and asset injection transparently. Your existing request formats remain compatible.

### How does the proxy handle authentication and security?

The proxy validates incoming requests using `verifyUserKey` (implemented in [`workbuddyHandler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/workbuddyHandler.ts) lines 22-34), which checks the `Authorization: Bearer` header or `x-api-key` against the configured authentication service. Validated requests are then tagged with session context and traced through Langfuse for auditability, while sensitive upstream API keys remain server-side in the proxy configuration.

### Can I selectively disable asset injectors while keeping the proxy active?

**Yes.** The `injection` configuration block in `ProxyConfig` allows granular control. Set `injection.enabled: true` but modify the `injectors` array to include only the assets you need (e.g., `["skill", "knowledge"]` without `"tdai-memory"`). You can also toggle TD AI memory writes independently using `tdai.memory.writeL0: false` while keeping injection active for other features.