# How MemoryCore Manages Skills in TencentDB-Agent-Memory: A Deep Dive into the Metadata-Driven Architecture

> Discover how MemoryCore manages skills in TencentDB-Agent-Memory. Explore its metadata-driven architecture for skill lifecycle management from creation to retrieval.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: deep-dive
- Published: 2026-08-24

---

**MemoryCore treats skills as first-class metadata assets, using deterministic ID generation, persistent file-system storage, and agent-specific bindings to manage the complete skill lifecycle from creation to retrieval.**

The TencentDB-Agent-Memory repository implements a sophisticated approach to skill management that treats capabilities as version-controlled, permission-bound assets. Understanding how MemoryCore manages skills reveals a metadata-driven architecture where every skill progresses through standardized stages of generation, registration, binding, and retrieval.

## Skill Lifecycle Architecture

MemoryCore manages skills through a unified asset model that separates metadata from content. The system stores asset records in SQLite or MongoDB via adapters in `src/metadata/store/`, while the actual skill definitions reside as Markdown files on the file system. This dual-layer approach enables fast metadata queries while preserving human-readable, version-controllable skill definitions.

## Step-by-Step Skill Management Process

### Generating Unique Skill Identifiers

Every skill begins its lifecycle with a deterministic identifier created by the short-ID utility. The `shortId()` function in [`src/utils/short-id.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/utils/short-id.ts) generates a 12-character string prefixed with `skl-`, producing identifiers like `skl-5f2e9a1b3c4d`. This scheme ensures collision-resistant identification across distributed deployments.

### Registering Skills as Metadata Assets

Following ID generation, MemoryCore registers the skill through the `createAsset` method defined in [`src/metadata/store/metadata-store.contract.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/metadata/store/metadata-store.contract.ts). The registration stores the asset with `asset_type: "skill"` alongside ownership and team metadata. Depending on the deployment configuration, either the SQLite adapter ([`src/metadata/store/sqlite-adapter.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/metadata/store/sqlite-adapter.ts)) or MongoDB adapter ([`src/metadata/store/mongodb-adapter.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/metadata/store/mongodb-adapter.ts)) persists this record.

### Binding Skills to Agents

Once registered, skills attach to specific agents via `setAgentFixedAssets`, which creates relational mappings between `agent_id` and `asset_id` in the metadata store. The permission checker service in [`src/metadata/service/permission-checker.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/metadata/service/permission-checker.ts) validates that only asset owners, team administrators, or the agent itself can access the bound skill, enforcing strict multi-tenant isolation.

### Persisting Skill Definitions

Skill content persists on the file system at `<dataDir>/skills/<skillName>/SKILL.md`, as implemented in [`src/offload/index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/offload/index.ts). This Markdown-based storage format enables manual editing and version control while maintaining a structured definition that the pipeline can parse during retrieval operations.

### Creating Skills via L4 Offload

The skill creation workflow flows through the offload server in [`src/offload/index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/offload/index.ts). When users invoke the `/create-skill` command, `parseCreateSkillCommand` extracts the skill name and focus parameters before `createSkillWithBackend` communicates with the backend generator. The backend client in [`src/offload/backend-client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/offload/backend-client.ts) returns the generated content, which the system writes to the appropriate [`SKILL.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/SKILL.md) file path.

### Retrieving Skills for Context Injection

During L4 generation phases, MemoryCore retrieves skills by loading the [`SKILL.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/SKILL.md) file contents directly into the LLM context. The router logic in [`src/offload/index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/offload/index.ts) locates the file under the skills directory and streams its content into structured XML tags within the conversation prompt.

## Configuration and Access Control

### Managing Skill Visibility

Skills respect enable/disable flags controlled through the config-param service, allowing administrators to toggle availability at global, team, or user levels. The `skill.enabled` parameter in [`src/metadata/store/metadata-store.contract.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/metadata/store/metadata-store.contract.ts) governs whether a skill appears in agent contexts regardless of binding status.

### Legacy Migration Support

MemoryCore maintains backward compatibility with the legacy `@tdai/memory-tdai` plugin through migration scripts documented in [`SKILL-MIGRATION.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/SKILL-MIGRATION.md). These scripts transfer existing [`SKILL.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/SKILL.md) files from the shared `~/.openclaw/memory-tdai/` directory into the new repository structure without modification, ensuring continuous operation during system upgrades.

## Practical Implementation Examples

```typescript
// Generate a new skill ID
import { shortId } from "./utils/short-id";
const skillId = `skl-${shortId()}`;   // e.g. "skl-5f2e9a1b3c4d"

// Register the skill asset (SQLite example)
await metadataStore.createAsset({
  asset_id: skillId,
  team_id,
  asset_type: "skill",
  name: "MyAwesomeSkill",
  owner_user_id: userId,
  source_type: "manual",
});

// Bind the skill to an agent
await metadataStore.setAgentFixedAssets(agentId, [
  { asset_id: skillId, asset_type: "skill", created_by: userId },
]);

// Persist the skill definition on disk
import { mkdir, writeFile } from "fs/promises";
import { join } from "path";

const skillsDir = join(stateManager.ctx.dataDir, "skills", "MyAwesomeSkill");
await mkdir(skillsDir, { recursive: true });
await writeFile(join(skillsDir, "SKILL.md"), "# My Awesome Skill\n...", "utf-8");

// Retrieve the skill during a conversation
const skillPath = join(skillsDir, "SKILL.md");
const skillContent = await readFile(skillPath, "utf-8");
prompt.push(`<l4_skill>${skillContent}</l4_skill>`);

```

## Summary

- MemoryCore generates unique skill IDs using the `shortId()` utility with a `skl-` prefix to ensure collision-resistant asset identification
- Skills register as metadata assets with type `"skill"` in either SQLite or MongoDB storage adapters depending on deployment configuration
- Agent binding occurs through `setAgentFixedAssets` with permission validation via the permission checker service
- Skill definitions persist as Markdown files at `<dataDir>/skills/<skillName>/SKILL.md` for human-readable version control
- Creation flows through the offload server using `parseCreateSkillCommand` and backend client communication with the L4 generator
- Retrieval streams file contents directly into LLM prompts during generation phases via the offload index router

## Frequently Asked Questions

### How does MemoryCore generate unique skill IDs?

MemoryCore generates skill identifiers using the short-ID utility in [`src/utils/short-id.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/utils/short-id.ts), creating a 12-character alphanumeric string prefixed with `skl-` (e.g., `skl-5f2e9a1b3c4d`). This deterministic approach ensures unique asset identification across the metadata store while maintaining human-readable references for debugging and logging purposes.

### Where are skill definitions stored in MemoryCore?

Skill definitions reside on the file system at `<dataDir>/skills/<skillName>/SKILL.md`, as implemented in the offload server at [`src/offload/index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/offload/index.ts). This location stores the complete Markdown content generated during skill creation, while metadata about the skill persists separately in the database through the metadata store contract, creating a separation between searchable metadata and version-controlled content.

### How does MemoryCore handle permissions for skill access?

The permission checker service in [`src/metadata/service/permission-checker.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/metadata/service/permission-checker.ts) validates access rights during skill retrieval and binding operations. Only the original asset owner, designated team administrators, or the specific agent itself can view or utilize a skill, ensuring strict multi-tenant isolation and preventing unauthorized access to proprietary capabilities within the TencentDB-Agent-Memory ecosystem.

### Can legacy skills from the old memory-tdai plugin be migrated?

Yes, MemoryCore preserves legacy skills through migration scripts documented in [`SKILL-MIGRATION.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/SKILL-MIGRATION.md). These scripts transfer existing [`SKILL.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/SKILL.md) files from the shared `~/.openclaw/memory-tdai/` directory into the new repository layout without data loss or content modification, enabling seamless upgrades from the previous `@tdai/memory-tdai` plugin architecture while maintaining historical skill definitions.