# How Threshold-Based Auto-Archiving Works for Skills in TencentDB Agent Memory

> Discover how threshold-based auto-archiving in TencentDB Agent Memory saves conversation data when limits like count, size, or tool usage are met. Optimize your agent's memory management.

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

---

**Threshold-based auto-archiving automatically persists buffered conversation messages to a versioned archive when any configured limit—conversation count, byte size, tool-call volume, or payload compression threshold—is exceeded.**

In the TencentCloud/TencentDB-Agent-Memory repository, the Core service treats each **Skill** as a stream of conversation messages buffered in memory. When this buffer grows past configured thresholds, the system creates a persistent archive and queues a `SkillConversationExtractWorker` task. This mechanism prevents unbounded buffer growth while ensuring conversation history is reliably captured for downstream processing.

## The Four Threshold Triggers That Force Archiving

The auto-archiving system monitors four distinct metrics defined in [`MemoryCore/src/core/skill/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/skill/types.ts). When any threshold is breached, the Core service immediately flushes the buffer and creates an archive.

### Conversation Count Threshold

The system tracks cumulative conversations in `state.conversation_count` within the `PipelineSessionState`. When this count reaches the `effectiveThreshold`, archiving triggers immediately.

The threshold employs a **warm-up strategy**: the system starts with a reduced threshold value that doubles on each archive until reaching the steady-state `everyNConversations` value configured in the Skill settings. This logic is implemented in [`MemoryCore/src/utils/pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/pipeline-manager.ts).

### Byte Size Limits

When accumulated request bytes exceed `bytesThreshold` (derived from the `archiveBytes` configuration), the Core service archives the buffer regardless of conversation count. This prevents memory pressure from large message payloads.

### Tool-Call Count Protection

Skills that invoke external tools accumulate tool calls in the buffer. If the cumulative number exceeds `toolCallsThreshold`, the system archives immediately to avoid overly large tool-call payloads that could degrade performance.

### Compressed Payload Handling

For individual requests exceeding `requestCompressThresholdBytes`, the Core compresses the payload. If the compressed data remains oversized, the system forces an immediate archive to maintain efficient memory usage.

## How the Core Service Evaluates Thresholds

The evaluation logic resides in [`MemoryCore/src/utils/pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/pipeline-manager.ts), which maintains a per-session `PipelineSessionState`. This state object records:

- Current `conversation_count`
- Active warm-up threshold value
- Accumulated byte and tool-call metrics

When the `/v3/skill/conversation/add` endpoint receives a request, the handler in [`MemoryCore/src/gateway/skill-handlers.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/skill-handlers.ts) updates the session state and calls `triggerArchiveIfNeeded()`. This function compares current metrics against the four thresholds using the `effectiveThreshold` calculation that accounts for warm-up progression.

## The Auto-Archiving Execution Flow

The archiving process follows a strict sequence implemented in [`MemoryCore/src/gateway/skill-handlers.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/skill-handlers.ts):

1. **Buffer Update**: The handler appends new messages to the session buffer and updates metrics in `PipelineSessionState`.
2. **Threshold Check**: `prepareArchivePayload` evaluates all four thresholds against current state.
3. **Archive Creation**: If triggered, `SkillTriggerService.archive()` persists the buffer as a versioned archive with a unique `archive_key`.
4. **Task Queuing**: The system creates a `SkillConversationExtractWorker` task for downstream processing.
5. **Client Notification**: The endpoint returns a response indicating the archive status.

The endpoint returns one of two statuses defined in [`MemoryCore/src/gateway/skill-schemas.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/skill-schemas.ts):

- **`status: "ok"`**: Messages appended successfully; buffer remains below all thresholds.
- **`status: "archived"`**: Buffer archived due to threshold breach; response includes `task_id`, `archive_key`, and `archived_at_ms`.

## Bypassing Thresholds with Force-Archive

Clients can explicitly trigger archiving without waiting for thresholds via the `/v3/skill/conversation/force-archive` endpoint. Implemented in [`MemoryCore/src/gateway/skill-handlers.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/skill-handlers.ts) (lines 1084-1085), this endpoint calls the same archive routine as the auto-path but skips all threshold checks.

This is useful for clearing stale buffers or forcing persistence before system maintenance.

## Implementation Examples

### Standard Conversation Addition with Auto-Archiving

```typescript
// Auto-archiving is automatic when thresholds are met
const response = await client.post('/v3/skill/conversation/add', {
  session_key: 'sess-123',
  messages: [{ role: 'user', content: 'Explain the new API' }],
});

// Response when below thresholds:
// { status: "ok" }

// Response when archived:
// {
//   status: "archived",
//   task_id: "task-a1b2c3",
//   archive_key: "skill-arch-2026-08-28",
//   archived_at_ms: 1724928000123
// }

```

### Manual Force-Archive

```typescript
// Skip threshold checks and archive immediately
const response = await client.post('/v3/skill/conversation/force-archive', {
  session_key: 'sess-123',
});

// Returns:
// {
//   status: "archived",
//   task_id: "...",
//   archive_key: "...",
//   archived_at_ms: ...
// }

```

### SDK Integration

The TypeScript SDK abstracts threshold handling 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):

```typescript
import { SkillClient } from '@tencentdb-agent-memory/memory-core';

const skill = new SkillClient(http);
const result = await skill.conversationAdd({
  session_key: 'sess-123',
  messages: [{ role: 'assistant', content: 'Here is the answer' }],
});

// result.status will be "ok" or "archived" based on threshold evaluation

```

## Summary

- **Four triggers** drive auto-archiving: conversation count, byte size, tool-call count, and compressed payload size, configured in [`MemoryCore/src/core/skill/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/skill/types.ts).
- **Warm-up logic** gradually increases the conversation threshold from an initial value to the steady-state `everyNConversations` setting via [`MemoryCore/src/utils/pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/pipeline-manager.ts).
- **Execution flow**: The `/v3/skill/conversation/add` handler updates `PipelineSessionState`, evaluates thresholds, and calls `SkillTriggerService.archive()` when limits are breached.
- **Immediate persistence**: The `/v3/skill/conversation/force-archive` endpoint bypasses all threshold checks to archive buffers on demand.
- **Downstream processing**: Every archive queues a `SkillConversationExtractWorker` task for conversation extraction and reuse.

## Frequently Asked Questions

### What happens if multiple thresholds are hit simultaneously?

The Core service triggers a single archive operation regardless of how many thresholds are breached. The `triggerArchiveIfNeeded()` function in [`MemoryCore/src/gateway/skill-handlers.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/skill-handlers.ts) checks all four conditions and initiates one atomic archive process, returning the `"archived"` status with a single `task_id` and `archive_key` representing the complete buffer state.

### How does the warm-up threshold calculation work?

According to the source code in [`MemoryCore/src/utils/pipeline-manager.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/pipeline-manager.ts), the system initializes new sessions with a reduced `effectiveThreshold` value. After each archive, this threshold doubles until reaching the configured `everyNConversations` steady-state value. This prevents premature archiving for short conversations while quickly ramping up to the desired interval.

### Can I disable auto-archiving for a specific skill?

No. The threshold-based auto-archiving is a protective mechanism built into the Core service. However, you can effectively disable automatic triggers by setting extremely high values for `archiveBytes`, `everyNConversations`, and `toolCallsThreshold` in the Skill configuration. For immediate control, use the `force-archive` endpoint to manage persistence timing manually.

### What is the difference between the "ok" and "archived" response statuses?

When the endpoint returns `status: "ok"`, the messages were appended to the active buffer without triggering thresholds. When it returns `status: "archived"`, the buffer exceeded one or more thresholds, the Core service created a persistent archive with a unique `archive_key`, and queued a `SkillConversationExtractWorker` task identified by `task_id`. The `archived_at_ms` timestamp records when the archive was committed.