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

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 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. 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) or MongoDB adapter (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 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. 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. 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 returns the generated content, which the system writes to the appropriate SKILL.md file path.

Retrieving Skills for Context Injection

During L4 generation phases, MemoryCore retrieves skills by loading the SKILL.md file contents directly into the LLM context. The router logic in 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 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. These scripts transfer existing 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

// 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, 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. 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 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. These scripts transfer existing 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.

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