# What Is TDAI Core? Architecture of TencentDB AI's Memory Engine

> Discover TDAI Core, the memory and metadata engine for TencentDB Agent Memory. Learn how it captures, indexes, and serves conversational memory through a unified HTTP gateway for agent integration.

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

---

**TDAI Core is the central memory-and-metadata engine of the TencentDB Agent Memory project that captures, indexes, and serves four layers of conversational memory while exposing a unified HTTP gateway for agent integration.**

The **TDAI Core** (alternatively referred to as **MemoryCore**) functions as the self-contained runtime backbone of the [TencentCloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory) repository. It orchestrates vector stores, embedding providers, and metadata services to provide deterministic memory operations for AI agents. By implementing a pipeline of services including skill extraction, quota management, and observability, TDAI Core isolates complex persistence logic from downstream consumers.

## TDAI Core Architecture and Components

### The Gateway Entry Point (`TdaiGateway`)

At the heart of the system lies the `TdaiGateway` class defined in [`MemoryCore/src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/server.ts). This class instantiates an HTTP server using Node.js's native `http` module and wires all REST endpoints for external communication. According to the source, the gateway initializes observability adapters, storage backends, and the skill module before binding to a configurable host and port (default `127.0.0.1:8420`).

The gateway serves as the sole entry point for adapters like OpenClaw or Hermes, exposing capabilities through TypeScript and Python SDKs.

### Memory Layer Hierarchy (L0–L3)

TDAI Core implements a four-tier memory architecture for conversational context:

- **L0 (Conversation)**: Raw conversation threads and turn-by-turn history
- **L1 (Atomic)**: Decomposed atomic facts and discrete memory units  
- **L2 (Scenario)**: Aggregated situational context and session summaries
- **L3 (Profile)**: Long-term user and agent profiles built from historical patterns

As documented in [`MemoryCore/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/README.md), these layers support multiple recall strategies including keyword search, embedding-based similarity, hybrid retrieval, and BM25 fallback mechanisms.

### Metadata Registry

Beyond conversation storage, the core manages two critical metadata domains:

1. **Knowledge Metadata**: Registry of identifiers, types, status flags, and service URLs for knowledge assets
2. **Asset Metadata**: Structured records for `User`, `Team`, `Agent`, `Task`, `Skill`, and `Knowledge Asset` entities

The metadata service maintains consistency through the [`v3-meta-router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/v3-meta-router.ts) implementation, providing isolated endpoints under `/v3/meta/*` for CRUD operations on these entities.

## API Endpoints and Integration

### REST API Surface

The gateway exposes a versioned REST API with the following primary endpoints defined in [`MemoryCore/src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/server.ts) and implemented in [`MemoryCore/src/gateway/v2-router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/v2-router.ts):

- `GET /health` – Liveness and readiness checks
- `POST /capture` – Write L0 conversation data  
- `POST /recall` – Pre-fetch relevant memories for the next turn using hybrid search
- `POST /search/memories` – Search L1 atomic memory units
- `POST /search/conversations` – Search L0 conversation history
- `POST /session/end` – Flush session state and persist pending writes
- `POST /seed` – Bulk import historical data for migration or initialization

### Skill Integration Hooks

TDAI Core creates a `SkillCore` instance during initialization and registers lifecycle hooks (`onSkillCreated`, `onSkillAccessed`, `onSkillArchived`) to synchronize skill assets with the metadata service. This integration, found in the gateway's initialization sequence, ensures that skill versioning and extraction status remain consistent across the system.

## Storage, Observability, and Deployment

### Persistence Layer

By default, TDAI Core persists structured data in **SQLite** and stores large objects in a local file directory. When operating in *service* mode, the system can swap in **Tencent Cloud Object Storage (COS)** for blob storage and Tencent Cloud Vector Database (TCVDB) for vector operations. The storage adapters are initialized in the gateway startup sequence based on the `TDAI_GATEWAY_CONFIG` environment variable.

### Observability Backends

Before the HTTP server starts, the gateway optionally initializes:

- **OpenTelemetry** for distributed tracing
- **Langfuse** for LLM operation tracking  
- **ClickHouse** for analytical queries

These backends are configured through environment variables and provide comprehensive telemetry for production deployments.

### Standalone vs. Service Mode

TDAI Core supports two operational profiles as implemented in the deployment mode handling logic:

- **Standalone**: Runs locally with SQLite and no external service dependencies, suitable for development and single-tenant scenarios
- **Service**: Runs as a sidecar in multi-tenant environments, requiring external metadata stores (MongoDB or SQLite), COS, and TCVDB for vector search

## Running TDAI Core Locally

### Installation and Configuration

To start a standalone TDAI Core instance, clone the repository and configure the environment:

```bash
cd MemoryCore
npm install
npm run build

export TDAI_GATEWAY_CONFIG="$PWD/tdai-gateway.standalone.yaml"
export TDAI_LLM_API_KEY="your-api-key"
export TDAI_LLM_BASE_URL="https://api.openai.com/v1"
export TDAI_LLM_MODEL="gpt-4o-mini"

```

Launch the gateway:

```bash
node --import tsx src/gateway/server.ts

```

The server binds to `127.0.0.1:8420` by default. For remote access, set `TDAI_GATEWAY_HOST="0.0.0.0"` and `TDAI_GATEWAY_API_KEY` to require Bearer token authentication.

### Example API Calls

Verify the deployment:

```bash
curl http://127.0.0.1:8420/health

```

Write a conversation to L0 memory:

```bash
curl -X POST http://127.0.0.1:8420/capture \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv-123",
    "turns": [{"role": "user", "content": "How do I back up a MySQL DB?"}],
    "metadata": {"team_id": "teamA", "agent_id": "agentX", "user_id": "userY"}
  }'

```

Recall relevant context:

```bash
curl -X POST http://127.0.0.1:8420/recall \
  -H "Content-Type: application/json" \
  -d '{
    "query": "backup strategy for MySQL",
    "team_id": "teamA",
    "agent_id": "agentX",
    "user_id": "userY"
  }'

```

### TypeScript SDK Usage

For programmatic access, use the provided SDK:

```typescript
import { MemoryCoreClient } from "../sdk/memory-core/typescript/src/client";

const client = new MemoryCoreClient({
  endpoint: "http://127.0.0.1:8420",
  apiKey: process.env.TDAI_GATEWAY_API_KEY,
});

await client.capture({
  conversation_id: "conv-123",
  turns: [{ role: "user", content: "Explain GC in MySQL" }],
  metadata: { team_id: "teamA", agent_id: "agentX", user_id: "userY" },
});

const recall = await client.recall({
  query: "MySQL garbage collection",
  team_id: "teamA",
  agent_id: "agentX",
  user_id: "userY",
});

```

When authentication is enabled, all requests (except `/health`) must include the header `Authorization: Bearer <TDAI_GATEWAY_API_KEY>` and `x-tdai-service-id: <memory-instance-id>`.

## Summary

- **TDAI Core** (MemoryCore) is the self-contained runtime engine that powers the TencentDB Agent Memory project, managing four hierarchical memory layers (L0–L3) and comprehensive metadata registries.
- The **TDAI Gateway** exposes functionality through a versioned REST API (`/capture`, `/recall`, `/search/*`) via the `TdaiGateway` class in [`MemoryCore/src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/server.ts).
- **Storage defaults** to SQLite with optional COS backend for service deployments, supporting both standalone development and multi-tenant production environments.
- **Observability** integrates OpenTelemetry, Langfuse, and ClickHouse for production monitoring.
- **Skill integration** uses lifecycle hooks to synchronize with metadata services, ensuring asset consistency across the platform.

## Frequently Asked Questions

### What are the four memory layers in TDAI Core?

TDAI Core organizes conversational memory into **L0 (Conversation)** for raw dialogue history, **L1 (Atomic)** for discrete facts, **L2 (Scenario)** for situational context, and **L3 (Profile)** for long-term user and agent characteristics. Each layer supports different retrieval strategies including keyword, embedding, and hybrid search with BM25 fallback.

### How does TDAI Core handle authentication?

Authentication is optional in standalone mode but required for remote deployments. When `TDAI_GATEWAY_API_KEY` is set, the gateway validates Bearer tokens in the `Authorization` header and requires the `x-tdai-service-id` header for multi-tenant isolation. The authentication check is implemented in the gateway's request handling pipeline in [`MemoryCore/src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/server.ts).

### What storage backends does TDAI Core support?

By default, TDAI Core uses **SQLite** for structured metadata and local filesystem storage for large objects. In service mode, it supports **Tencent Cloud Object Storage (COS)** for blobs and **TCVDB** (Tencent Cloud Vector Database) for embedding storage, configured via the [`tdai-gateway.standalone.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tdai-gateway.standalone.yaml) or corresponding service configuration files.

### Can TDAI Core run without external dependencies?

Yes. In **standalone** mode, TDAI Core operates as a single binary with only SQLite and local file storage, requiring no external vector databases or object storage. This mode, controlled by environment configuration, is suitable for development and lightweight deployments where `node:http` serves traffic directly without load balancers or sidecars.