How to Configure the Memory Panel API for Custom Integrations

Configure the Memory Panel API by registering your instance in 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:

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

Edit 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 and is explicitly ignored by Git to prevent credential leakage. Detailed field descriptions are available in MemoryPanel/config/metadata-instances.README.md.

Configure Environment Variables

The Panel runtime, defined in 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:

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

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

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 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, 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, every POST request to /api/v1/... must include:

• x-tdai-service-id — The instance_id value from your 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:

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:

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.

Verify Connectivity

Before deploying integrations, confirm the Panel is healthy:

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 to 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.
• 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. 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 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.

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