# MemoryCore API Endpoint and Port: Configuration Guide for TencentDB-Agent-Memory

> Learn how to configure the TencentDB Agent MemoryCore API endpoint and port. Discover default settings and how to override them using environment variables for seamless integration.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: api-reference
- Published: 2026-08-27

---

**The MemoryCore API endpoint defaults to `127.0.0.1:8420` with a base URL of `http://127.0.0.1:8420`, and you can override these values via the `TDAI_GATEWAY_HOST` and `TDAI_GATEWAY_PORT` environment variables defined in the gateway configuration.**

The TencentDB-Agent-Memory repository provides a persistent memory layer for database agents through the MemoryCore service. Understanding the MemoryCore API endpoint and port configuration is essential for deploying and integrating this service into your infrastructure, whether for local development or production environments.

## Default MemoryCore API Endpoint and Port Configuration

### Gateway Configuration File

The primary configuration for the MemoryCore API endpoint resides in [`MemoryCore/tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/tdai-gateway.yaml). According to the TencentDB-Agent-Memory source code, this YAML file explicitly declares the default binding parameters that the HTTP server uses when starting up.

### Default Host and Port Values

Within [`MemoryCore/tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/tdai-gateway.yaml) at lines 27-28, the service is configured to bind to the loop-back address with the following defaults:

- **Host:** `127.0.0.1`
- **Port:** `8420`

This configuration creates the base URL `http://127.0.0.1:8420` for all API interactions. The official API documentation in [`MemoryCore/v3-api-memorycore-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md) (lines 3-4) confirms this setup, explicitly listing "MemoryCore（记忆内核），端口 `8420`" as the service identifier and port number.

## Customizing the MemoryCore API Endpoint and Port

While the default settings suit local development, production deployments typically require custom host and port configurations.

### Environment Variable Overrides

You can override the default MemoryCore API endpoint and port values using two environment variables:

- **`TDAI_GATEWAY_HOST`**: Specifies the IP address or hostname to bind to
- **`TDAI_GATEWAY_PORT`**: Specifies the TCP port number for incoming connections

These variables are read by the gateway implementation, allowing you to deploy the service on different interfaces or ports without modifying the YAML configuration file directly.

## Connecting to the MemoryCore API

The following examples demonstrate how to interact with the MemoryCore API using the default endpoint configuration.

### Health Check Endpoint

The health check endpoint requires no authentication and verifies that the service is running:

```bash
curl http://127.0.0.1:8420/health

```

### Adding Conversations via v3 API

To add a conversation to the memory store, send a POST request to the v3 endpoint with a Bearer token:

```bash
curl -X POST http://127.0.0.1:8420/v3/conversation/add \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <KERNEL_AUTH_TOKEN>" \
  -d '{
        "session_id": "sess_1",
        "messages": [{ "role": "user", "content": "Hello MemoryCore!" }]
      }'

```

### Querying L0 Messages with Pagination

Retrieve stored messages using pagination parameters:

```bash
curl -X POST http://127.0.0.1:8420/v3/conversation/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <KERNEL_AUTH_TOKEN>" \
  -d '{
        "session_id": "sess_1",
        "limit": 5,
        "offset": 0
      }'

```

## Implementation Details

### Gateway Server Implementation

The HTTP server that listens on the configured endpoint is implemented in [`MemoryCore/src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/server.ts). This file contains the logic for binding to the host and port specified in either the YAML configuration or the environment variables.

### API Documentation Reference

For comprehensive endpoint documentation, refer to [`MemoryCore/v3-api-memorycore-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md) in the TencentDB-Agent-Memory repository. This file documents the v3 API structure, authentication requirements, and available endpoints for the MemoryCore service.

### Deployment Documentation

For deployment instructions and additional configuration options, consult [`MemoryCore/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/README.md). This file provides comprehensive guidance on service setup and environment preparation according to the TencentDB-Agent-Memory repository standards.

## Summary

- The MemoryCore API endpoint defaults to `127.0.0.1:8420` as defined in [`MemoryCore/tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/tdai-gateway.yaml).
- The base URL for all API calls is `http://127.0.0.1:8420` unless overridden by environment variables.
- Use `TDAI_GATEWAY_HOST` and `TDAI_GATEWAY_PORT` to customize the endpoint without modifying configuration files.
- Authentication via Bearer token is required for all v3 endpoints, while the `/health` endpoint remains publicly accessible.
- Implementation files include [`MemoryCore/src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/server.ts) for the server logic and [`MemoryCore/v3-api-memorycore-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md) for API specifications.

## Frequently Asked Questions

### What is the default MemoryCore API port?

The default MemoryCore API port is **8420**. This value is hardcoded in the [`MemoryCore/tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/tdai-gateway.yaml) configuration file at line 28 and confirmed in the official API documentation. The service binds to this port on the loop-back interface (`127.0.0.1`) unless you specify otherwise.

### How do I change the MemoryCore API endpoint host?

Set the `TDAI_GATEWAY_HOST` environment variable to your desired IP address or hostname before starting the service. This override takes precedence over the default `127.0.0.1` value defined in the YAML configuration, allowing you to expose the service on network interfaces.

### Where is the MemoryCore API endpoint configured in TencentDB-Agent-Memory?

The endpoint configuration resides in [`MemoryCore/tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/tdai-gateway.yaml) within the TencentDB-Agent-Memory repository. Lines 27-28 specify the default host and port values, while the server implementation in [`MemoryCore/src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/server.ts) handles the actual binding logic at runtime.

### Is authentication required for all MemoryCore API endpoints?

No, authentication requirements vary by endpoint. The `/health` endpoint requires no authentication, making it suitable for monitoring and load balancer health checks. However, all v3 API endpoints (such as `/v3/conversation/add` and `/v3/conversation/query`) require a valid Bearer token in the Authorization header.