# How the L0-L3 Memory Pipeline Is Triggered and Self-Warming Works in TencentDB Agent Memory

> Discover how TencentDB Agent Memory triggers the L0-L3 memory pipeline and utilizes self-warming to pre-cache data, reducing I/O latency and boosting performance.

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

---

**The L0-L3 memory pipeline is triggered by the `MemoryProxy` handler calling `InjectionPipeline.process` on every request, while the self-warming mechanism pre-executes eligible hooks during session initialization to cache L2/L3 data and eliminate I/O latency on subsequent calls.**

The TencentDB-Agent-Memory service implements a sophisticated tiered memory architecture (L0-L3) that injects contextual data into agent requests. Understanding how the L0-L3 memory pipeline is triggered and how its self-warming mechanism operates is critical for optimizing latency and cache hit rates. This article examines the source code to reveal the exact execution flow from HTTP request entry through session initialization to cached memory injection.

## Pipeline Trigger Mechanism

### Entry Point in MemoryProxy Handler

When an HTTP request arrives at the proxy, [`MemoryProxy/src/handler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/handler.ts) creates an `AgentContext` by invoking the appropriate protocol adapter (`adapter.parse`). Immediately after parsing, the handler instantiates the `InjectionPipeline` and calls its `process` method to begin memory injection.

```typescript
// Simplified handler invocation
import { InjectionPipeline } from "./injection/pipeline.js";

async function handleRequest(body, metadata) {
  const pipeline = new InjectionPipeline(
    globalHookRegistry,
    protocolAdapters,
    { hookCacheRepo: hookCacheRepo }   // enables pre‑warm cache reads
  );
  const result = await pipeline.process(body, metadata);
  return result;
}

```

### InjectionPipeline Execution Flow

As implemented in [`MemoryProxy/src/injection/pipeline.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/injection/pipeline.ts), the `InjectionPipeline.process` method orchestrates three distinct phases:

1. **Agent Profile Detection** – Identifies the relevant agent configuration and user context.
2. **Hook Execution** – Runs all registered injection hooks for each defined injection point.
3. **Serialization** – Converts the modified `AgentContext` back into the response format.

The pipeline accepts a `hookCacheRepo` in its constructor, enabling it to read pre-warmed blocks directly from cache rather than re-executing expensive L2/L3 retrieval logic.

## Self-Warming Mechanism for L0-L3 Memory

### Session Initialization Trigger

The pre-warm process is triggered immediately after session creation. Both the main handler ([`MemoryProxy/src/handler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/handler.ts)) and the **session-refresh** route ([`MemoryProxy/src/routes/session-refresh.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/routes/session-refresh.ts)) invoke `prewarmFromConfig` following the session-init step.

This function constructs a `PrewarmInput` object containing the session ID, user ID, agent source, and asset capabilities, then forwards it to the pre-warm runner.

```typescript
// Example: pre‑warming L3 persona for a newly created session
import { prewarmFromConfig } from "./injection/index.js";

async function onSessionInit(sessionInfo) {
  const input = {
    sessionInfo,
    userId: sessionInfo.user_id,
    agentSource: sessionInfo.agent_id,
    keyId: generateKeyId(),
    spaceId: sessionInfo.space_id,
    assetCapabilities: { chat_memory: true },
  };
  await prewarmFromConfig({ registry, hookCacheRepo }, input, { clearBefore: false });
}

```

### prewarmAll Execution Logic

The `prewarmFromConfig` function forwards the input to `prewarmAll`, defined in [`MemoryProxy/src/injection/prewarm.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/injection/prewarm.ts). This runner filters the global hook registry using the `shouldPrewarm` utility to identify hooks with `cacheStrategy` values of `"session_init"` or `"hybrid"`.

It then executes each eligible hook's `prewarm` method in parallel, respecting both per-hook timeouts and a global timeout threshold. The `shouldPrewarm` check ensures that only long-term memory hooks (L2/L3) requiring expensive computation are warmed, while on-demand L0/L1 hooks are skipped.

### HookCacheRepo Persistence

Successful pre-warm results are persisted to a `HookCacheRepo` implementation, typically backed by COS (Cloud Object Storage) or Redis. Subsequent requests read these cached blocks directly via the repository interface, bypassing the hook's `execute` method entirely until cache expiration or invalidation occurs.

## L3 Persona Injection Implementation

The `TdaiProfileMemoryInjector` in [`MemoryProxy/src/injection/injectors/tdai-profile-memory-injector.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/injection/injectors/tdai-profile-memory-injector.ts) exemplifies the L3 (Persona) layer implementation. According to line 32 of the injector, this hook declares `cacheStrategy: "session_init"`, making it eligible for the self-warming mechanism.

This hook implements both `execute` (fallback) and `prewarm` methods. During the `prewarm` phase, it builds the L3 persona and a lightweight L2 scene index once the session is registered, returning a single `ContextBlock`. Because this block is cached during warming, every subsequent request receives the L3 data without database queries or external I/O.

## Summary

- The **L0-L3 memory pipeline** triggers via `InjectionPipeline.process` in the MemoryProxy handler on every HTTP request.
- **Self-warming** activates during session initialization through `prewarmFromConfig`, which calls `prewarmAll` to execute eligible hooks before the first user message.
- Hooks declaring `cacheStrategy: "session_init"` or `"hybrid"` (like `TdaiProfileMemoryInjector`) generate and cache L2/L3 data during the warm phase.
- Cached blocks are stored in `HookCacheRepo` (COS/Redis) and injected directly into the `AgentContext`, eliminating retrieval latency for expensive long-term memory layers.

## Frequently Asked Questions

### What triggers the L0-L3 memory pipeline in TencentDB Agent Memory?

The pipeline is triggered when the `MemoryProxy` handler receives an HTTP request and calls `InjectionPipeline.process`. This occurs in [`MemoryProxy/src/handler.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/handler.ts) immediately after the protocol adapter parses the request into an `AgentContext`. The pipeline then executes all registered injection hooks to populate memory layers L0 through L3.

### How does the self-warming mechanism know which hooks to pre-execute?

The `prewarmAll` function in [`MemoryProxy/src/injection/prewarm.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/injection/prewarm.ts) uses the `shouldPrewarm` utility to filter hooks based on their `cacheStrategy` property. Only hooks configured with `"session_init"` or `"hybrid"` strategies are selected for pre-warming. This check happens before parallel execution begins.

### Where are pre-warmed memory blocks stored?

Pre-warmed blocks are persisted to a `HookCacheRepo` implementation, typically backed by COS (Cloud Object Storage) or Redis. This repository is injected into the `InjectionPipeline` constructor and is consulted before executing any hook's `execute` method, allowing cached L3 persona data to bypass expensive regeneration logic.

### What is the difference between a hook's `prewarm` and `execute` methods?

The `prewarm` method runs once during session initialization (when `cacheStrategy` permits) and writes its result to cache, while the `execute` method serves as a fallback that runs on-demand during the request pipeline if no cached value exists. For example, `TdaiProfileMemoryInjector` builds the L3 persona in `prewarm` for caching, but can regenerate it in `execute` if the cache expires.