# MemoryClient vs SkillClient in the TencentDB Agent Memory SDK: Key Differences Explained

> Understand MemoryClient vs SkillClient in TencentDB Agent Memory SDK. Learn how MemoryClient manages data operations and SkillClient handles skill management for your applications.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: deep-dive
- Published: 2026-08-26

---

**MemoryClient handles core data-plane operations with strict session isolation, while SkillClient provides a flexible wrapper for skill management endpoints with optional default parameters.**

The TencentDB-Agent-Memory repository provides a TypeScript SDK (`sdk/memory-core/typescript`) that exposes two distinct clients for interacting with the memory service. Understanding the difference between MemoryClient and SkillClient is critical for choosing the correct abstraction when building applications that leverage conversation memory, atomic operations, or skill-based knowledge retrieval.

## Core Architectural Responsibilities

### MemoryClient: Data-Plane and Session Management

`MemoryClient` serves as the low-level interface for core memory operations. Implemented in [[`src/v3/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/client.ts)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/sdk/memory-core/typescript/src/v3/client.ts), this client targets the `/v3` endpoint family and manages conversations, atomic counters, and scenario files. It enforces **strict isolation semantics** through an internal `IsolationContext` that requires explicit identification of the data boundary for every operation.

The constructor demands `teamId`, `agentId`, and `userId`, while write operations such as `addConversation` **must** include a non-empty `session_id`. The implementation throws a `ParamError` immediately if these isolation fields are missing, ensuring that data leakage across sessions is impossible at the client level.

### SkillClient: Skill Management and Flexible Defaults

`SkillClient` acts as a higher-level façade for the `/v3/skill/*` endpoint family. Defined in [[`src/v3/skill-client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/skill-client.ts)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/sdk/memory-core/typescript/src/v3/skill-client.ts), this client handles skill CRUD operations, file uploads, extraction jobs, and skill-specific conversation APIs. Unlike its counterpart, SkillClient treats isolation fields (`teamId`, `agentId`, `userId`, `taskId`) as **optional defaults** that are merged into each request payload.

The client does not enforce strict client-side validation for most calls. Instead, it relies on server-side validation, allowing developers to set baseline defaults at initialization while retaining the ability to override them per-request using the `withDefaults()` method.

## Isolation Semantics and Validation

### Strict Isolation in MemoryClient

MemoryClient implements a hard boundary between sessions. When calling `addConversation()`, the client validates that `session_id` is present and non-empty before transmitting the request. This design ensures that write operations cannot accidentally pollute the global memory space. Read operations, however, can omit `session_id` to aggregate data across sessions when explicitly needed.

### Default Merging in SkillClient

SkillClient uses a defaults-merging strategy. The constructor accepts an optional defaults object containing isolation identifiers, which are then shallow-merged into every request. This approach reduces boilerplate when managing multiple skills under the same team or agent context, while still permitting call-specific overrides via `withDefaults()`.

## Endpoint Coverage Comparison

| Feature | MemoryClient | SkillClient |
|---------|---------------|-------------|
| **Base Path** | `/v3` | `/v3/skill` |
| **Primary Operations** | Conversation management, atomic queries, scenario files | Skill creation, file handling, extraction |
| **Isolation Enforcement** | Client-side (`IsolationContext`) | Server-side with client-side defaults |
| **Session Requirements** | Mandatory `session_id` for writes | Optional (`taskId` for specific workflows) |
| **Error Handling** | Throws `ParamError` for missing isolation fields | Throws `ParamError` only for explicitly validated empty strings |

## Code Examples

### Working with MemoryClient (Strict Isolation)

The following example demonstrates initializing the client with required isolation fields and adding a conversation that is strictly bound to a specific session.

```typescript
import { MemoryClient } from '@tencentdb-agent-memory/memory-sdk-ts-v3';

const memory = new MemoryClient({
  endpoint: 'https://memory.tencentyun.com',
  apiKey: 'sk-***',
  serviceId: 'mem-xyz',
  teamId: 't1',
  agentId: 'agent-coder',
  userId: 'u42',
  sessionId: 'sess-001',               // required for writes
});

await memory.addConversation({
  messages: [{ role: 'user', content: 'Hello' }],
});

```

### Managing Skills with SkillClient (Flexible Defaults)

This example shows creating a skill using default isolation values provided at initialization, as implemented in [[`src/v3/skill-client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/skill-client.ts)](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/sdk/memory-core/typescript/src/v3/skill-client.ts).

```typescript
import { SkillClient } from '@tencentdb-agent-memory/memory-sdk-ts-v3';

const skills = new SkillClient({
  endpoint: 'https://memory.tencentyun.com',
  apiKey: 'sk-***',
  serviceId: 'mem-xyz',
  teamId: 't1',
  agentId: 'agent-coder',
  userId: 'u42',
});

const skill = await skills.create({
  name: 'code-assist',
  content: '---\nname: code-assist\n...',
});

```

### Overriding Defaults Per Call

SkillClient allows temporary overrides for specific operations without mutating the global instance state.

```typescript
await skills.withDefaults({ taskId: 'task-123' }).list({}); // taskId applied only to this call

```

## Summary

- **MemoryClient** provides low-level access to the data plane with **strict isolation** requirements, validating `teamId`, `agentId`, `userId`, and `session_id` client-side before transmission.
- **SkillClient** offers a higher-level interface for skill management with **flexible defaults**, merging optional isolation parameters into requests and delegating validation to the server.
- **Source Location**: MemoryClient resides in [`src/v3/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/client.ts) utilizing `IsolationContext`, while SkillClient is defined in [`src/v3/skill-client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/skill-client.ts) with default-merging logic.
- **Use MemoryClient** when directly manipulating conversation history or atomic memory structures; **use SkillClient** when creating, updating, or querying skill definitions and their associated files.

## Frequently Asked Questions

### Can I use MemoryClient and SkillClient together in the same application?

Yes. Both clients can coexist within the same application and share the underlying HTTP transport layer defined in [`src/v3/http.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/http.ts). They serve complementary purposes—use MemoryClient for raw memory operations and SkillClient for structured skill management.

### Why does MemoryClient require a session_id for writes while SkillClient does not?

MemoryClient enforces **strict session isolation** at the client level to prevent accidental cross-session data pollution, throwing `ParamError` if `session_id` is missing during `addConversation()` calls. SkillClient manages resources where isolation is often context-dependent or managed server-side, making `session_id` or `taskId` optional defaults rather than hard requirements.

### Which client should I use for querying conversation history?

Use **MemoryClient**. According to the source in [`src/v3/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/client.ts), read operations can omit `session_id` to aggregate across sessions, while specific session queries include it in the `IsolationContext`. SkillClient does not expose conversation history endpoints directly.

### Are the type definitions different between the two clients?

Yes. MemoryClient relies on type definitions in [`src/v3/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/types.ts) for request and response structures like `V3MemoryClientConfig`. SkillClient uses [`src/v3/skill-types.js`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/skill-types.js) for skill-specific interfaces, reflecting the distinct data models required for skill CRUD operations versus core memory data structures.