Where Are the Core Components of TencentDB Agent Memory Located?

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): Provides functions for cleaning, tokenizing, and normalizing text before it enters the memory model.

• Stateful Pipeline Manager (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): Guarantees ordered execution of asynchronous tasks to prevent race conditions in memory updates.

• Pipeline Factory (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): Manages concurrency limits for pipeline workers, ensuring resource-efficient processing.

• Timer Scanner (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): Executes individual pipeline instances, handling error recovery and retry logic.

Configuration Files

The root of the MemoryCore package contains essential configuration:

• MemoryCore/package.json: Defines npm metadata and dependency lists for the core engine.

• 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: Routes incoming HTTP requests to appropriate memory operations.

• MemoryProxy/src/turnSeq.ts: Manages turn-sequence handling to maintain conversation context across API calls.

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

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

// 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.
• MemoryKnowledge (MemoryKnowledge/src/) manages the knowledge graph through services like 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 and 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 and pipeline-factory.ts, while the services subdirectory contains execution workers like pipeline-worker.ts and 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, with turn-sequence management handled by 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. 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.

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