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

> Master prompt management with TencentDB Agent Memory! Learn to create, apply, clear, and use effective prompts with the Memory Prompt Client SDK for optimal LLM interaction.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: how-to-guide
- Published: 2026-08-31

---

**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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`

```typescript
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`

```typescript
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`

```typescript
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`

```typescript
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:

```typescript
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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/memory-prompt-client.ts) | Core implementation of `create()`, `apply()`, `clear()`, `getEffective()` |
| [`memory-prompt-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/memory-prompt-types.ts) | TypeScript definitions for `Layer`, `MemoryPromptSource`, request/response shapes |
| [`http.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/http.ts) | `V3HttpTransport` class handling low-level HTTP I/O |
| [`index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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.