Understanding the Memory Proxy and Memory Hub in TencentDB Agent Memory

The Memory Hub functions as the core control plane that centrally stores all memory assets and enforces fine-grained ACLs, while the Memory Proxy serves as a lightweight gateway that normalizes agent-side APIs, handles authentication, and routes requests to the Hub.

The TencentDB-Agent-Memory repository implements a distributed architecture that separates persistent memory management from agent interaction layers. The system relies on two primary components—the Memory Proxy and Memory Hub—to provide secure, scalable access to Chat Memory, Skills, Wiki pages, and CodeGraph data. Understanding the distinct roles of these components is essential for deploying and integrating the memory system with AI agents.

What Is the Memory Hub?

The Memory Hub operates as the central control plane and authoritative data store for the entire TencentDB Agent Memory ecosystem. It maintains structured memory assets and exposes both web-based management interfaces and programmatic APIs for agent consumption.

Core Responsibilities

According to the source code in MemoryHub/src/api/*, the Hub handles four critical functions:

• Asset Repository: Stores all memory types including Chat Memory, Skills, Wiki pages, and CodeGraph structures in a centralized database.
• Access Control: Enforces fine-grained ACLs that determine which teams, members, and specific agents can read or modify individual assets.
• Lifecycle Management: Runs background pipelines that transform raw conversation logs, documents, and code into structured, searchable assets.
• Administrative Interface: Provides a web panel where teams create Teams, add Members, bind assets to specific Agents, and manage asset lifecycles.

Key Implementation Files

The Hub implementation centers on these critical paths within the repository:

• MemoryHub/docker-compose.yml – Defines the Docker composition for orchestrating the Hub service and its dependencies.
• MemoryHub/src/config.ts – Contains central configuration parameters including port definitions (default 8126), database connections, and ACL policies.
• MemoryHub/src/api/* – Houses the OpenAPI handlers that implement asset CRUD operations, semantic search endpoints, and ACL enforcement logic.

What Is the Memory Proxy?

The Memory Proxy acts as a lightweight façade and stable API gateway that agents interact with directly. It abstracts the complexity of the Hub’s internal APIs and provides a simplified, versioned interface for memory operations.

Gateway Responsibilities

As implemented in MemoryProxy/src/agent-adapters/*, the Proxy performs these essential functions:

• API Normalization: Translates agent-side calls into Hub-compatible requests, allowing the Hub’s internal API to evolve without breaking existing agent integrations.
• Authentication and Routing: Validates agent credentials and forwards authenticated requests to the appropriate Hub endpoints (typically localhost:8126).
• Performance Optimization: Implements request-level caching and optional rate-limiting to reduce load on the Hub and improve agent response times.
• State Management: Maintains lightweight SQLite persistence for proxy-level state in MemoryProxy/src/db/*.

Implementation Structure

The Proxy source code follows a modular architecture:

• MemoryProxy/src/agent-adapters/* – Contains protocol adapters that normalize requests from various agent frameworks into the Hub’s expected format.
• MemoryProxy/src/db/* – Manages local SQLite storage for caching and proxy-specific metadata.
• deploy/global-images/start-proxy.sh – Helper script that builds the Proxy container and initializes the service on port 8125.

How the Components Integrate

The Memory Proxy and Memory Hub communicate via HTTP to maintain a clean separation between agent-facing interfaces and data management internals.

Agents always target the Memory Proxy at http://localhost:8125, never communicating directly with the Hub’s internal API at http://localhost:8126. This architecture ensures that:

• Security: Authentication logic is concentrated in the Proxy layer, preventing direct exposure of Hub credentials to agent code.
• Stability: Hub API changes can be accommodated by updating Proxy adapters without modifying agent implementations.
• Scalability: Multiple Proxy instances can route to a single Hub, enabling horizontal scaling of agent gateways while maintaining a centralized memory store.

Practical Deployment and Usage

Starting the Complete Stack

Deploy both components using the provided orchestration scripts:

# From the repository root

cd deploy/global-images
cp .env.example .env          # Configure LLM credentials and database URIs

./start-all.sh                # Launches Memory Core, Hub (port 8126), and Proxy (port 8125)

Querying Memory Through the Proxy

Agents interact with the system via the Proxy’s stable API endpoint:

import fetch from 'node-fetch';

async function queryMemoryHub(query) {
  const resp = await fetch('http://localhost:8125/v3/tools/search', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query })
  });
  const data = await resp.json();
  console.log('Search results:', data);
}

queryMemoryHub('how to reset a MySQL password');

This request is authenticated by the Proxy, forwarded to the Hub’s search pipeline, and returns structured asset matches.

Direct Hub Access (Administrative)

While agents use the Proxy, administrative tools may access the Hub directly for asset management:

curl -X GET "http://localhost:8126/v3/assets/wiki/12345" \
     -H "Authorization: Bearer <hub-token>"

Note: Production agent implementations should always route through the Proxy (8125) rather than calling the Hub (8126) directly to ensure proper authentication and API compatibility.

Summary

• The Memory Hub is the authoritative control plane that stores all structured memory assets, enforces ACLs, and provides administrative interfaces via MemoryHub/src/api/*.
• The Memory Proxy is the agent-facing gateway that normalizes APIs, handles request routing, and caches responses, implemented primarily in MemoryProxy/src/agent-adapters/*.
• Communication Flow strictly routes agent requests through the Proxy (port 8125) to the Hub (port 8126), ensuring security and API stability.
• Deployment utilizes deploy/global-images/start-all.sh to orchestrate both services with Docker, using environment variables defined in .env for credentials and network configuration.

Frequently Asked Questions

What is the primary difference between the Memory Proxy and Memory Hub?

The Memory Hub serves as the core data plane that persistently stores memory assets and enforces access controls, while the Memory Proxy acts as a gateway abstraction layer that agents communicate with. The Proxy handles authentication, request normalization, and caching, ensuring agents remain isolated from Hub implementation details.

How do agents authenticate with the memory system?

Agents present credentials to the Memory Proxy at localhost:8125, which validates tokens and forwards authorized requests to the Hub. The Proxy manages the complexity of Hub authentication tokens internally, so agents do not require direct access to Hub credentials or knowledge of the Hub’s internal API structure at localhost:8126.

Can I run the Memory Proxy without the Memory Hub?

No, the Memory Proxy is a stateless gateway that depends on the Memory Hub for all data persistence. While the Proxy maintains lightweight SQLite state in MemoryProxy/src/db/* for caching and routing tables, all authoritative memory assets, ACLs, and search indexes reside exclusively in the Hub. The Proxy requires a running Hub instance to function.

Which configuration files control the default ports for each component?

The Hub listens on port 8126 as defined in MemoryHub/src/config.ts, while the Proxy binds to port 8125 as specified in its Docker configuration and the startup script deploy/global-images/start-proxy.sh. These ports can be modified via environment variables in deploy/global-images/.env before running start-all.sh.

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