Client Configuration for Connecting to MemoryProxy: The Complete Setup Guide

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, 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:

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 lines 78-89.

Claude Code (Anthropic) Configuration

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

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 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:

# 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	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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}