# Memory Proxy Architecture and Zero-Code Integration in TencentDB Agent Memory

> Discover the Memory Proxy architecture in TencentDB Agent Memory. Learn how this transparent HTTP layer enables zero-code integration for LLM requests, seamlessly injecting skills and knowledge.

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

---

**The Memory Proxy is a transparent HTTP forwarding layer that intercepts OpenAI and Anthropic-compatible LLM requests to inject skills, knowledge, and persistent memory without requiring any code changes to the coding agent.**

The TencentDB-Agent-Memory repository implements a production-ready proxy architecture that eliminates integration friction for AI coding assistants. By sitting between agents like Claude Code or CodeBuddy and upstream LLMs, this system enables zero-code integration—teams gain persistent memory and contextual skills simply by redirecting the agent’s base URL to the proxy endpoint.

## Core Architecture of the Memory Proxy

The Memory Proxy operates as a stateless HTTP server that transparently forwards requests while enriching them with contextual data from the Memory Core. According to the implementation in [`MemoryProxy/src/index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/index.ts), the proxy listens on port `:8096` and exposes standard OpenAI `/v1/chat/completions` and Anthropic `/v1/messages` endpoints.

### The Transparent Forwarding Layer

At its foundation, the proxy maintains **API transparency**—it forwards exact OpenAI or Anthropic JSON payloads to upstream LLMs (such as TokenHub or OpenAI-compatible endpoints) while intercepting the request lifecycle to inject memory layers. The architecture follows this flow:

```

Coding Agent (Claude Code / CodeBuddy)
        │
        ▼
Memory Proxy :8096  ←  This Repository
        │
        ├───► Upstream LLM (TokenHub / OpenAI)
        │
        └───► Memory Core Gateway :8420
                ├─ Memory L0-L3 storage
                ├─ Skill search / archive
                └─ Knowledge metadata

```

The proxy extracts the `spaceId` from the request path (`/proxy/<spaceId>/v1/chat/completions`) and validates the `x-tdai-user-key` header via the Memory Core’s `/v3/meta/auth/verify` endpoint before processing.

### Context Injection and Session Management

During the **session initialization** phase, the proxy presents a lightweight configuration form (team → agent → task) and automatically injects the selected context into the system prompt. This includes:

- **L0 short-term memory**: Immediate conversation history written back after each turn
- **L2/L3 long-term memory**: Retrieved relevant past interactions
- **Skills**: Operational templates exposed via `<cloud_skills>` tool calls
- **Knowledge**: Domain metadata exposed via `<knowledge_tools>`

After each human turn, the proxy performs **conversation write-back**—archiving the interaction as a skill and persisting L0 memory to the Memory Core Gateway at `:8420`.

## How Zero-Code Integration Works

Zero-code integration is achieved through **path-based routing** and **payload compatibility**. Because the proxy accepts standard OpenAI SDK requests, any client that can call OpenAI APIs can use the proxy by changing only the base URL and including the `spaceId` in the path.

### API Compatibility Requirements

To enable zero-code integration, the proxy implements the exact request/response contracts of the major LLM providers:

- **OpenAI-compatible**: Supports `/v1/chat/completions` with standard message formats
- **Anthropic-compatible**: Supports `/v1/messages` for Claude-based agents

The proxy performs **auth and identity extraction** transparently, pulling the `spaceId` from the URL path and validating credentials against the Memory Core without client involvement.

### The Integration Workflow

The zero-code pattern works through four transparent steps:

1. **Base URL Configuration**: Point the agent to `http://<host>:8096` instead of the upstream LLM
2. **Path Routing**: Include the `spaceId` in the request path (e.g., `/proxy/demo-space/v1/chat/completions`)
3. **Payload Enrichment**: The proxy injects session info, skill context, and rate-limiting headers into the standard JSON payload
4. **Response Return**: The unmodified upstream LLM response is returned after write-back and usage reporting to ClickHouse or Langfuse

Because all memory operations, authentication, and billing calculations occur inside the proxy, the coding agent requires no SDK modifications or plugin installations.

## Implementation: Deploying the Proxy

Deploying the Memory Proxy requires two components: the proxy server and the Memory Core Gateway.

### Starting the Proxy Locally

For development environments, you can run the proxy without Redis by using local file storage. The configuration is defined in [`MemoryProxy/config.example.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/config.example.yaml):

```bash
cd MemoryProxy
npm install

# Configure for local development (no Redis)

cp config.example.yaml config.yaml
sed -i 's/redis.enabled: true/redis.enabled: false/' config.yaml
sed -i 's/storage.enabled: false/storage.enabled: true/' config.yaml

# Start the server

npm run start:config

# Or: node --import tsx/esm src/index.ts --config config.yaml

```

The proxy will listen on `localhost:8096` and route requests based on the path structure defined in [`src/index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/index.ts).

### Starting the Memory Core Gateway

The proxy depends on the Memory Core Gateway running on port `:8420`. Configure it using [`MemoryCore/tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/tdai-gateway.yaml):

```bash
cd MemoryCore
npm install
npm run build

export TDAI_GATEWAY_CONFIG="$PWD/tdai-gateway.standalone.yaml"
export TDAI_LLM_API_KEY="your-openai-key"

node --import tsx src/gateway/server.ts

```

### Client Configuration Example

Any OpenAI-compatible client can integrate by updating the base URL to include the `spaceId`:

```json
{
  "apiKey": "sk-mem-xxxx",
  "url": "http://localhost:8096/proxy/your-space-id/v1/chat/completions"
}

```

For Anthropic-compatible clients, use `http://localhost:8096/proxy/your-space-id/v1/messages`.

### Testing the Integration

Verify the zero-code setup using a standard `curl` command:

```bash
curl http://localhost:8096/proxy/demo-space/v1/chat/completions \
  -H "Authorization: Bearer sk-mem-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "gpt-4o-mini",
        "messages": [{"role":"user","content":"Write a hello world script"}]
      }'

```

The response matches standard OpenAI formatting, but the proxy has automatically initialized the session, injected relevant skills from the knowledge base, stored the turn in L0 memory, and reported token usage to the observability backend.

## Key Configuration and Source Files

The proxy architecture is defined across several critical files in the TencentDB-Agent-Memory repository:

| File | Purpose |
|------|---------|
| [`MemoryProxy/src/index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/index.ts) | HTTP routing and request lifecycle management |
| [`MemoryProxy/config.example.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/config.example.yaml) | Upstream LLM configuration, auth settings, and storage options |
| [`MemoryCore/tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/tdai-gateway.yaml) | Gateway configuration for the Memory Core service |
| [`deploy/global-images/start-proxy.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/deploy/global-images/start-proxy.sh) | Production deployment script for containerized environments |
| [`deploy/panel-knowledge-combined/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/deploy/panel-knowledge-combined/README.md) | Integration guide for Panel UI and Knowledge services |

These files collectively implement the transparent interception pattern that enables zero-code integration while maintaining full compatibility with existing OpenAI and Anthropic SDKs.

## Summary

- The **Memory Proxy** acts as a transparent HTTP layer between coding agents and LLMs, forwarding standard OpenAI/Anthropic requests while enriching them with memory and skills.
- **Zero-code integration** is achieved through path-based `spaceId` routing and API-compatible request/response contracts—requiring only a base URL change in the client.
- The architecture automatically handles **session initialization**, **context injection** (L0-L3 memory, skills, knowledge), **conversation write-back**, and **billing reporting** without agent modifications.
- Source code in [`MemoryProxy/src/index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/index.ts) and configuration in [`MemoryProxy/config.example.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/config.example.yaml) define the routing logic and upstream LLM integration.
- The system requires both the proxy (port `:8096`) and the Memory Core Gateway (port `:8420`) to function in development or production environments.

## Frequently Asked Questions

### What coding agents are compatible with the Memory Proxy?

Any agent that uses standard OpenAI-compatible (`/v1/chat/completions`) or Anthropic-compatible (`/v1/messages`) HTTP APIs can integrate without code changes. This includes Claude Code, CodeBuddy, Continue.dev, and custom Python or JavaScript applications using the official OpenAI SDK. The proxy maintains exact payload compatibility, so the agent behaves as if connecting directly to the upstream LLM.

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

The proxy extracts the `x-tdai-user-key` header from incoming requests and validates it against the Memory Core’s `/v3/meta/auth/verify` endpoint. It also extracts the `spaceId` from the request path (`/proxy/<spaceId>/...`) to isolate tenant data. According to the configuration in [`config.example.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/config.example.yaml), the proxy supports configurable upstream LLM keys and can enforce rate limiting before forwarding requests to the Memory Core Gateway.

### What is the difference between L0, L2, and L3 memory layers?

**L0** represents short-term conversation memory that is written back immediately after each user turn, maintaining the current session context. **L2 and L3** are long-term memory layers retrieved by the Memory Core Gateway (`:8420`) based on semantic relevance to the current query. The proxy automatically injects L2/L3 context into the system prompt and archives completed conversations as skills for future L2/L3 retrieval, creating a persistent knowledge loop without client-side implementation.

### Can I deploy the proxy without Redis for local development?

Yes. While production deployments typically use Redis for session storage, you can disable Redis and enable local file storage by modifying [`MemoryProxy/config.example.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/config.example.yaml)—set `redis.enabled: false` and `storage.enabled: true`. This configuration is suitable for local testing but should not be used in production environments where persistence and scalability are required.