MemoryProxy Hooks Cache Strategies: None, Session_Init, and Hybrid Explained

The TencentDB-Agent-Memory repository defines three distinct cache strategies for MemoryProxy injection hooks—none, session_init, and hybrid—which control whether hook outputs are computed per turn, cached for an entire session, or both pre-warmed and runtime-cached.

The MemoryProxy module in TencentCloud/TencentDB-Agent-Memory manages AI context injection through an extensible hook framework. By configuring MemoryProxy hooks cache strategies, developers can eliminate redundant computations across conversation turns while maintaining precise control over data freshness and startup performance.

Cache Strategy Type Definition

According to the source code, the valid cache strategies are enumerated as a TypeScript union type in MemoryProxy/src/injection/types.ts:

export type CacheStrategy = "none" | "session_init" | "hybrid";

This type definition at lines 272–274 establishes the contract that all injection hooks must follow when declaring their caching behavior.

The Three Cache Strategies Explained

The pipeline respects three distinct caching behaviors that determine when and how hook results are stored.

None Strategy

The "none" strategy represents the default behavior when a hook omits the cacheStrategy property. In this mode, the hook executes on every single turn with no pre-warming or cache lookup performed. This strategy suits real-time data sources or lightweight operations where caching overhead would exceed computation costs.

Session_Init Strategy

The "session_init" strategy triggers execution once during the session-initialization phase. The pipeline stores the result in MemoryProxy/src/injection/prewarm.ts (lines 5–9) and subsequently reuses this cached output for the entire conversation session. This approach benefits expensive one-time computations—such as loading knowledge bases or user profiles—that remain static throughout the session.

Hybrid Strategy

The "hybrid" strategy combines pre-warming with per-turn cache access. Hooks marked with this strategy are executed during the pre-warm phase (like session_init) but can also read from and write to the runtime cache on a per-turn basis. As implemented in MemoryProxy/src/injection/pipeline.ts (lines 45–48), this enables both startup efficiency and dynamic result reuse across specific turns.

Pipeline Enforcement and File References

The cache strategy declaration directly controls execution flow in two critical pipeline stages.

Pre-warming Logic

In MemoryProxy/src/injection/prewarm.ts, the pipeline inspects each hook's cacheStrategy property at lines 5–9. Only hooks declaring "session_init" or "hybrid" trigger the hook.prewarm method. If a hook specifies "none" or omits the strategy entirely, the pre-warm phase skips that hook entirely, conserving initialization resources.

Runtime Execution

During active turn processing, MemoryProxy/src/injection/pipeline.ts handles cache reads and writes based on the declared strategy at lines 45–48. When the strategy is omitted, the pipeline treats it as "none" for backward compatibility, ensuring hooks execute fresh on every turn without cache interference.

Practical Implementation Examples

The following patterns demonstrate proper strategy selection for different use cases.

Session-Level Caching for Knowledge Bases

Use "session_init" when fetching static reference data that does not change during the conversation:

import type { InjectionHook } from "../types.js";

export const knowledgeListHook: InjectionHook = {
  id: "knowledgeList",
  point: "pre_prompt",
  priority: 10,
  cacheStrategy: "session_init",
  async run(ctx) {
    const list = await fetchKnowledge(); // Expensive operation
    return [{ type: "text", content: list.join("\n") }];
  },
};

Hybrid Caching for Dynamic Context

Use "hybrid" when you need both initial pre-warming and potential per-turn updates:

export const recentMessagesHook: InjectionHook = {
  id: "recentMessages",
  point: "pre_prompt",
  priority: 5,
  cacheStrategy: "hybrid",
  async run(ctx) {
    const msgs = await getRecentMessages(ctx.sessionId);
    return [{ type: "text", content: msgs }];
  },
};

Per-Turn Execution for Real-Time Data

Omit the strategy or explicitly set "none" for hooks that must execute fresh every turn:

export const liveMetricsHook: InjectionHook = {
  id: "liveMetrics",
  point: "post_response",
  priority: 20,
  // cacheStrategy defaults to "none"
  async run(ctx) {
    await sendMetrics(ctx);
  },
};

Summary

• Three strategies—none, session_init, and hybrid—control how MemoryProxy hooks interact with the caching layer.
• Type definition lives in MemoryProxy/src/injection/types.ts lines 272–274.
• Pre-warming in MemoryProxy/src/injection/prewarm.ts (lines 5–9) executes only session_init and hybrid hooks during session startup.
• Runtime execution in MemoryProxy/src/injection/pipeline.ts (lines 45–48) respects the strategy for cache reads/writes and defaults missing values to "none".
• Strategy selection should match data volatility: use none for real-time data, session_init for static session data, and hybrid for mixed requirements.

Frequently Asked Questions

What happens if I omit the cacheStrategy property in a MemoryProxy hook?

If you omit the cacheStrategy property, the pipeline defaults to "none" behavior. According to MemoryProxy/src/injection/pipeline.ts lines 45–48, the system treats undefined strategies as uncached for backward compatibility, executing the hook fresh on every turn without pre-warming or runtime cache lookup.

When should I choose hybrid over session_init for a hook?

Select "hybrid" when your hook benefits from pre-warming expensive initial computations but may need to update results or access the runtime cache during specific turns. The "session_init" strategy stores results only once at startup and never refreshes them, while "hybrid" enables both startup optimization and dynamic per-turn cache operations as implemented in the pipeline.

How does the pre-warm phase interact with these cache strategies?

The pre-warm phase, defined in MemoryProxy/src/injection/prewarm.ts lines 5–9, iterates through all registered hooks and calls hook.prewarm only for those declaring "session_init" or "hybrid" strategies. Hooks with "none" or undefined strategies are skipped entirely during initialization, preventing unnecessary computation for real-time data sources.

Can I change a hook's cache strategy dynamically during runtime?

No, the cache strategy is evaluated during the injection hook registration and session initialization phases. The CacheStrategy type is defined as a static string literal union in MemoryProxy/src/injection/types.ts, and the pipeline checks this value at pre-warm time and during turn execution without providing runtime mutation APIs.

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