# How MemoryProxy Interacts with Coding Agents: Architecture and Integration Flow

> Discover how MemoryProxy interacts with coding agents by transparently proxying LLM requests, managing authentication, and injecting context before forwarding to upstream models. Learn the integration flow.

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

---

**MemoryProxy acts as a transparent LLM request proxy that intercepts OpenAI/Anthropic-compatible API calls from coding agents, performing authentication, session initialization, and context injection before forwarding requests to upstream language models while preserving the original request format and response structure.**

This guide examines the TencentDB-Agent-Memory repository's MemoryProxy component, specifically how it enables coding agents like Claude Code or CodeBuddy to interact with contextual memory systems without requiring client-side modifications. The proxy sits transparently between the agent and the LLM service, handling pre-processing, memory injection, and post-processing pipelines.

## Transparent Proxy Architecture

MemoryProxy functions as an HTTP middleware layer that exposes OpenAI-compatible and Anthropic-compatible endpoints. From the coding agent's perspective, the only required change is updating the base URL to point to the proxy instead of the original LLM provider.

The proxy intercepts requests at endpoints following this pattern:

```bash
http://localhost:8096/proxy/<spaceId>/v1/chat/completions

```

For Anthropic-compatible clients:

```bash
http://localhost:8096/proxy/<spaceId>/v1/messages

```

The `spaceId` extracted from the path parameter drives authentication, billing, and memory retrieval. According to the source code in [`MemoryProxy/src/handler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/handler.ts), the proxy preserves the original request body—including the model name, temperature settings, and messages—while augmenting the system prompt with contextual data before forwarding.

## End-to-End Request Pipeline

When a coding agent sends a request, MemoryProxy executes an eight-stage pipeline before returning the LLM response. The implementation in [`MemoryProxy/src/handler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/handler.ts) and [`MemoryProxy/src/index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/index.ts) orchestrates these steps:

### 1. Authentication and Authorization

The proxy validates the `x-tdai-user-key` header by calling MemoryCore's `POST /v3/meta/auth/verify` endpoint. If verification fails, the proxy returns a **401** status immediately. Internal service accounts listed under `systemUsers` in the configuration bypass session initialization but still undergo authentication and usage logging.

### 2. Session Initialization

For non-system users on their first turn, the proxy either displays an interactive form or auto-selects context based on headers. The implementation in `MemoryProxy/src/session/` processes:

- `x-team-id` – Identifies the team workspace
- `x-agent-id` – Specifies the coding agent profile  
- `x-task-id` – Associates the conversation with a specific task

Selected metadata is injected into the system prompt to establish conversation context.

### 3. Context Injection

After session initialization, the proxy enriches the system prompt via `MemoryProxy/src/injection/`. The injection process adds three specific blocks:

- **`<cloud_skills>`** – Team-specific skills and capabilities
- **`<knowledge_tools>`** – Relevant documentation and knowledge bases
- **`<tdai_memory_tools>`** – Memory L2 (semantic) and L3 (episodic) context

Memory L0 (working) and L1 (short-term) layers are exposed as read-only tools rather than prompt injection, allowing the model to query them without breaking the KV-cache.

### 4. Rate Limiting

Before forwarding, `MemoryProxy/src/rate-limit/` applies a sliding-window limiter. Default constraints enforce **1 million tokens per minute** and **100 requests per minute** per `spaceId × final-model` combination. Exceeding these limits returns a **429** status without contacting the upstream LLM.

### 5. Upstream Forwarding

The proxy forwards the modified request verbatim to the target LLM service. The routing logic in [`MemoryProxy/src/handler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/handler.ts) detects OpenAI versus Anthropic protocol differences and constructs the appropriate upstream URL while preserving streaming and non-streaming modes.

### 6. Response Extraction and Memory Write-Back

After receiving the LLM response, `MemoryProxy/src/extraction/` asynchronously writes the conversation slice to MemoryCore via `POST /v3/skill/conversation/add`. This captures the interaction for short-term memory (L0) storage without blocking the response to the client.

### 7. Usage Reporting

The `MemoryProxy/src/report/` module sends credits, token counts, and observability traces to ClickHouse, Langfuse, and Opik. Failures in reporting channels do **not** affect the request path—these are fire-and-forget background operations.

## Configuring Coding Agents for MemoryProxy

Coding agents require zero code modifications; only the API endpoint configuration changes.

For OpenAI-compatible agents, update your configuration:

```json
{
  "apiKey": "sk-mem-xxxx",
  "baseURL": "http://localhost:8096/proxy/<spaceId>/v1",
  "model": "gpt-4"
}

```

For Anthropic-compatible agents:

```json
{
  "apiKey": "sk-mem-xxxx",
  "baseURL": "http://localhost:8096/proxy/<spaceId>/v1",
  "model": "claude-3-opus-20240229"
}

```

The agent continues to specify temperature, max_tokens, and other parameters exactly as before. The proxy handles header injection and prompt modification transparently.

## Core Implementation Files

The MemoryProxy codebase in TencentDB-Agent-Memory organizes functionality across these key modules:

| File Path | Responsibility |
|-----------|----------------|
| [`MemoryProxy/src/index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/index.ts) | HTTP server entry point that wires middleware and routing |
| [`MemoryProxy/src/handler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/handler.ts) | Core request handler routing OpenAI vs. Anthropic endpoints |
| `MemoryProxy/src/session/` | Interactive session initialization and state management |
| `MemoryProxy/src/injection/` | Skill, knowledge, and memory prompt injection logic |
| `MemoryProxy/src/skill/` | Reverse-proxy bridge to MemoryCore's Skill HTTP tools |
| `MemoryProxy/src/memory/` | Interface to MemoryCore Memory tools for L0/L1 queries |
| `MemoryProxy/src/extraction/` | Conversation persistence and L0 memory write-back |
| `MemoryProxy/src/rate-limit/` | TPM/QPM sliding window implementation |
| `MemoryProxy/src/report/` | Observability exporters for ClickHouse, Langfuse, and Opik |
| [`MemoryProxy/config.example.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/config.example.yaml) | Example configuration showing auth, injection, and storage settings |

These components collectively enable the proxy to intercept, enrich, and forward LLM calls, giving coding agents seamless access to team-wide memory and skills.

## Summary

- **MemoryProxy operates as a transparent middleware** between coding agents and LLM services, requiring only a URL change in agent configuration.
- **Authentication uses the `x-tdai-user-key` header** verified against MemoryCore's `/v3/meta/auth/verify` endpoint, with special handling for system users.
- **Context injection adds Skills, Knowledge, and Memory L2/L3** directly into system prompts, while L0/L1 remain accessible as read-only tools.
- **The eight-stage pipeline** includes auth, session init, injection, rate-limiting, forwarding, extraction, and reporting—implemented across [`handler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/handler.ts), [`index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/index.ts), and specialized subdirectories.
- **Rate limiting defaults** to 1M TPM and 100 QPM per `spaceId × model` combination via the `src/rate-limit/` module.
- **Asynchronous write-back** stores conversations to MemoryCore without blocking responses, enabling persistent memory across coding sessions.

## Frequently Asked Questions

### Do coding agents require code changes to use MemoryProxy?

No. Coding agents interact with MemoryProxy using standard OpenAI or Anthropic SDKs without modification. Agents only need to update the `baseURL` to point to `http://localhost:8096/proxy/<spaceId>/v1` while keeping the same API key format and request parameters. The proxy transparently handles all pre-processing and post-processing.

### How does MemoryProxy authenticate requests from coding agents?

The proxy extracts the `x-tdai-user-key` header from each request and validates it against MemoryCore's `POST /v3/meta/auth/verify` endpoint. If validation fails, the proxy returns HTTP 401 immediately. System users defined in the configuration can bypass session initialization while still undergoing authentication and usage tracking.

### What types of memory does the proxy inject into agent conversations?

MemoryProxy injects **L2 (semantic) and L3 (episodic) memory** directly into the system prompt using `<tdai_memory_tools>` XML blocks. **L0 (working) and L1 (short-term) memory** are exposed as read-only tools that the model can query during generation without disrupting the KV-cache. Additionally, the proxy injects team-specific Skills via `<cloud_skills>` and Knowledge bases via `<knowledge_tools>` blocks.

### How does the proxy handle high-throughput coding agent workloads?

The `MemoryProxy/src/rate-limit/` module implements a sliding-window rate limiter that enforces **1 million tokens per minute** and **100 requests per minute** per unique `spaceId` and model combination. This prevents upstream throttling while allowing burst traffic from active coding sessions. The limiter operates before upstream forwarding to reject overload conditions immediately.