# Where Are the Core Components of TencentDB Agent Memory Located?

> Discover the location of TencentDB Agent Memory core components. Find MemoryCore, MemoryProxy, and MemoryKnowledge packages on the feat/server_team branch to understand its architecture.

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

---

**The core components of TencentDB Agent Memory reside in three TypeScript packages under the `feat/server_team` branch: `MemoryCore` for the processing engine, `MemoryProxy` for the HTTP gateway, and `MemoryKnowledge` for the knowledge graph service.**

The TencentDB Agent Memory system is an open-source project maintained by TencentCloud that provides persistent memory capabilities for database agents. Located in the `TencentCloud/TencentDB-Agent-Memory` repository, the codebase is organized as a modular monorepo where each package handles distinct responsibilities. Understanding the exact file locations within these packages is essential for developers customizing the memory pipelines or integrating the system into existing infrastructure.

## Repository Architecture Overview

The project follows a clean separation of concerns across three primary packages. The `MemoryCore` package contains the fundamental memory processing logic, while `MemoryProxy` exposes these capabilities via HTTP endpoints, and `MemoryKnowledge` manages factual data storage and retrieval.

This architecture ensures that the core engine remains agnostic of transport protocols, allowing the memory logic to function independently of the API layer.

## MemoryCore: The Processing Engine

The `MemoryCore` package serves as the heart of the TencentDB Agent Memory system. It implements the pipeline infrastructure, state management, and utility functions required to process and store memory events.

### Utility Modules in `src/utils`

The `MemoryCore/src/utils` directory houses reusable helpers that handle text processing and pipeline orchestration:

- **Text Utilities** ([`MemoryCore/src/utils/text-utils.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/text-utils.ts)): Provides functions for cleaning, tokenizing, and normalizing text before it enters the memory model.

- **Stateful Pipeline Manager** ([`MemoryCore/src/utils/stateful-pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/stateful-pipeline-manager.ts)): Orchestrates sequential processing of memory events while preserving state across conversation turns.

- **Serial Queue** ([`MemoryCore/src/utils/serial-queue.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/serial-queue.ts)): Guarantees ordered execution of asynchronous tasks to prevent race conditions in memory updates.

- **Pipeline Factory** ([`MemoryCore/src/utils/pipeline-factory.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/pipeline-factory.ts)): Creates concrete pipeline instances based on runtime configuration, enabling dynamic pipeline construction.

### Service Workers in `src/services`

The `MemoryCore/src/services` directory contains worker implementations that drive the memory engine:

- **Worker Permit Pool** ([`MemoryCore/src/services/worker-permit-pool.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/services/worker-permit-pool.ts)): Manages concurrency limits for pipeline workers, ensuring resource-efficient processing.

- **Timer Scanner** ([`MemoryCore/src/services/timer-scanner.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/services/timer-scanner.ts)): Periodically triggers maintenance tasks, including the expiration of stale memory entries and cleanup operations.

- **Pipeline Worker** ([`MemoryCore/src/services/pipeline-worker.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/services/pipeline-worker.ts)): Executes individual pipeline instances, handling error recovery and retry logic.

### Configuration Files

The root of the `MemoryCore` package contains essential configuration:

- [`MemoryCore/package.json`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/package.json): Defines npm metadata and dependency lists for the core engine.

- [`MemoryCore/tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/tdai-gateway.yaml): Specifies default gateway configuration parameters used by the memory engine during initialization.

## MemoryProxy: The HTTP Gateway Layer

The `MemoryProxy` package acts as the API gateway that exposes the memory engine to external consumers, such as the WorkBuddy UI.

Key implementation files include:

- [`MemoryProxy/src/workbuddyHandler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/workbuddyHandler.ts): Routes incoming HTTP requests to appropriate memory operations.

- [`MemoryProxy/src/turnSeq.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/turnSeq.ts): Manages turn-sequence handling to maintain conversation context across API calls.

- [`MemoryProxy/src/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/types.ts): Contains TypeScript type definitions for the API contract.

These components translate HTTP requests into internal memory operations and format responses for client consumption.

## MemoryKnowledge: The Knowledge Graph Service

The `MemoryKnowledge` package handles persistent storage and retrieval of factual data through a knowledge graph implementation.

Primary source locations include:

- [`MemoryKnowledge/src/telemetry.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/telemetry.ts): Implements telemetry collection and monitoring for the knowledge service.

- `MemoryKnowledge/bin/server.mjs`: Entry point script for starting the knowledge service server.

- `MemoryKnowledge/bin/mcp.mjs`: Alternative entry point for MCP (Model Context Protocol) deployments.

This package operates independently from the core processing engine, providing a dedicated service for long-term factual storage.

## Working with the Core Components

Developers can import utilities directly from the `MemoryCore` package to build custom memory pipelines. The following examples demonstrate common usage patterns.

### Creating a Text Processing Pipeline

This example shows how to construct a pipeline using the factory and text utilities:

```typescript
// Example: creating a simple pipeline to process a user utterance
import { createPipeline } from './MemoryCore/src/utils/pipeline-factory';
import { processText } from './MemoryCore/src/utils/text-utils';

// Build a pipeline that normalizes text and passes it through a mock handler
const pipeline = createPipeline([
  (input: string) => processText(input),          // normalize
  async (normalized) => {
    // Simulate a memory operation
    console.log('Normalized:', normalized);
    return { result: `Echo: ${normalized}` };
  },
]);

// Run the pipeline
pipeline.run('  Hello,   World!  ').then(console.log);
// → { result: 'Echo: hello, world!' }

```

### Managing Concurrency with Worker Pools

To prevent resource exhaustion, use the `WorkerPermitPool` to limit concurrent pipeline executions:

```typescript
// Example: using the worker-permit pool to limit concurrent pipelines
import { WorkerPermitPool } from './MemoryCore/src/services/worker-permit-pool';

const pool = new WorkerPermitPool(3); // allow up to 3 concurrent workers

async function runTask(taskId: number) {
  await pool.acquire();           // wait for a free slot
  try {
    console.log(`Running task ${taskId}`);
    // ... perform pipeline work ...
  } finally {
    pool.release();               // free the slot
  }
}

// Launch several tasks; the pool throttles concurrency automatically
[1, 2, 3, 4, 5].forEach(runTask);

```

These patterns illustrate the essential operations available in the core: **pipeline creation**, **text preprocessing**, and **concurrency control**.

## Summary

- The **MemoryCore** package (`MemoryCore/src`) contains the essential processing engine with utilities in `src/utils/` and service workers in `src/services/`.
- **MemoryProxy** (`MemoryProxy/src/`) provides the HTTP gateway layer with request handlers like [`workbuddyHandler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/workbuddyHandler.ts).
- **MemoryKnowledge** (`MemoryKnowledge/src/`) manages the knowledge graph through services like [`telemetry.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/telemetry.ts) and entry scripts in `bin/`.
- All core components reside in the `feat/server_team` branch of the `TencentCloud/TencentDB-Agent-Memory` repository.
- Configuration files at [`MemoryCore/tdai-gateway.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/tdai-gateway.yaml) and [`MemoryCore/package.json`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/package.json) control engine initialization and dependencies.

## Frequently Asked Questions

### Where is the main processing logic located in TencentDB Agent Memory?

The main processing logic resides in the **MemoryCore** package, specifically within `MemoryCore/src/`. The `utils` subdirectory contains pipeline orchestration code including [`stateful-pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/stateful-pipeline-manager.ts) and [`pipeline-factory.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/pipeline-factory.ts), while the `services` subdirectory contains execution workers like [`pipeline-worker.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/pipeline-worker.ts) and [`worker-permit-pool.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/worker-permit-pool.ts).

### How does the repository expose the memory engine via HTTP?

The **MemoryProxy** package serves as the HTTP gateway. It exposes endpoints through handlers defined in [`MemoryProxy/src/workbuddyHandler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/workbuddyHandler.ts), with turn-sequence management handled by [`MemoryProxy/src/turnSeq.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/turnSeq.ts). This layer translates HTTP requests into internal memory operations without modifying the core engine logic.

### What handles concurrency and resource management in the core engine?

Concurrency is managed by the **WorkerPermitPool** class located at [`MemoryCore/src/services/worker-permit-pool.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/services/worker-permit-pool.ts). This service maintains a pool of permits that limit how many pipeline workers can run simultaneously, preventing resource exhaustion during high-load scenarios.

### Which branch contains the server implementation components?

All core components are located in the **`feat/server_team`** branch of the `TencentCloud/TencentDB-Agent-Memory` repository. This branch contains the `MemoryCore`, `MemoryProxy`, and `MemoryKnowledge` packages that constitute the complete server-side implementation.