How to Customize LLM Extraction Prompts for L1/L2/L3 Memory in TencentDB Agent Memory

You customize LLM extraction prompts for L1 (structured memory), L2 (scenario files), and L3 (core persona) layers by creating prompts via the Memory Prompt API and binding them to specific teams or agents using the apply() method.

The TencentDB-Agent-Memory repository provides a multi-layered memory system where each layer uses distinct extraction prompts to guide the LLM's data processing behavior. Understanding how to customize LLM extraction prompts for L1/L2/L3 memory allows you to control exactly how the system extracts, structures, and stores information across different memory tiers.

Understanding the Memory Prompt API Architecture

The Memory Prompt API (/v3/memory-prompt/*) manages the full lifecycle of extraction prompts, from creation to binding. According to the source code in sdk/memory-core/python/tencentdb_agent_memory/v3/memory_prompt.py, the service exposes both synchronous (MemoryPromptClient) and asynchronous (AsyncMemoryPromptClient) Python clients, plus equivalent TypeScript implementations.

The three memory layers require different extraction strategies:

• L1 (Structured Memory): Extracts and formats discrete facts, entities, and relationships into structured storage
• L2 (Scenario Files): Processes situational context and conversation scenarios for retrieval
• L3 (Core Persona): Defines the persistent identity and behavioral guidelines for the agent

Binding Scope determines where prompts take effect. L1 and L2 prompts bind to a team + agent profile and operate independently of any session_id. L3 prompts describe the core persona and similarly attach to team and agent combinations. The helper method _target(team_id, agent_ids) in the SDK source enforces that agent-specific bindings only occur when a team context exists.

Creating and Binding Custom Extraction Prompts

The workflow follows a strict three-phase pattern: create, optionally update, then apply. After you customize LLM extraction prompts for L1/L2/L3 memory, you must bind them to targets before the system uses them for extraction operations.

Step 1: Create the Prompt

First, instantiate a client with your service credentials and default team context. Use the create() method to store the prompt content, specifying the target layer via the layer parameter ("L1", "L2", or "L3"). The prompt content is a plain string that the LLM receives unchanged, allowing you to embed runtime placeholders like {user_input}.

from tencentdb_agent_memory.v3.memory_prompt import MemoryPromptClient

client = MemoryPromptClient(
    endpoint="https://memory.tencentcloudapi.com",
    api_key="YOUR_API_KEY",
    service_id="memory-service",
    team_id="team-123",
)

# Create an L1 structured memory extraction prompt

response = client.create(
    name="structured-extraction-v2",
    layer="L1",
    prompt="""
You are a knowledge extractor. Given the user query and surrounding conversation,
return a concise, JSON-encoded list of relevant structured memory items.
Only output the JSON object, nothing else.
"""
)
prompt_id = response["memory_prompt_id"]

Step 2: Update Prompt Content

If you need to refine the extraction logic after creation, use the update() method with the memory_prompt_id returned from the previous step. This overwrites the prompt content while preserving the layer association.

client.update(
    memory_prompt_id=prompt_id,
    prompt="""
You are an advanced extractor. Return up to 5 JSON-formatted memory snippets
that best answer the user question. Do not add explanatory text.
"""
)

Step 3: Apply to Target Team or Agent

The critical final step uses the apply() method (which calls POST /v3/memory-prompt/set with action="apply"). Omitting agent_ids applies the prompt to all agents within the specified team. Supplying a list of agent_ids restricts the prompt to specific agents only.

# Apply to all agents in the default team

client.apply(
    memory_prompt_id=prompt_id,
    layer="L1"
)

# Apply to specific agents only

client.apply(
    memory_prompt_id=prompt_id,
    layer="L1",
    agent_ids=["agent-42", "agent-99"]
)

Implementation Details and Source Code References

Several implementation constraints in sdk/memory-core/python/tencentdb_agent_memory/v3/memory_prompt.py govern prompt behavior:

1. Layer Validation: The layer argument must be one of "L1", "L2", or "L3". Invalid values raise validation errors before the API call executes.

2. Target Enforcement: The internal _target() helper validates that agent_ids cannot be provided without a corresponding team_id. This ensures hierarchical consistency in the binding structure.

3. Stateless Storage: For L2 and L3 layers, prompts store once per team and agent combination. The system ignores session_id parameters for these layers, making prompts persistent across conversations.

4. Clearing Bindings: To remove a previously bound prompt, call the clear() method (which sends action="clear" to the same endpoint), effectively reverting to default extraction behavior.

Complete Code Examples

Python Synchronous Client

This example demonstrates creating an L2 scenario prompt and retrieving the effective configuration:

from tencentdb_agent_memory.v3.memory_prompt import MemoryPromptClient

client = MemoryPromptClient(
    endpoint="https://memory.tencentcloudapi.com",
    api_key="YOUR_API_KEY",
    service_id="memory-service",
    team_id="team-123",
)

# Create L2 scenario extraction prompt

resp = client.create(
    name="scenario-summarizer",
    layer="L2",
    prompt="Summarize the scenario file content in one sentence focusing on user intent.",
)
pid = resp["memory_prompt_id"]

# Bind to specific agent

client.apply(
    memory_prompt_id=pid,
    layer="L2",
    agent_ids=["agent-42"]
)

# Verify the active prompt

effective = client.get_effective(layer="L2")
print(effective["prompt"])

Python Asynchronous Client

For high-throughput applications, use AsyncMemoryPromptClient to customize LLM extraction prompts for L1/L2/L3 memory without blocking:

import asyncio
from tencentdb_agent_memory.v3.memory_prompt import AsyncMemoryPromptClient

async def configure_memory():
    client = AsyncMemoryPromptClient(
        endpoint="https://memory.tencentcloudapi.com",
        api_key="YOUR_API_KEY",
        service_id="memory-service",
        team_id="team-123",
    )

    # Create L3 persona definition prompt

    r = await client.create(
        name="core-persona-v1",
        layer="L3",
        prompt="""
You are a virtual assistant representing the user. Keep the persona short and
consistent. Return only the JSON representation of the persona.
"""
    )
    
    # Apply to all team agents

    await client.apply(
        memory_prompt_id=r["memory_prompt_id"],
        layer="L3"
    )
    
    await client.close()

asyncio.run(configure())

TypeScript Implementation

The TypeScript SDK in sdk/memory-core/typescript/ mirrors the Python functionality:

import { MemoryPromptClient } from "@tencentdb/memory-core";

const client = new MemoryPromptClient({
  endpoint: "https://memory.tencentcloudapi.com",
  apiKey: "YOUR_API_KEY",
  serviceId: "memory-service",
  teamId: "team-123",
});

async function setupExtraction() {
  // Create L3 persona prompt
  const { memory_prompt_id } = await client.create({
    name: "professional-persona",
    layer: "L3",
    prompt: `
You are a precise technical assistant. Maintain a formal tone.
Return persona metadata as compact JSON.
`
  });

  // Apply to entire team
  await client.apply({
    memory_prompt_id,
    layer: "L3",
  });
}

setupExtraction();

Summary

• Layer Definitions: L1 handles structured facts, L2 manages scenario context, and L3 defines core persona behavior in the TencentDB-Agent-Memory system.
• API Endpoints: Use /v3/memory-prompt/create to store prompts, /v3/memory-prompt/update to modify them, and /v3/memory-prompt/set with action="apply" to bind them to targets.
• Binding Scope: Prompts bind to team and agent combinations; L1/L2/L3 prompts persist independently of session_id.
• Client Libraries: MemoryPromptClient and AsyncMemoryPromptClient in sdk/memory-core/python/tencentdb_agent_memory/v3/memory_prompt.py handle validation, target enforcement, and HTTP communication.
• Content Format: Prompts are raw strings that support placeholder variables for runtime injection by the service.

Frequently Asked Questions

What is the difference between L1, L2, and L3 memory prompts?

L1 prompts guide extraction into structured memory, formatting facts and entities into searchable data structures. L2 prompts process scenario files, summarizing conversational context and situational background. L3 prompts define the core persona, establishing the agent's persistent identity and behavioral constraints. Each layer operates on different data types but follows the same binding mechanism through the Memory Prompt API.

Can I use the same prompt for multiple memory layers?

No, you cannot share prompt instances across layers. The layer parameter is immutable after creation and stored separately for L1, L2, and L3 contexts. If you need similar extraction logic across layers, you must create distinct prompt records for each layer value, though you may reuse the same prompt content string.

How do I revert to default prompts after applying a custom one?

Use the clear() method (or call POST /v3/memory-prompt/set with action="clear") to remove the binding between a custom prompt and a target team or agent. This operation resets the layer to use the system default extraction prompts rather than your customized version. You do not need to delete the prompt record itself unless you want to permanently remove it from storage.

Do custom prompts apply immediately to existing conversations?

Yes, prompt bindings take effect immediately for subsequent LLM extraction operations. However, because L1/L2 prompts bind to team and agent profiles without session_id dependency, they apply to all future extractions for that target. Existing data already stored in memory layers remains unchanged; only new extraction and indexing operations use the updated prompt logic.

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