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

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

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, 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 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:

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:

• 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 (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

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

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

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.
• 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.
• 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 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, 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.

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