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

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

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:

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:

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. 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 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. 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.
• 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 for the server logic and 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 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 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 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.

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