What Are Skills in TencentDB Agent Memory and How Are They Versioned?

Skills in TencentDB Agent Memory are versioned, executable knowledge assets comprising a markdown document (SKILL.md), optional resource files, metadata, and immutable version history managed through a monotonic integer scheme with configurable TTL-based cleanup.

TencentDB Agent Memory treats skills as first-class assets that agents can store, retrieve, and execute. This architecture enables reproducible agent behavior, rollback capabilities, and efficient knowledge management at scale. Below is a comprehensive breakdown of the skill data model and its versioning mechanics as implemented in the TencentCloud/TencentDB-Agent-Memory repository.

Skill Structure and Components

Every skill consists of four core elements defined in skill-types.ts【/cache/repos/github.com/TencentCloud/TencentDB-Agent-Memory/feat/server_team/sdk/memory-core/typescript/src/v3/skill-types.ts】:

Component	Purpose
SKILL.md	Canonical markdown document with YAML front-matter (name, description, version) and instructional body content
Resources	Optional files stored under a files/ directory, tracked via SkillManifestEntry objects
Metadata	Arbitrary JSON object (metadata_json) attached to each version for custom extensions
Version Info	Immutable version records with version integer, is_head flag, and created_at_ms timestamp

The TypeScript SDK exposes these through 17 /v3/skill/* HTTP endpoints wrapped by skill-client.ts.

How Skill Versioning Works

TencentDB Agent Memory implements append-only, immutable versioning through the SkillVersioning class in skill-versioning.ts【/cache/repos/github.com/TencentCloud/TencentDB-Agent-Memory/feat/server_team/MemoryCore/src/core/skill/skill-versioning.ts】.

Creating the First Version (v1)

When SkillVersioning.createNewSkill() is invoked:

1. The caller supplies a unique skill_id
2. Resources upload to COS (Cloud Object Storage) via the storage adapter
3. A version row inserts into the skill DB via store.appendVersion
4. Optional onSkillCreated hook registers the asset in meta-assets
5. System reports +1 VDB delta via onSkillVdbChanged to Shark (usage tracking)

import { SkillClient } from "./sdk/memory-core/typescript/src/v3/skill-client";

const client = new SkillClient({
  teamId: "team-123",
  agentId: "agent-abc",
  userId: "user-xyz",
});

const createResp = await client.create({
  name: "DataAnalysisSkill",
  content: `---
name: DataAnalysisSkill
description: Analyzes sales CSV files
---

# Data Analysis Workflow

1. Load CSV from /data/sales.csv
2. Compute monthly aggregates`,
  resources: [
    {
      path: "files/analyze.py",
      content: "import pandas as pd\n...",
      encoding: "utf-8",
      mime_type: "text/x-python",
    },
  ],
});
console.log(createResp.skill_id, "v" + createResp.version);

The SkillCreateRequest type enforces this structure in skill-types.ts.

Appending Subsequent Versions

The append operation (expected_version → new head) follows this logic:

1. Fetch current head version
2. Idempotency check: If content_hash and resources are unchanged, return existing head
3. Otherwise, storage.copyTree duplicates the old version's directory
4. Apply resource changes (writeResource / removeResource)
5. Update manifest and insert new DB row via store.appendVersion
6. Promote to head; previous head becomes historical version

const head = await client.get({ skill_id: "skill-xyz" });
const updated = head.content!.replace("monthly", "weekly");

await client.update({
  skill_id: head.skill_id,
  expected_version: head.version,  // Optimistic concurrency
  content: updated,
  // resources: [...] // optional changes
});

Critical: The expected_version parameter prevents lost-update races. Mismatches return a concurrency error.

Version Retention and Expiration

TTL-based cleanup runs via SkillVersioning.cleanupExpiredVersionsForSkill():

• Each version has created_at_ms and configurable ttlSeconds
• Default retention: KEEP_RECENT = 3 non-head versions are preserved regardless of TTL
• Expired versions beyond this threshold trigger:
  1. DB row deletion
  2. Storage directory removal
  3. –1 VDB delta per deleted version

const versions = await client.versions({
  skill_id: "skill-xyz",
  pagination: { limit: 10 },
});
// SkillVersionSummary includes is_expired flag
versions.items.forEach(v => {
  console.log(`v${v.version} head=${v.is_head} expired=${v.is_expired}`);
});

Complete Skill Deletion

SkillVersioning.deleteSkill() performs atomic cleanup:

await client.delete({
  skill_id: "skill-xyz",
  expected_version: 5,  // Must match current head
});

This removes all versions, cleans all storage directories, and reports a single –N VDB delta.

Storage Architecture

Skill version data spans two layers:

Layer	Technology	Responsibility
Object Storage	COS adapter	files/ directory per version at storage_dir path
Skill Database	SQLite or TCVDB	Version rows with skill_id, version, content_hash, manifest, is_head, is_expired

The skill-store.interface.ts abstracts the database layer, while skill-resource-store.ts handles COS operations and manifest management.

Key Versioning Properties

Immutable versions — Once created, a version cannot be modified. All updates generate new versions with incremented integers.

Idempotent operations — Duplicate content hashes bypass storage writes and DB inserts, returning existing heads for efficiency.

Configurable retention — The KEEP_RECENT constant and ttlSeconds parameter balance storage costs against audit requirements.

Hook integration — onSkillCreated and onSkillVdbChanged enable external asset registries and usage analytics without coupling.

Summary

• Skills are versioned knowledge assets with SKILL.md documents, optional resources, and metadata
• Version numbers are monotonic integers; is_head marks the latest stable version
• Immutable append-only model guarantees reproducibility and audit trails
• Idempotent create/append prevents redundant storage when content is unchanged
• TTL cleanup with recent-version protection automates lifecycle management while preserving rollback options
• Dual-layer storage separates metadata (DB) from binary assets (COS) for scalability

Frequently Asked Questions

How does TencentDB Agent Memory handle concurrent skill updates?

The SDK uses optimistic concurrency control via the expected_version parameter. The update and delete methods reject requests where the provided version doesn't match the current head, forcing clients to retry with fresh state. This prevents lost updates without distributed locking overhead.

Can I recover a deleted skill version?

No. The TTL cleanup and delete operations are permanent. The system intentionally trades recoverability for storage efficiency. To preserve historical versions indefinitely, configure ttlSeconds to a large value or ensure your retention policy (KEEP_RECENT) covers your audit window.

What happens if I append a version with identical content?

The operation is idempotent. SkillVersioning compares the content hash and resource signatures against the current head. If unchanged, it returns the existing head version without writing to storage or the database—avoiding version proliferation from no-op updates.

How do I migrate skills between teams or environments?

The SDK doesn't provide native export/import. You must read the skill via client.get(), then create() in the target environment with identical content and resources. Version history doesn't transfer; the migrated skill starts at v1 with a new skill_id.

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