# How to Add Conversation History Using the TypeScript SDK in TencentDB-Agent-Memory

> Easily add conversation history to your sessions with the TencentDB-Agent-Memory TypeScript SDK. Learn how to use the conversationAdd method to manage buffering and extraction triggers.

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

---

**The TypeScript SDK exposes the `conversationAdd` method in `SkillClient` to incrementally append conversation turns to a session buffer, returning `"archived"` when extraction triggers or `"ok"` when buffering continues.**

The TencentDB-Agent-Memory repository provides a TypeScript SDK for persisting and extracting skills from conversational AI interactions. Adding conversation history using the TypeScript SDK requires instantiating the `MemoryCoreClient` and invoking the `conversationAdd` method with properly isolated session identifiers and schema-compliant messages. The SDK automatically validates inputs locally and triggers asynchronous skill extraction when buffer thresholds are exceeded.

## Understanding the conversationAdd API

The `conversationAdd` method is implemented in [`sdk/memory-core/typescript/src/v3/skill-client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/skill-client.ts) (lines 94-101) and serves as the primary interface for appending conversation turns to the memory buffer.

### Required Isolation Fields

Every call to `conversationAdd` must include four required isolation fields to ensure proper namespacing and data separation:

- **`session_id`** – Unique identifier for the conversation session
- **`user_id`** – Identifier for the participating user
- **`team_id`** – Team or organization scope for the memory partition
- **`agent_id`** – Specific agent instance handling the conversation

The SDK validates these fields locally using `validateRequiredStrings` before transmitting the request.

### Message Schema Validation

The SDK enforces a strict five-role schema defined in [`skill-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/skill-types.ts) and validated against the server-side gateway schema in [`MemoryCore/src/gateway/skill-schemas.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/skill-schemas.ts). Each **SkillMessage** must specify exactly one of the following roles:

- `system` – System-level instructions and context
- `user` – Input messages from the end user
- `assistant` – Generated responses from the AI
- `tool_call` – Invocations of external tools
- `tool_result` – Results returned from tool executions

Before transmitting, the SDK runs `validateMessages` to ensure schema compliance, preventing malformed data from reaching the server.

## Step-by-Step Implementation

### Initialize the MemoryCoreClient

First, create an instance of `MemoryCoreClient` (defined in [`sdk/memory-core/typescript/src/v3/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/client.ts)) with your endpoint configuration and optional default isolation values:

```typescript
import { MemoryCoreClient } from '@tencentdb/memory-core-sdk';

const client = new MemoryCoreClient({
  baseURL: 'https://api.tencentyun.com',
  // Optional: set default team_id, user_id here if consistent across calls
});

```

### Prepare SkillMessage Arrays

Construct arrays of `SkillMessage` objects representing individual conversation turns. Each turn can contain multiple messages to capture full contextual exchanges:

```typescript
import { SkillMessage } from '@tencentdb/memory-core-sdk/types';

const turnMessages: SkillMessage[] = [
  { role: 'user', content: 'What is the weather in Beijing today?' },
  { 
    role: 'assistant', 
    content: 'The weather in Beijing is sunny with a high of 28°C.' 
  },
];

```

### Execute conversationAdd Calls

Invoke the method through the `skill` namespace, passing the isolation IDs and message array:

```typescript
import { SkillConversationAddRequest } from '@tencentdb/memory-core-sdk/types';

const addReq: SkillConversationAddRequest = {
  session_id: 'sess-12345',
  user_id: 'user-abc',
  team_id: 'team-xyz',
  agent_id: 'agent-001',
  messages: turnMessages,
};

const response = await client.skill.conversationAdd(addReq);

```

### Handle Response Status

Check the response status to determine if skill extraction occurred:

- **`"ok"`** – Messages buffered successfully; no extraction triggered yet
- **`"archived"`** – Buffer threshold reached; skill extraction task initiated automatically

When status is `"archived"`, the response includes a `task_id` field referencing the extraction job:

```typescript
if (response.status === 'archived') {
  console.log('Skill extraction initiated, task_id:', response.task_id);
}

```

## Batch Importing Historical Conversations

To replay existing dialog histories, iterate over stored turns and invoke `conversationAdd` sequentially. This ensures each historical turn passes through the SDK's validation and buffering pipeline:

```typescript
async function replayHistory(
  client: MemoryCoreClient, 
  history: SkillMessage[][], 
  isolationConfig: { session_id: string; user_id: string; team_id: string; agent_id: string }
) {
  for (const turn of history) {
    const resp = await client.skill.conversationAdd({
      ...isolationConfig,
      messages: turn,
    });
    
    if (resp.status === 'archived') {
      console.log(`Turn archived with task: ${resp.task_id}`);
    }
  }
}

```

## Key Source Files and Architecture

Understanding the source structure helps debug validation errors and extend functionality:

- **[`sdk/memory-core/typescript/src/v3/skill-client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/skill-client.ts)** – Implements `conversationAdd` and `conversationForceArchive` methods according to the TencentDB-Agent-Memory source code
- **[`sdk/memory-core/typescript/src/v3/skill-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/skill-types.ts)** – Defines `SkillMessage`, `SkillConversationAddRequest`, and response type definitions
- **[`sdk/memory-core/typescript/src/v3/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/client.ts)** – Provides the `MemoryCoreClient` class that exposes the `skill` namespace used for API calls
- **[`MemoryCore/src/gateway/skill-schemas.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/skill-schemas.ts)** – Contains the server-side JSON schemas that validate message structure and role definitions

## Summary

- The **TypeScript SDK** provides `conversationAdd` in `SkillClient` to buffer conversation turns and trigger skill extraction automatically when thresholds are met
- **Four isolation fields** (`session_id`, `user_id`, `team_id`, `agent_id`) are required for every call to ensure proper memory namespacing
- Messages must conform to the **five-role schema** (`system`, `user`, `assistant`, `tool_call`, `tool_result`) enforced by `validateMessages`
- **Local validation** occurs via `validateRequiredStrings` and `validateMessages` before network transmission to prevent invalid requests
- A response status of **`"archived"`** indicates the buffer reached its configured limit and a skill extraction task was created

## Frequently Asked Questions

### What are the required parameters for conversationAdd?

The `conversationAdd` method requires four isolation string fields (`session_id`, `user_id`, `team_id`, `agent_id`) and a `messages` array containing valid `SkillMessage` objects. The SDK validates these locally using `validateRequiredStrings` before sending requests to the server endpoint.

### How do I know when skill extraction is triggered?

When the accumulated buffer reaches configured size or byte thresholds, `conversationAdd` returns a response object with `status` set to `"archived"` and includes a `task_id` field. If the status is `"ok"`, the turn was buffered successfully without triggering extraction.

### Can I import existing conversation histories using the SDK?

Yes. Iterate over historical conversation turns chronologically and invoke `conversationAdd` for each turn sequentially. This replays the dialogue through the SDK's validation and buffering pipeline, treating historical data identically to real-time streams.

### What message roles does the TypeScript SDK support?

The SDK supports five specific roles defined in [`skill-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/skill-types.ts) and validated against the gateway schema: `system`, `user`, `assistant`, `tool_call`, and `tool_result`. Each message in the array must specify one of these roles, or the `validateMessages` function will throw a validation error before the request transmits.