Understanding the Four-Service Architecture of TencentDB Agent Memory

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 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
Memory Proxy	Request format translation and recall/capture hooks	MemoryProxy/src/server.ts, 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, while the heavy lifting of the memory-lifting pipeline happens in 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 — Wiki page search and CRUD operations.
• MemoryKnowledge/src/store/code-graph-service.ts — CodeGraph indexing and query support.
• 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, while the internal routing logic is in MemoryProxy/src/handler.ts. The agent-adapters subfolder provides per-agent adapters (e.g., 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. 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:

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):

// 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:

// 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:

// 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:

// 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	Entry point for all v2 REST endpoints
	MemoryCore/src/services/pipeline-worker.ts	Runs the L1→L2→L3 extraction pipeline
Memory Knowledge	MemoryKnowledge/src/store/wiki-service.ts	Wiki search and CRUD
	MemoryKnowledge/src/store/code-graph-service.ts	CodeGraph indexing & query
Memory Proxy	MemoryProxy/src/server.ts	HTTP receiver for agent requests
	MemoryProxy/src/agent-adapters/default.ts	Default "main-only" adapter
Memory Panel	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, 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, 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.

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