# How to Integrate TencentDB Agent Memory with TencentDB

> Integrate TencentDB Agent Memory with TencentDB by deploying core services and pointing your LLM agent to the OpenAPI endpoint for seamless access to Chat Memory, Skills, and more.

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

---

**To integrate TencentDB Agent Memory with TencentDB, deploy the Memory Core, Memory Hub, and Memory Proxy services, then point your LLM agent to the unified OpenAPI endpoint at `http://localhost:8125/v3/tools/*` to retrieve Chat Memory, Skills, Wiki, and CodeGraph assets via standard HTTP requests.**

TencentDB Agent Memory (TDAM) is an open-source memory layer developed by TencentCloud that enables LLM-powered tools to persist and reuse contextual assets. The system exposes a **memory-hub + proxy** architecture that requires zero code changes to your existing agents, allowing seamless integration with TencentDB workflows through RESTful endpoints defined in [`MemoryProxy/src/handler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/handler.ts).

## Architecture Overview

The integration relies on three distinct components that work together to provide a unified interface for asset retrieval:

- **Memory Core** – Stores raw assets and executes background pipelines for Wiki generation and CodeGraph indexing. The pipeline logic is implemented in [`MemoryCore/src/utils/stateful-pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/stateful-pipeline-manager.ts).

- **Memory Hub** – Provides the UI panel and REST API for creating assets, managing ACLs, and binding resources to specific teams. Configuration details are documented in [`MemoryKnowledge/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/README.md).

- **Memory Proxy** – A thin HTTP proxy that exposes the unified OpenAPI (`/v3/tools/*`) and routes requests to the appropriate backend. Runtime configuration is parsed in [`MemoryProxy/src/config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/config.ts).

This architecture decouples your agent from the underlying storage, allowing any tool that can make HTTP requests to integrate with TencentDB Agent Memory.

## Prerequisites and Deployment

Before integrating, you must deploy all three services using the provided orchestration script:

```bash
./deploy/global-images/start-all.sh

```

This script initializes the containers and outputs a ready-to-use configuration snippet, typically setting the Proxy to listen on `http://localhost:8125`. The Proxy acts as the single entry point for all agent interactions, handling authentication via the `auth` module ([`src/auth.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/auth.ts)) before routing to internal services.

## Step-by-Step Integration Guide

### Deploy the Three Services

Run the deployment script from the repository root to start the Memory Core, Memory Hub, and Memory Proxy containers. The script configures default ports and internal networking, printing a one-liner configuration for Claude and other supported agents upon completion.

### Configure the Proxy Endpoint

Update your agent's configuration to use the Proxy as its base URL. No SDK installation is required—simply set the endpoint to `http://localhost:8125` (or your configured `PROXY_URL`). The Proxy intercepts requests and rewrites them to the internal Core service, enabling **zero-code integration** for existing tools.

### Discover Available Assets

Query the proxy to retrieve the catalog of accessible memory assets:

```bash
curl -X GET http://localhost:8125/v3/tools/list

```

This endpoint returns all registered tools—including Chat Memory, Skills, Wiki pages, and CodeGraph symbols—that the authenticated user is authorized to access. The discovery mechanism is handled by [`MemoryProxy/src/injection/registry.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/injection/registry.ts), which dynamically registers each asset type as a callable tool.

### Invoke Memory Tools

Execute a specific asset by calling the unified action endpoint:

```bash
curl -X POST http://localhost:8125/v3/tools/call \
  -H "Content-Type: application/json" \
  -d '{
        "tool": "wiki_search",
        "args": { "query": "authentication design" },
        "metadata": { "user": "alice@example.com" }
      }'

```

The Proxy routes this request to the appropriate handler (Wiki, CodeGraph, or Skill) and streams the response back to your agent.

### Configure ACL Bindings

Restrict asset visibility by binding specific resources to agents or roles. Use the Memory Hub UI or the REST API defined in [`MemoryHub/openapi.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryHub/openapi.yaml) to assign ACLs. When bindings are active, the `/v3/tools/list` endpoint filters results to show only authorized assets for the requesting identity.

## Technical Implementation Details

### Configuration and Runtime

All Proxy runtime options are centralized in [`MemoryProxy/src/config.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/config.ts). This module parses command-line arguments and environment variables (from `.env` files) to construct the final configuration object used throughout the server.

### Request Routing

The main entry point [`MemoryProxy/src/handler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/handler.ts) implements the HTTP router that dispatches `/v3/tools/*` requests to specialized handlers. Each asset type (skills, wiki, codegraph) has a dedicated route that validates the payload against the registry before execution.

### Tool Registration

New capabilities are added via [`MemoryProxy/src/injection/registry.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/injection/registry.ts), which maintains the tool catalog exposed to agents. Built-in agents like Claude Code, Codex, and WorkBuddy live under `src/agent-adapters/*` (e.g., [`claude-code.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/claude-code.ts), [`codex.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/codex.ts)). Each adapter implements the `AgentAdapter` interface, allowing the Proxy to automatically expose new tools via the discovery endpoint without additional configuration.

## Integration Code Examples

### Querying via cURL

Fetch a Wiki page or search CodeGraph symbols using standard HTTP requests:

```bash
curl -X POST http://localhost:8125/v3/tools/call \
  -H "Content-Type: application/json" \
  -d '{
        "tool": "codegraph_lookup",
        "args": { "symbol": "MemoryCore/src/utils/short-id.ts" },
        "metadata": { "user": "bob@example.com" }
      }'

```

### Node.js Client Implementation

Implement a reusable client to interact with the Memory Proxy:

```javascript
import fetch from "node-fetch";

const PROXY_URL = "http://localhost:8125";

async function callTool(tool, args, user) {
  const resp = await fetch(`${PROXY_URL}/v3/tools/call`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      tool,
      args,
      metadata: { user },
    }),
  });
  return await resp.json();
}

// Retrieve a specific CodeGraph symbol
callTool("codegraph_lookup", { symbol: "MemoryCore/src/utils/short-id.ts" }, "bob")
  .then(console.log);

```

### Creating Custom Adapters

Extend the system by implementing a custom adapter in TypeScript:

```typescript
// src/agent-adapters/mytool.ts
import type { AgentAdapter } from "./types";

export const myToolAdapter: AgentAdapter = {
  name: "my_custom_tool",
  description: "Calls an external service and returns JSON",
  async handle(req) {
    const { url, payload } = req.args;
    const resp = await fetch(url, {
      method: "POST",
      body: JSON.stringify(payload),
      headers: { "Content-Type": "application/json" },
    });
    return await resp.json();
  },
};

// Register in src/agent-adapters/index.ts
import { myToolAdapter } from "./mytool";
registry.register(myToolAdapter);

```

After registration, `my_custom_tool` appears in `/v3/tools/list` and accepts invocations via `/v3/tools/call` alongside built-in assets.

## Summary

- **Deploy all three services** (Core, Hub, Proxy) using [`./deploy/global-images/start-all.sh`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/./deploy/global-images/start-all.sh) to enable the memory infrastructure.
- **Point agents to the Proxy** at `http://localhost:8125` to access the unified OpenAPI without modifying existing code.
- **Discover and invoke tools** via `/v3/tools/list` and `/v3/tools/call`, with routing handled by [`MemoryProxy/src/handler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/handler.ts).
- **Implement custom adapters** by following the `AgentAdapter` interface in `src/agent-adapters/*` to expose new capabilities.
- **Enforce access control** through the Hub UI or REST API to restrict asset visibility per user or team.

## Frequently Asked Questions

### Do I need to modify my existing agent's codebase to integrate with TencentDB Agent Memory?

No. The Memory Proxy implements a **zero-code integration** pattern. Any agent capable of making HTTP requests can communicate with the system by setting its base URL to the Proxy endpoint. The Proxy handles authentication, routing, and response formatting, requiring no SDK imports or library dependencies in your agent code.

### How does the Memory Proxy authenticate requests from external tools?

The Proxy authenticates requests via the `auth` module located at [`src/auth.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/auth.ts). It validates incoming credentials and injects the caller's identity into the request context, enabling per-user and per-team ACL enforcement throughout the pipeline managed by [`MemoryCore/src/utils/stateful-pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/stateful-pipeline-manager.ts).

### Can I restrict which memory assets specific agents or users can access?

Yes. The Memory Hub provides ACL management through its UI or the REST API documented in [`MemoryHub/openapi.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryHub/openapi.yaml). You can bind specific Chat Memory, Skills, Wiki pages, or CodeGraph symbols to particular agents or roles. Once configured, the `/v3/tools/list` endpoint automatically filters results to show only authorized assets for the requesting identity.

### How do I add support for a new LLM tool or custom agent to the system?

Create a new file in `src/agent-adapters/` that exports an object implementing the `AgentAdapter` interface, including `name`, `description`, and a `handle` method. Register the adapter in [`src/agent-adapters/index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/agent-adapters/index.ts) using the registry from [`MemoryProxy/src/injection/registry.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/injection/registry.ts). The Proxy will automatically expose the new adapter via `/v3/tools/list` within seconds of deployment.