# How to Configure the Memory Panel API for Custom Integrations

> Configure the Memory Panel API for custom integrations by registering your instance and authenticating requests. Expose your instance via the METADATA_INSTANCES_CONFIG environment variable for seamless integration.

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

---

**Configure the Memory Panel API by registering your instance in [`metadata-instances.json`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/metadata-instances.json), exposing it via the `METADATA_INSTANCES_CONFIG` environment variable, and authenticating requests with the `x-tdai-service-id` and `x-tdai-user-key` headers.**

The **Memory Panel** serves as the front-end gateway for the TencentDB-Agent-Memory repository, exposing a unified REST-style RPC API that external tools, CI pipelines, and custom bots can consume. To integrate your application with this team-memory service, you must properly configure the instance registry and authentication headers as implemented in the source code.

## Register Your Memory Instance

All external integrations begin with the instance registry file. The Memory Panel expects a JSON configuration that maps instance IDs to their respective gateway endpoints and API keys.

Create your configuration from the provided template:

```bash
cp MemoryPanel/config/metadata-instances.example.json MemoryPanel/config/metadata-instances.json

```

Edit [`MemoryPanel/config/metadata-instances.json`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/config/metadata-instances.json) to include your **instance ID**, **gateway endpoint**, and **API key** (the bearer token issued by the kernel). Optionally, add a `proxy_endpoint` if your architecture routes traffic through a separate proxy service.

According to the repository structure, this file lives at [`MemoryPanel/config/metadata-instances.json`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/config/metadata-instances.json) and is explicitly ignored by Git to prevent credential leakage. Detailed field descriptions are available in [`MemoryPanel/config/metadata-instances.README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/config/metadata-instances.README.md).

## Configure Environment Variables

The Panel runtime, defined in [`MemoryPanel/src/panel/config/panel-config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/src/panel/config/panel-config.ts), locates the registry file via the `METADATA_INSTANCES_CONFIG` environment variable.

Set the variable to point to your JSON file:

```bash
export METADATA_INSTANCES_CONFIG=/app/panel/config/metadata-instances.json

```

When running in Docker, mount the file as a read-only volume:

```bash
docker run -d \
  -p 8125:8125 \
  -e METADATA_INSTANCES_CONFIG=/app/config/metadata-instances.json \
  -v "$(pwd)/config/metadata-instances.json:/app/config/metadata-instances.json:ro" \
  tencentcloud/memory-panel:latest

```

The deployment scripts in [`deploy/panel-knowledge-combined/start-combined.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/deploy/panel-knowledge-combined/start-combined.sh) and `MemoryPanel/docker/local/Dockerfile.local` reference this variable during service initialization.

## Set Up Networking and Proxy Settings

If the kernel gateway requires proxy access, you have two configuration options. You can add a `proxy_endpoint` field directly in [`metadata-instances.json`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/metadata-instances.json), or set the `REMOTE_INSTANCE_PROXY_URL` environment variable. When the JSON configuration contains a proxy endpoint, the environment variable is ignored.

## Authenticate API Requests

All business endpoints (except health checks) require specific headers for authentication and routing. According to [`MemoryPanel/panel-api-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/panel-api-doc.md), every POST request to `/api/v1/...` must include:

- **`x-tdai-service-id`** — The `instance_id` value from your [`metadata-instances.json`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/metadata-instances.json) file
- **`x-tdai-user-key`** — A user-level API key distinct from the kernel `api_key`
- **`x-request-id`** — Optional tracing identifier
- **`Content-Type: application/json`**

The base URL for all API calls follows the pattern `http://<panel-host>:8125/api/v1`.

## Making Your First API Call

Once configured, you can interact with team-memory services. For example, to retrieve a team's chat-memory assets:

```bash
curl -X POST http://localhost:8125/api/v1/chat-memory/team-assets \
  -H "Content-Type: application/json" \
  -H "x-tdai-service-id: inst_1" \
  -H "x-tdai-user-key: <user-key>" \
  -d '{"team_id":"t_1"}'

```

For TypeScript applications, use the Memory Core SDK:

```typescript
import { MemoryPanelClient } from '@tencentcloud/memory-core';

const client = new MemoryPanelClient({
  baseUrl: 'http://localhost:8125/api/v1',
  serviceId: 'inst_1',
  userKey: process.env.TDIA_USER_KEY!,
});

async function listTeamMemories(teamId: string) {
  const resp = await client.post('chat-memory/team-assets', { team_id: teamId });
  console.log(resp.data);
}

```

All responses follow a standard envelope format containing `code`, `message`, `request_id`, and `data` fields as documented in [`MemoryPanel/panel-api-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/panel-api-doc.md).

## Verify Connectivity

Before deploying integrations, confirm the Panel is healthy:

```bash
curl http://localhost:8125/health

```

A successful response returns `{"status":"ok"}`. If the health check passes but API calls fail, verify that `METADATA_INSTANCES_CONFIG` points to valid JSON and that the `api_key` matches the kernel gateway's issued token.

## Summary

- **Instance registration** requires copying [`metadata-instances.example.json`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/metadata-instances.example.json) to [`metadata-instances.json`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/metadata-instances.json) and populating the `instance_id`, `gateway_endpoint`, and `api_key` fields.
- **Runtime configuration** depends on the `METADATA_INSTANCES_CONFIG` environment variable pointing to your registry file, as loaded by [`MemoryPanel/src/panel/config/panel-config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/src/panel/config/panel-config.ts).
- **Proxy support** can be set via the JSON file's `proxy_endpoint` field or the `REMOTE_INSTANCE_PROXY_URL` environment variable.
- **Authentication** requires the `x-tdai-service-id` and `x-tdai-user-key` headers on all POST requests to `/api/v1/*` endpoints.
- **Health verification** is available via the `GET /health` endpoint on port 8125.

## Frequently Asked Questions

### What file format does the Memory Panel expect for instance configuration?

The Panel expects a JSON file matching the schema defined in [`MemoryPanel/config/metadata-instances.example.json`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/config/metadata-instances.example.json). This file must contain an array of instance objects with `instance_id`, `gateway_endpoint`, and `api_key` properties. The file path must be exported via the `METADATA_INSTANCES_CONFIG` environment variable before starting the service.

### How do I secure the API keys when deploying with Docker?

Store the [`metadata-instances.json`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/metadata-instances.json) file outside version control (it is already listed in `.gitignore`) and mount it as a read-only volume into the container. Use the syntax `-v /host/path/metadata-instances.json:/app/config/metadata-instances.json:ro` to prevent the container from modifying the credentials at runtime.

### Why am I receiving authentication errors despite a healthy Panel?

Authentication errors typically indicate a mismatch between the `x-tdai-service-id` header and the `instance_id` in your JSON file, or an invalid `x-tdai-user-key`. Verify that the user key is active and that the `api_key` in your configuration matches the bearer token issued by the kernel gateway. Check the `METADATA_INSTANCES_CONFIG` path if the Panel cannot locate the registry file.

### Can I use environment variables instead of the JSON configuration file?

You must use the JSON file for instance registration, but you can configure proxy settings through the `REMOTE_INSTANCE_PROXY_URL` environment variable as a fallback. However, if `proxy_endpoint` is defined in the JSON file, it takes precedence over the environment variable according to the logic in [`deploy/panel-knowledge-combined/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/deploy/panel-knowledge-combined/README.md).