# Understanding the Four-Service Architecture of TencentDB Agent Memory

> Explore the four-service architecture of TencentDB Agent Memory. Discover how its independent containers handle storage, retrieval, routing, and UI for efficient memory management.

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

---

**TLDR: TencentDB Agent Memory is built on a four-service architecture — Memory Core (Gateway), Memory Knowledge, Memory Proxy, and Memory Panel — that separates storage, retrieval, routing, and UI concerns into independently deployable containers communicating via a unified REST API.**

The [TencentCloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory) repository implements a production-grade memory layer for LLM-powered agents. Instead of a monolithic service, the project is decomposed into four distinct services, each with a single responsibility: the **Core Gateway** manages storage and the extraction pipeline, the **Knowledge** service provides searchable assets, the **Proxy** normalizes agent-specific request formats, and the **Panel** offers a human-facing web UI. This four-service architecture gives any LLM agent — whether CodeBuddy, Claude Code, WorkBuddy, or Hermes — a single HTTP endpoint for memory read/write operations without writing SDK code.

## An Overview of the Four-Service Architecture

The architecture is designed around a clear separation of concerns. Each service runs in its own container, uses its own storage where appropriate, and communicates through well-defined REST-style APIs. The services are:

- **Memory Core (Gateway)** — Central data store and pipeline worker that owns the vector database (TCVDB), COS object storage, and Redis state.
- **Memory Knowledge** — Provides searchable knowledge assets (Wiki pages, CodeGraph, Skills) layered on top of core data.
- **Memory Proxy** — A lightweight reverse proxy that translates agent-specific request formats into the unified Core API.
- **Memory Panel** — A human-centric control panel for project creation, asset binding, and ACL management.

| Service | Primary Role | Key Components |
|---|---|---|
| **Memory Core (Gateway)** | Central data store, pipeline worker, owns TCVDB/COS/Redis | `MemoryCore/src/api-trace/*`, `MemoryCore/src/services/*` |
| **Memory Knowledge** | Searchable Wiki, CodeGraph, and Skills assets | `MemoryKnowledge/src/store/*`, [`MemoryKnowledge/src/telemetry.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/telemetry.ts) |
| **Memory Proxy** | Request format translation and recall/capture hooks | [`MemoryProxy/src/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/server.ts), [`MemoryProxy/src/handler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/handler.ts) |
| **Memory Panel** | Web UI for projects, asset binding, ACLs | `MemoryPanel/web/src/*`, `MemoryPanel/docker/Dockerfile` |

All four services communicate through a shared API gateway URL (e.g., `http://localhost:8420`), simplifying client integration.

## Memory Core (Gateway): The Central Data Store

The **Memory Core** service serves as the gateway and pipeline worker. It owns all persistent storage layers — the TCVDB vector store, COS object storage for large files, and Redis for state management. Crucially, it runs the asynchronous L1→L2→L3 extraction pipeline that transforms raw conversations into structured memory.

The entry point for all v2 REST endpoints lives in [`MemoryCore/src/api-trace/api-traced-proxy.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/api-trace/api-traced-proxy.ts), while the heavy lifting of the memory-lifting pipeline happens in [`MemoryCore/src/services/pipeline-worker.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/services/pipeline-worker.ts). Every request from the other three services eventually lands here.

## Memory Knowledge: Searchable Intelligence Assets

The **Memory Knowledge** service builds searchable indexes on top of the core data. It exposes endpoints like `/v3/wiki/search` and `/v3/codegraph/query`, offering fast hybrid search combining BM25 keyword search with vector similarity.

Key implementation files include:

- [`MemoryKnowledge/src/store/wiki-service.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/store/wiki-service.ts) — Wiki page search and CRUD operations.
- [`MemoryKnowledge/src/store/code-graph-service.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/store/code-graph-service.ts) — CodeGraph indexing and query support.
- [`MemoryKnowledge/src/telemetry.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/telemetry.ts) — Observability and performance metrics.

This service translates the L2 scenario blocks (Wiki pages, CodeGraph sub-graphs) into assets that can be retrieved by agents through a natural-language-like query interface.

## Memory Proxy: The Universal Translator

The **Memory Proxy** is a lightweight HTTP reverse-proxy that normalizes requests from various agent APIs (OpenAI, Anthropic, Claude Code, OpenClaw, etc.) into the unified Core API format. It also performs **request-kind classification** (main vs. auxiliary) and injects recall/capture hooks by analyzing request flow.

The server entry is [`MemoryProxy/src/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/server.ts), while the internal routing logic is in [`MemoryProxy/src/handler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/handler.ts). The `agent-adapters` subfolder provides per-agent adapters (e.g., [`default.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/default.ts) implements the standard "main-only" adapter).

## Memory Panel (Web UI): Human-Centric Control

The **Memory Panel** is the user-facing web application. It allows teams to:

- Create projects and bind assets to agents.
- Review and manually edit Wiki pages, CodeGraph entries, and Skills.
- Manage access control lists (ACLs) per asset.

The UI is implemented in Vue, with the main component in [`MemoryPanel/web/src/App.vue`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/web/src/App.vue). The container is defined in `MemoryPanel/docker/Dockerfile`.

## How the Four Services Implement the L0 → L3 Memory Model

The entire platform is built on a deep layered memory model — spanning from raw conversations to long-term persona profiles.

The **Layered Memory Model**:

- **L0 Conversation** — Raw chat logs stored verbatim in COS.
- **L1 Atom** — Extracted facts, preferences, and constraints.
- **L2 Scenario** — Grouped knowledge blocks (Wiki pages, CodeGraph sub-graphs).
- **L3 Persona/Core** — Long-term profiles and reusable Skills.

The **Gateway** owns the raw L0 data and runs the asynchronous pipeline that lifts data through L1→L2→L3 layers. The **Knowledge** service then indexes the produced L2/L3 assets and provides fast search. The **Proxy** normalizes agent requests and ensures the recall/capture hooks integrate cleanly. The **Panel** manages what assets are bound to which agents.

## Practical Code Example: Communicating with the Four Services

Below is a minimal TypeScript example demonstrating how a client can interact with the four services using the published SDK, `@tencentdb-agent-memory/memory-sdk-ts-v2`.

**Set up**:

```ts
import { MemoryClient, MemoryFileReader } from '@tencentdb-agent-memory/memory-sdk-ts-v2';

const client = new MemoryClient({
  gatewayUrl: 'http://localhost:8420',   // Core Gateway endpoint
  apiKey: process.env.MEMORY_API_KEY,   // obtain from the Panel
  instanceId: 'default',
});

const fileReader = new MemoryFileReader({ gatewayUrl: 'http://localhost:8420' });

```

**Write raw conversation (L0)**:

```ts
// 1️⃣ - Store a conversation as L0 memory
await client.addConversation({
  sessionId: 'sess-123',
  messages: [
    { role: 'user', content: 'How do I enable TLS?' },
    { role: 'assistant', content: 'You can set `tlsEnabled=true`...' },
  ],
});

```

**Retrieve L1 atomic facts**:

```ts
// 2️⃣ - Search for L1 atoms via the Knowledge service
const atoms = await client.searchAtomic({
  query: 'tls',
  maxResults: 5,
});
console.log('L1 atoms →', atoms);

```

**Fetch an L2 Wiki page from COS**:

```ts
// 3️⃣ - Directly read a Wiki scene block (COS object key)
const page = await fileReader.read({
  path: 'scene_blocks/tls-setup.md',
});
console.log('Wiki page content →', page);

```

**Invoke a tool through the Proxy**:

```ts
// 4️⃣ - Call the memory search tool exposed by the Proxy
import { tdai_memory_search } from '@tencentdb-agent-memory/memory-sdk-ts-v2/tools';

const searchResult = await tdai_memory_search({
  query: 'database connection pooling',
  topK: 3,
});
console.log('Memory search result →', searchResult);

```

This single client manages all interactions — writing to Core Gateway, reading from the Knowledge service, fetching raw COS files, and using Proxy-exposed tools — without knowing the internals of each service.

## Key Source Files Worth Exploring

For those who want to dig into implementation details, the table below lists the most important files inside each service directory:

| Service | Important Source File(s) | Purpose |
|---|---|---|
| **Memory Core** | [`MemoryCore/src/api-trace/api-traced-proxy.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/api-trace/api-traced-proxy.ts) | Entry point for all v2 REST endpoints |
| | [`MemoryCore/src/services/pipeline-worker.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/services/pipeline-worker.ts) | Runs the L1→L2→L3 extraction pipeline |
| **Memory Knowledge** | [`MemoryKnowledge/src/store/wiki-service.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/store/wiki-service.ts) | Wiki search and CRUD |
| | [`MemoryKnowledge/src/store/code-graph-service.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/store/code-graph-service.ts) | CodeGraph indexing & query |
| **Memory Proxy** | [`MemoryProxy/src/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/server.ts) | HTTP receiver for agent requests |
| | [`MemoryProxy/src/agent-adapters/default.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/agent-adapters/default.ts) | Default "main-only" adapter |
| **Memory Panel** | [`MemoryPanel/web/src/App.vue`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/web/src/App.vue) | Main UI component |
| | `MemoryPanel/docker/Dockerfile` | Container image definition |

## Summary

- The **four-service architecture of TencentDB Agent Memory** consists of **Core ↔ Knowledge ↔ Proxy ↔ Panel**, each isolated in its own container.
- **Memory Core** owns the vector database, COS, and Redis, and runs the L0→L3 extraction pipeline.
- **Memory Knowledge** provides fast BM25 + vector search over Wiki pages, CodeGraph, and Skills.
- **Memory Proxy** normalizes various agent request formats and injects recall/capture hooks.
- **Memory Panel** gives a Vue-based UI for project/asset/ACL management.
- All services communicate through a single gateway URL, enabling zero-code agent integration.

## Frequently Asked Questions

### What does the "four-service architecture" of TencentDB Agent Memory refer to?

It refers to the software decomposition of the repository into four independent services: **Memory Core (Gateway)**, **Memory Knowledge**, **Memory Proxy**, and **Memory Panel**. Each runs in its own container and handles one exclusive responsibility — storage/pipeline, search, request translation, and UI management respectively.

### Which service is responsible for the conversation-to-atom extraction pipeline?

The **Memory Core (Gateway)** service runs the extraction pipeline. In [`MemoryCore/src/services/pipeline-worker.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/services/pipeline-worker.ts), the code asynchronously processes L0 conversation datagrams and lifts them through L1 atoms, L2 scenarios, and L3 persona profiles using the underlying TCVDB vector store and COS object storage.

### Can an LLM agent interact with all four services without writing custom code?

Yes. The **Memory Proxy** service specifically exists to translate any agent's native request format (OpenAI, Anthropic, Claude Code, OpenClaw) into the unified Core API. Agents communicate with the proxy endpoint (e.g., `http://localhost:8420`) and memory read/write operations happen transparently — no agent-specific code is needed in the host application.

### How do I provision users and ACLs in the system?

Through the **Memory Panel** web UI. In [`MemoryPanel/web/src/App.vue`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/web/src/App.vue), teams can create projects, import codebases, documents, and sessions, bind assets to agents, and manage access control lists (ACLs) per namespace. The Panel then communicates those changes to the other services via the shared REST API.