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

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

// 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, 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) and the session-refresh route (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.

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

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