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

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 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. 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, 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 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 and implemented in 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:

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:

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:

curl http://127.0.0.1:8420/health

Write a conversation to L0 memory:

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:

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:

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.
• 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.

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 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.

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