# How to Configure the Memory Proxy for Zero-Code Integration with Claude Code

> Learn how to configure the Memory Proxy for zero-code integration with Claude Code. This transparent HTTP proxy seamlessly injects context and memory without code changes.

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

---

**The TencentDB Memory Proxy enables zero-code integration with Claude Code by acting as a transparent HTTP proxy that intercepts LLM requests, injects contextual memory and skills into system prompts, and manages session initialization through environment variables or a [`settings.json`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/settings.json) file—requiring no modifications to your Claude Code client.**

The TencentDB-Agent-Memory repository provides a sophisticated **Memory Proxy** that bridges AI coding agents with persistent memory layers. This guide explains how to configure the Memory Proxy for zero-code integration with Claude Code, allowing you to leverage contextual task profiles and knowledge injection without writing a single line of client-side code.

## What the Memory Proxy Does

**Memory Proxy** is a transparent HTTP proxy that sits between Claude Code and the upstream LLM. According to the [`MemoryProxy/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/README.md) (lines 1-9), it intercepts the initial request, executes a session-initialization flow, and injects selected agent profiles, skills, and knowledge into the system prompt before forwarding the call to the real LLM.

The architecture consists of four primary components:

- **Memory Proxy HTTP entry point** (`/proxy/<spaceId>/…`) – Handles authentication, session initialization, context injection, rate-limiting, and request forwarding (see [`MemoryProxy/src/index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/index.ts) for the server entry point).
- **Session-Init handler** ([`MemoryProxy/src/session/claude-code/init.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/session/claude-code/init.ts), lines 4-9) – Drives the interactive team → agent → task selection forms and registers the session.
- **Injection pipeline** (`MemoryProxy/src/injection/*`) – Pulls Skills, Knowledge, and L2/L3 memory from MemoryCore and appends them to the system prompt (referenced in README lines 56-73).
- **MemoryCore gateway** (port `:8420`) – Stores all memory layers and supplies metadata for teams, agents, and tasks (README lines 78-84).

After the LLM responds, the proxy writes the conversation and short-term memory back to MemoryCore. This entire workflow requires no code changes in Claude Code itself.

## Deploying the Memory Proxy

### Launch the Docker Container

Deploy the proxy using the official Docker image with port `8096` exposed. You must mount your configuration file and set the administrative API key.

```bash
docker run --rm -p 8096:8096 \
  -v "$PWD/config.yaml:/data/config.yaml:ro" \
  -v tdai-proxy-data:/data/tdai-memory-proxy \
  -e TDAI_PROXY_ADMIN_API_KEY="YOUR_RANDOM_TOKEN" \
  memory-proxy:local

```

This command references the Docker deployment instructions found in the MemoryProxy README (lines 55-73).

### Configure Upstream and MemoryCore

Create a [`config.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/config.yaml) file based on [`MemoryProxy/config.example.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/config.example.yaml). Set the following critical parameters:

- **`upstream.url`** and **`upstream.apiKey`** – Point to your actual LLM endpoint (e.g., Anthropic API).
- **`auth.url`** and **`tdai.endpoint`** – Target the MemoryCore gateway at `http://127.0.0.1:8420`.
- **Storage backend** – For local testing, disable Redis (`redis.enabled: false`) and set `storage.backend: sqlite`.

```yaml
upstream:
  url: "https://api.anthropic.com"
  apiKey: "${ANTHROPIC_API_KEY}"

tdai:
  endpoint: "http://127.0.0.1:8420"

redis:
  enabled: false

storage:
  backend: sqlite

```

## Zero-Code Client Configuration

### Method 1: Environment Variables

Export the required variables before launching Claude Code. The `ANTHROPIC_BASE_URL` must route through the proxy, and `ANTHROPIC_AUTH_TOKEN` should contain your Memory Proxy key (as documented in [`agents/claude-code/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/agents/claude-code/README.md), lines 11-29).

```bash
export ANTHROPIC_BASE_URL="http://127.0.0.1:8096/claude-code/default"
export ANTHROPIC_AUTH_TOKEN="sk-mem-xxxxxxxx"
export ANTHROPIC_MODEL="claude-opus-4.7"

```

Run Claude Code normally; the client will automatically route all LLM traffic through the proxy.

### Method 2: Persistent Settings File

For a permanent configuration, create `~/.claude/settings.json` with the following structure:

```json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-mem-xxxxxxxx",
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8096/claude-code/default",
    "ANTHROPIC_MODEL": "claude-opus-4.7"
  }
}

```

Claude Code reads this file on startup, eliminating the need to export variables in every terminal session.

### Validate the Proxy URL Pattern

Ensure your configuration uses the correct **spaceId** (memory instance ID) in the URL path. According to the Anthropic Messages client snippet (Claude Code README lines 71-84), the format must include the space identifier:

```

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

```

The proxy uses this path parameter to resolve the user and memory instance.

## Advanced: Pre-Selecting Context via Headers

To bypass the interactive team/agent/task forms entirely, pre-select your context using HTTP headers. In [`MemoryProxy/src/session/claude-code/init.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/session/claude-code/init.ts), the `handleSessionInit` function (lines 665-720) checks for these headers and skips the form flow when they are present.

Include the following headers in your requests:

- **`x-team-id`** – Team identifier
- **`x-agent-id`** – Agent profile identifier  
- **`x-task-id`** – Task identifier
- **`x-tdai-user-key`** – Your Memory Proxy authentication token

Example using `node-fetch`:

```javascript
const fetch = require('node-fetch');

await fetch('http://localhost:8096/proxy/my-space/v1/messages', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-team-id': 'team-123',
    'x-agent-id': 'agent-456',
    'x-task-id': 'task-789',
    'x-tdai-user-key': 'sk-mem-abc123',
  },
  body: JSON.stringify({
    model: 'claude-opus-4.7',
    messages: [{ role: 'user', content: 'Explain quantum entanglement' }],
  }),
});

```

When these headers are present, the proxy registers the session directly and immediately injects the specified context into the system prompt.

## Key Source Files

Understanding these files helps troubleshoot or extend the integration:

| File | Purpose | Key Details |
|------|---------|-------------|
| [`MemoryProxy/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/README.md) | Proxy overview and request pipeline | Lines 1-9 (architecture), 56-73 (injection), 78-84 (MemoryCore) |
| [`MemoryProxy/src/session/claude-code/init.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/session/claude-code/init.ts) | Session initialization logic | Lines 4-9 (imports), 665-720 (`handleSessionInit` with header branch) |
| [`agents/claude-code/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/agents/claude-code/README.md) | Client-side configuration | Lines 11-29 (env vars), 71-84 (URL patterns) |
| `MemoryProxy/src/injection/*` | Context injection implementation | Appends Skills/Knowledge to system prompts |
| [`MemoryProxy/config.example.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/config.example.yaml) | Configuration template | Upstream, auth, and storage settings |
| [`MemoryProxy/src/index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/index.ts) | HTTP server entry point | Routes `/proxy/<spaceId>/…` endpoints |

## Summary

- **Memory Proxy** acts as a transparent intermediary between Claude Code and LLM providers, injecting contextual memory without client modifications.
- Deploy the proxy via Docker on port `8096`, ensuring [`config.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/config.yaml) points to your upstream LLM and the MemoryCore gateway on port `8420`.
- Configure Claude Code using either environment variables (`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`) or the `~/.claude/settings.json` file.
- The proxy URL must include your `<spaceId>` to resolve the correct memory instance.
- Use headers (`x-team-id`, `x-agent-id`, `x-task-id`) to skip interactive forms and pre-select context programmatically.

## Frequently Asked Questions

### What is the difference between Memory Proxy and MemoryCore?

**Memory Proxy** is the HTTP interception layer that handles authentication, session initialization, and prompt injection, while **MemoryCore** (running on port `:8420`) is the persistent storage service for conversation history, skills, and knowledge layers. The proxy reads from and writes to MemoryCore, but they run as separate processes.

### Can I use the Memory Proxy with other LLM clients besides Claude Code?

Yes. Any client compatible with the Anthropic Messages API or OpenAI-compatible endpoints can route through the proxy. You only need to set the base URL and authentication token to point at the proxy's `/proxy/<spaceId>/v1/messages` endpoint. The injection pipeline in `MemoryProxy/src/injection/*` handles the rest transparently.

### How does the session initialization flow work when I first connect?

When Claude Code sends its first request, the proxy intercepts it and triggers the session-initialization logic in [`init.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/init.ts). If you haven't provided pre-selection headers, the proxy presents an interactive **asset-confirm** form followed by team → agent → task selection forms. Once you complete the forms, the proxy registers the session, caches your selections, and injects the corresponding context into subsequent LLM calls.

### Is Redis required for the Memory Proxy to function?

No. For local testing and zero-code integration, you can disable Redis by setting `redis.enabled: false` and `storage.backend: sqlite` in your [`config.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/config.yaml). This configuration uses local SQLite storage instead of Redis, though Redis is recommended for production deployments handling high concurrency.