How to Manage Prompts with the Memory Prompt Client: Create, Apply, Clear, and Effective Functions

Use the MemoryPromptClient TypeScript SDK to create prompt records, apply them to teams or agents, clear existing bindings, and retrieve the effective prompt that the LLM will actually receive.

The Memory Prompt Client is the primary interface for managing LLM prompts in the TencentDB Agent Memory platform. As implemented in TencentCloud/TencentDB-Agent-Memory, this client provides four essential operations—create, apply, clear, and effective—that control how prompt content flows through a layered hierarchy to your language models.

---

Understanding the Memory Prompt Client Architecture

The MemoryPromptClient lives in sdk/memory-core/typescript/src/v3/memory-prompt-client.ts and wraps HTTP calls via the V3HttpTransport class. It operates on a layered prompt model where prompts are stored per layer (l1, l2, l3), with higher layers shadowing lower ones when determining what the LLM ultimately sees.

All methods share common behaviors defined in the client:

• requireTarget (lines 34‑38): Validates that at least one target (teamId, agentIds, or instanceId) is specified
• requireText (lines 30‑33): Throws ParamError for empty required string fields
• stripUndefined (lines 27‑29): Cleans payloads by removing undefined values before transmission

---

Creating a New Prompt with create()

The create() method persists a new prompt record containing a name and content for a specific layer.

Source: memory-prompt-client.ts:72‑76

await client.create({
  name: "Helpful Assistant",
  prompt: "You are a helpful AI assistant. Answer concisely.",
  layer: "l2",  // Valid values: "l1" | "l2" | "l3"
});

The method returns a response containing the generated memory_prompt_id, which you'll use in subsequent apply() calls. This identifier is permanent until explicitly deleted.

---

Applying Prompts to Targets with apply()

The apply() method binds an existing prompt to a target—either an entire team, specific agents, or an instance—on a designated layer. This overrides any previous prompt association for that target on that layer.

Source: memory-prompt-client.ts:106‑116

await client.apply({
  memory_prompt_id: "prompt-xyz",
  layer: "l2",
  agent_ids: ["agent-001", "agent-002"],  // Omit for team-wide application
  // team_id: "override-team"  // Optional: override client default
});

Key characteristics:

• Target specificity: The backend resolves instance_id → agent_id → team_id → global, with more specific targets taking precedence
• Idempotent behavior: Repeated calls with the same parameters simply re-apply the same binding
• Single endpoint: Both apply() and clear() route to /v3/memory-prompt/set, distinguished by the action field ("apply" vs "clear")

---

Clearing Prompt Bindings with clear()

The clear() method removes a prompt association from a target, causing the system to fall back to the next-most-specific prompt in the hierarchy (or to defaults if none exists).

Source: memory-prompt-client.ts:18‑26

await client.clear({
  layer: "l2",
  agent_ids: ["agent-001", "agent-002"],  // Target to clear
  // Must match the target type used in the original apply() call
});

After clearing, the effective prompt for affected requests automatically recalculates based on remaining bindings in the hierarchy.

---

Retrieving the Effective Prompt with getEffective()

The getEffective() method resolves the actual prompt content that an LLM request will receive after evaluating the full hierarchy from instance through global layers.

Source: memory-prompt-client.ts:86‑90

const effective = await client.getEffective({
  layer: "l2",
  team_id: "team-abc",  // Required if not using client defaults
  // Optional for deeper resolution:
  // agent_id: "agent-001",
  // instance_id: "inst-456"
});

console.log("Effective prompt:", effective.prompt);
console.log("Source of prompt:", effective.source);  // Where this resolved from

This is the definitive method for debugging prompt behavior—call it before issuing LLM requests to verify exactly what instructions your model will receive.

---

Complete Working Example

Here's a unified demonstration of all four operations using default context:

import { MemoryPromptClient } from "sdk/memory-core/typescript/src/v3/index.js";

const client = new MemoryPromptClient({
  endpoint: "https://memory-api.tencentcloud.com",
  apiKey: process.env.MEMORY_API_KEY!,
  serviceId: "svc-123",
  teamId: "team-abc",  // Default team for all operations
});

async function managePromptWorkflow() {
  // 1. CREATE: Define reusable prompt content
  const created = await client.create({
    name: "Technical Support",
    prompt: "You are a PostgreSQL expert. Provide production-safe advice.",
    layer: "l2",
  });
  
  const promptId = created.memory_prompt_id;

  // 2. APPLY: Activate for specific agents
  await client.apply({
    memory_prompt_id: promptId,
    layer: "l2",
    agent_ids: ["agent-db-admin", "agent-migration"],
  });

  // 3. EFFECTIVE: Verify what agents will receive
  const effective = await client.getEffective({
    layer: "l2",
    agent_id: "agent-db-admin",  // Overrides default team context
  });
  console.assert(effective.memory_prompt_id === promptId);

  // 4. CLEAR: Remove when no longer needed
  await client.clear({
    layer: "l2",
    agent_ids: ["agent-db-admin", "agent-migration"],
  });
}

managePromptWorkflow().catch(console.error);

---

Key Source Files in TencentDB-Agent-Memory

File	Purpose
memory-prompt-client.ts	Core implementation of create(), apply(), clear(), getEffective()
memory-prompt-types.ts	TypeScript definitions for Layer, MemoryPromptSource, request/response shapes
http.ts	V3HttpTransport class handling low-level HTTP I/O
index.ts	Export barrel for clean SDK imports

---

Summary

• create() — Persist new prompt content to a layer; returns memory_prompt_id
• apply() — Bind prompt to team/agent/instance, overriding previous associations
• clear() — Remove binding, triggering hierarchy fallback
• getEffective() — Resolve the actual prompt content after hierarchy evaluation

All four methods validate inputs through requireTarget and requireText, strip undefined values via stripUndefined, and communicate with the /v3/memory-prompt/set (for mutations) and /v3/memory-prompt/get (for queries) endpoints.

---

Frequently Asked Questions

What happens if I apply a prompt to both a team and an agent?

The more specific target wins. According to the TencentDB-Agent-Memory resolution logic, instance_id outranks agent_id, which outranks team_id, which outranks global defaults. Call getEffective() with your specific target identifiers to verify the resolved prompt.

Can I apply the same prompt to multiple layers simultaneously?

No—each apply() call targets exactly one layer (l1, l2, or l3). To use the same content across layers, issue separate apply() calls with the same memory_prompt_id but different layer values. Each layer maintains independent binding state.

Why does clear() require the same target type as the original apply()?

The backend identifies bindings by the combination of layer + target specificity. Clearing agent_ids removes agent-level bindings but preserves team-level bindings (if any), allowing intentional partial rollbacks. Use getEffective() after clearing to confirm the new resolution state.

What's the difference between l1, l2, and l3 layers?

The layers represent organizational scope levels in your TencentDB deployment, with l3 being the most specific (typically instance-level) and l1 the broadest (global defaults). Higher-numbered layers shadow lower ones—an l3 binding beats an l2 binding for the same target. Always apply critical overrides to higher layers.

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