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

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/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/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.

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/feat/server_team/sdk/memory-core/typescript/src/v3/skill-client.ts).

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.

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 utilizing IsolationContext, while SkillClient is defined in 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. 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, 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 for request and response structures like V3MemoryClientConfig. SkillClient uses src/v3/skill-types.js for skill-specific interfaces, reflecting the distinct data models required for skill CRUD operations versus core memory data structures.

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