How Skills Are Created and Versioned in TencentDB Agent Memory: A Complete Technical Guide

Skills in TencentDB Agent Memory are immutable, versioned artifacts that start at version 1 and increment atomically through write operations requiring the current expected_version, with all historical snapshots retained in the SkillVersions table until they exceed the versionTtlSeconds retention window.

TencentDB Agent Memory models every Skill as an immutable artifact scoped to a team-agent context within the TencentCloud/TencentDB-Agent-Memory repository. When skills are created and versioned in TencentDB Agent Memory, the system assigns a unique skill_id and initializes the version counter at 1, enforcing strict optimistic concurrency controls for all subsequent modifications. Each write operation validates the provided expected_version before atomically incrementing the version number and persisting a new snapshot of the SKILL.md content and accompanying resources.

Understanding the Skill Lifecycle Architecture

The skill lifecycle follows a structured protocol designed to prevent race conditions and ensure complete auditability. All mutations occur through specific API endpoints that interact with the SkillVersions table, where every state change generates a new record rather than modifying existing data.

Initial Skill Creation (Version 1)

When you invoke POST /v3/skill/create through the TypeScript SDK or direct API call, the server initializes the artifact with the provided name, content (typically formatted as SKILL.md), optional resources, and metadata. As defined in src/v3/skill-types.ts, the response contains the generated skill_id and initial version metadata. This first snapshot automatically becomes the head version, marked with is_head: true in all query responses.

Atomic Updates Using Expected Version

Modifications occur through two primary mechanisms: POST /v3/skill/update for full content replacement and POST /v3/skill/patch for partial text substitution. Both endpoints require the expected_version parameter, representing the current head version you intend to supersede. According to the implementation in src/gateway/skill-schemas.ts and mirrored in the SDK, the server validates this value against the actual head version stored in the SkillVersions table. If the values match, the server increments the version counter and persists the new snapshot; if they diverge, the operation fails with error codes 40001 or 40301, signaling a concurrent modification conflict.

Archiving and Deletion

To remove a skill entirely, use POST /v3/skill/delete with the current expected_version. This archives or removes the entire skill lineage across all versions, not just the current iteration. The operation requires the same version validation to prevent accidental deletion of unexpectedly modified resources.

Version Storage and Retention Mechanics

The versioning system maintains complete history through dedicated types and retention policies that balance audit requirements with storage constraints.

The SkillVersions Table and Type Hierarchy

The SkillSummary type defines the core metadata fields including version (the numeric identifier) and is_head (boolean indicating the latest iteration). For historical queries, SkillVersionSummary extends SkillSummary to include the is_expired flag, as specified in src/v3/skill-types.ts. When retrieving specific points in history via POST /v3/skill/get, you optionally supply the version parameter; omitting it returns the current head. For bulk enumeration, POST /v3/skill/versions accepts SkillPagination parameters (limit, offset) to page through large version histories efficiently.

Expiration Policy and versionTtlSeconds

Versions transition to an expired state when their age exceeds the versionTtlSeconds configuration value. While expired versions remain queryable and appear in list results with is_expired: true, they become candidates for storage reclamation. The system never returns expired versions when requesting the head snapshot, ensuring active agents always receive current, supported skill definitions.

Implementing Version Control with the TypeScript SDK

The TencentDB Agent Memory TypeScript SDK abstracts the REST protocol through strongly-typed clients located in src/v3/skill-client.ts. These wrappers enforce required context fields and provide convenience methods for the complete skill lifecycle.

Client Initialization and Context

All operations require team_id, agent_id, and user_id context. The SkillClient validates these fields before transmission, though the server performs final authority checks. Initialize the client with your endpoint and default identifiers:

import { SkillClient } from './src/v3/skill-client';

const client = new SkillClient({
  baseUrl: 'https://memory.tencentcloud.com',
  defaults: { 
    user_id: 'u-123', 
    team_id: 't-abc', 
    agent_id: 'a-xyz' 
  },
});

Creating and Evolving Skills

Creating a skill initializes the version chain at 1, while updates require explicit version tracking:

// Create initial skill (version automatically set to 1)
await client.createSkill({
  name: 'data-processing',
  content: `---
name: data-processing
description: Process incoming telemetry
---
export function run() { return "processed"; }`,
});

// Update to version 2 by providing expected_version = 1
await client.updateSkill({
  skill_id: 'skl-001',
  expected_version: 1,
  content: `---
name: data-processing
description: Process telemetry with filtering
---
export function run() { return "filtered"; }`,
});

Retrieving Historical Versions

Access specific snapshots or enumerate the complete history with pagination:

// Retrieve latest head version
const latest = await client.getSkill({ skill_id: 'skl-001' });
console.log(latest.version); // 2
console.log(latest.is_head);  // true

// Access specific historical version
const v1 = await client.getSkill({ 
  skill_id: 'skl-001', 
  version: 1 
});

// List all versions with expiration status
const versions = await client.listSkillVersions({ 
  skill_id: 'skl-001', 
  pagination: { limit: 10 } 
});

versions.items.forEach(v => {
  console.log(`v${v.version} - expired: ${v.is_expired}`);
});

Summary

• Immutable Versioning: Every modification creates a new snapshot with an auto-incremented version number starting at 1, stored permanently in the SkillVersions table until expiration.
• Optimistic Concurrency Control: The expected_version parameter prevents lost updates by validating the client's view matches the server state before incrementing, returning errors 40001 or 40301 on mismatches.
• TypeScript Contracts: The SDK defines request/response schemas in src/v3/skill-types.ts and implements the convenience layer in src/v3/skill-client.ts, with validation schemas maintained in src/gateway/skill-schemas.ts.
• Retention and Expiration: Versions exceeding versionTtlSeconds are flagged with is_expired: true in SkillVersionSummary responses but remain accessible for audit purposes.
• Scoped Operations: All API calls require team_id, agent_id, and user_id context, ensuring strict isolation between different organizational units and agent instances.

Frequently Asked Questions

What happens if I provide the wrong expected_version when updating a skill?

The server rejects the request with error codes 40001 or 40301. This optimistic locking mechanism prevents concurrent writers from overwriting each other's changes. You must first retrieve the current head version using getSkill() to obtain the correct version number before attempting any update or patch operation.

Can I delete a specific version of a skill while keeping others?

No, the POST /v3/skill/delete endpoint archives or removes the entire skill lineage identified by skill_id. Individual versions cannot be selectively deleted through the public API. All versions remain accessible until they naturally expire based on the versionTtlSeconds retention policy, after which they may be purged from storage but remain listed with is_expired: true.

How do I perform a partial text update without replacing the entire skill content?

Use the POST /v3/skill/patch endpoint via SkillClient.patchSkill(), specifying the old_string to locate and new_string for replacement, along with the required expected_version. This executes a targeted text substitution within the existing content while still incrementing the version number and creating a new immutable snapshot in the SkillVersions table.

What distinguishes SkillSummary from SkillVersionSummary in the type system?

SkillSummary provides basic metadata including version and is_head status for general skill identification. SkillVersionSummary extends this type specifically for version enumeration operations (via POST /v3/skill/versions), adding the is_expired boolean field to indicate whether the specific version has exceeded the retention window defined by versionTtlSeconds.

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