# Client Configuration for Connecting to MemoryProxy: The Complete Setup Guide

> Master client configuration for MemoryProxy. Connect LLM clients easily by setting the base URL, authenticating with user_key, and matching the model name. Get the complete setup guide.

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

---

**To connect any LLM client to MemoryProxy, point the base URL to `http://<proxy-host>:8096/<agent-type>/default`, authenticate using your `user_key` token, and ensure the model name matches your configured upstream provider.**

The MemoryProxy serves as a lightweight middleware layer within the TencentDB-Agent-Memory architecture that intercepts LLM requests from coding agents and automatically injects team memory assets—including Chat Memory, Skills, Wiki, and CodeGraph—before forwarding to the upstream model. According to the source code in [`INSTALL.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/INSTALL.md), the proxy binds to port 8096 and requires precise client-side configuration to resolve the correct team, agent, and task context during session initialization.

## Core Configuration Parameters

All agents connecting to MemoryProxy share three fundamental configuration requirements, regardless of their specific SDK implementation.

### Base URL Structure

Clients must direct their LLM endpoint to the proxy rather than the original provider URL. The standard format follows:

```bash
http://<proxy-host>:8096/<agent-type>/default

```

The proxy listens on **port 8096** and expects an `<agent-type>` path segment that corresponds to the upstream LLM provider (e.g., `claude-code`, `codebuddy`, `opencode`). The trailing `default` segment represents the memory-instance ID (`x-tdai-service-id`), which can be customized based on your deployment configuration.

### Authentication Token

Every request must include a valid **business user token** (`user_key`) generated by the Memory Hub. This value is returned by the `POST /v3/meta/user/create` endpoint and serves as the primary authentication mechanism. As implemented in the proxy's auth layer, this token validates the user against Memory Core and enables lookup of associated teams, agents, and task contexts.

### Optional Context Headers

For agents requiring non-interactive session initialization (such as Hermes or OpenClaw), you must pre-select the context using HTTP headers or environment variables:

- `x-team-id` – Specifies the target team identifier
- `x-agent-id` – Specifies the agent configuration to load
- `x-task-id` – Optionally binds the session to a specific task context

These headers bypass the interactive picker that typically runs during the first conversation turn.

## Agent-Specific Configuration Examples

The TencentDB-Agent-Memory repository supports nine first-party agents, each with dedicated configuration locations documented in [`INSTALL.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/INSTALL.md) lines 78-89.

### Claude Code (Anthropic) Configuration

For the Claude Code agent, set environment variables before launching the CLI:

```bash
export ANTHROPIC_BASE_URL="http://127.0.0.1:8096/claude-code/default"
export ANTHROPIC_AUTH_TOKEN="<business-user-key>"
export ANTHROPIC_MODEL="claude-2.1"  # Must match PROXY_UPSTREAM_MODEL

```

These variables are documented in the Installation guide at [`INSTALL.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/INSTALL.md) lines 48-53. The proxy intercepts requests to `/v1/messages` and processes them through the memory injection pipeline before forwarding to the upstream Anthropic endpoint.

### Environment Variable Setup Pattern

A minimal universal configuration using environment variables works across most agents:

```bash

# Proxy connection settings

export PROXY_URL="http://127.0.0.1:8096"
export PROXY_AGENT="claude-code"  # Change to: codebuddy, opencode, dsh, etc.

# Construct full base URL

export ANTHROPIC_BASE_URL="${PROXY_URL}/${PROXY_AGENT}/default"

# Authentication (obtain from Memory Hub)

export ANTHROPIC_AUTH_TOKEN="sk-mem-XXXXXXXXXXXXXXXXXXXXXXXX"

# Model configuration

export ANTHROPIC_MODEL="claude-2.1"

```

### Configuration File Locations by Agent

Different agents store their client configuration in specific files as documented in the `agents/` directory:

| Agent | Configuration Location | Format |
|-------|------------------------|--------|
| **CodeBuddy** | `~/.codebuddy/models.json` | JSON |
| **WorkBuddy** | `~/.workbuddy/models.json` | JSON |
| **Codex** | `~/.codex/config.toml` | TOML |
| **DeepSeek Harness** | `~/.dsh/settings.yaml` and [`.credentials.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/.credentials.yaml) | YAML |
| **OpenCode** | `~/.config/opencode/opencode.json` | JSON |
| **Hermes** | `~/.hermes/config.yaml` | YAML |
| **OpenClaw** | `~/.openclaw/openclaw.json` | JSON |
| **Pi (generic)** | Environment variables: `TDAI_PROXY_URL`, `TDAI_SPACE_ID`, `TDAI_TEAM_ID`, `TDAI_AGENT_ID`, `TDAI_USER_KEY`, `TDAI_MODEL`, optional `TDAI_TASK_ID` | Env vars |

For Codex, note that the first conversation turn requires *Plan* mode to properly initialize the session context.

## Request Flow and Memory Injection

When a properly configured client sends a request to MemoryProxy, the system executes a four-phase pipeline:

1. **Authentication** – Validates the `ANTHROPIC_AUTH_TOKEN` (or equivalent) against Memory Core.
2. **Session Initialization** – Either launches the interactive team/agent picker or uses pre-supplied `x-team-id`, `x-agent-id`, and `x-task-id` headers.
3. **Memory Injection** – Retrieves relevant L2/L3 memory segments, skills, and knowledge assets from Chat Memory, Wiki, and CodeGraph, then appends them to the system prompt.
4. **Upstream Forwarding** – Proxies the enriched request to `PROXY_UPSTREAM_URL` using the model name specified in `PROXY_UPSTREAM_MODEL`.

## Quick Start Checklist

To verify your client configuration is complete:

1. **Start the full stack** using [`./start-all.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/./start-all.sh) to generate the `.env` file containing proxy settings.
2. **Create a business user** via the Memory Hub API and record the returned `user_key`.
3. **Configure environment variables** or edit the agent-specific configuration file with the proxy URL and authentication token.
4. **Launch your agent** (e.g., `claude` or `codebuddy`) – the first turn will prompt you to select a Team, Agent, and optional Task, after which all subsequent turns automatically receive memory-enhanced prompts.

## Summary

- **Base URL format**: `http://<host>:8096/<agent-type>/default` where port 8096 is the standard MemoryProxy listener.
- **Authentication**: Use the `user_key` obtained from `POST /v3/meta/user/create` as your API token.
- **Context headers**: Supply `x-team-id`, `x-agent-id`, and `x-task-id` for non-interactive agents like Hermes and OpenClaw.
- **Configuration methods**: Environment variables for Claude Code and Pi, JSON/YAML files for CodeBuddy, WorkBuddy, and others.
- **Upstream model**: Must match the value set in `PROXY_UPSTREAM_MODEL` environment variable.

## Frequently Asked Questions

### What port does MemoryProxy listen on by default?

MemoryProxy binds to **port 8096** by default. Clients must include this port in the base URL (e.g., `http://127.0.0.1:8096/`) to reach the proxy endpoint rather than connecting directly to upstream LLM providers.

### Where do I obtain the authentication token for MemoryProxy?

Generate a business user through the Memory Hub by calling `POST /v3/meta/user/create`. The response includes a `user_key` value that serves as your `ANTHROPIC_AUTH_TOKEN` or equivalent API token for authenticating all proxy requests.

### Why does the first conversation turn ask me to select a team and agent?

MemoryProxy uses the initial request to initialize your session context. During this phase, it either displays an interactive picker to select `team-id`, `agent-id`, and optional `task-id`, or automatically resolves them if you pre-supply the `x-team-id`, `x-agent-id`, and `x-task-id` headers in your configuration. After initialization, subsequent turns proceed directly to the LLM with memory injection enabled.