Key Metadata Operations Managed by the Memory Core Service

The Memory Core service exposes a comprehensive Metadata API through the MetadataClient class that manages 14+ entity domains—including users, teams, agents, tasks, assets, and knowledge—via standardized CRUD operations on the /v3/meta/* and /v3/knowledge/* endpoints.

The TencentDB-Agent-Memory repository provides a scalable memory infrastructure for AI agents, with the Memory Core service acting as the central authority for workspace structural definitions. These metadata operations establish the relationships between users, resources, and permissions that enable the memory-generation pipeline to resolve asset ownership and access control. All metadata interactions are abstracted through the TypeScript SDK's MetadataClient, implemented in sdk/memory-core/typescript/src/v3/metadata-client.ts.

Metadata API Architecture and Core Concepts

The Metadata API distinguishes between structural metadata (the "workspace definition") and content metadata (knowledge chunks, embeddings). The MetadataClient serves as the SDK wrapper for all /v3/meta/* and /v3/knowledge/* HTTP endpoints, handling the full lifecycle of entities that comprise a memory workspace.

According to the source code in metadata-client.ts, every operation shares common request handling utilities. The body() helper strips undefined fields to ensure clean JSON payloads, while the requireAnyString validation helper—defined at lines 76-85 of the same file—enforces that at least one identifying field (such as user_id or user_key) is present in validation-critical requests.

Entity Domains and CRUD Operations

The Memory Core organizes metadata into distinct domains, each exposing specific operation types through the MetadataClient.

Identity and Access Management

• User: create, get, delete, list
• User-Key: create, list, get, revoke, update
• Auth: verify (user-key validation against stored credentials)
• ACL: grant, revoke, list, check (access control list management)

Organizational Structure

• Team: create, get, update, delete, list
• Team Member: add, remove, list, get

Agent and Task Lifecycle

• Agent: create, get, update, delete, list, archive
• Task: create, get, update, delete, list, archive
• Task Agent: link, unlink, list (associates agents with specific tasks)
• Participation Log: append, list (tracks agent participation history)

Resource and Knowledge Management

• Asset: create, get, update, delete, list, list-accessible, touch-usage
• Agent-Fixed Asset: set, list, list-with-detail, summarize
• Knowledge (v3 management plane): create, get, update, delete, list

System Configuration

• Config Param (v3.2): get-instance-quota, get and set user configuration parameters

Practical Code Examples

The MetadataClient provides type-safe methods for all metadata operations. The following examples demonstrate client initialization and common workflows.

import { MetadataClient } from
  'https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/feat/server_team/sdk/memory-core/typescript/src/v3/metadata-client.ts';

// Initialise the client (replace placeholders with real values)
const client = new MetadataClient({
  endpoint: 'https://memory.tencentyun.com',
  apiKey: 'KERNEL_AUTH_TOKEN',
  serviceId: 'tdai-xxxxxx',
});

// ----- User management -------------------------------------------------
await client.createUser({ user_name: 'alice' });
const alice = await client.getUser('alice-id');
await client.deleteUsers([alice.user_id]);

// ----- Agent management ------------------------------------------------
await client.createAgent({ agent_name: 'CodeBuddy', team_id: 'team-01' });
const agents = await client.listAgents({ team_id: 'team-01' });
await client.archiveAgent(agents[0].agent_id);

// ----- Knowledge CRUD ---------------------------------------------------
await client.createKnowledge({
  knowledge_name: 'ProductFAQ',
  team_id: 'team-01',
  knowledge_type: 'manual',
});
const list = await client.listKnowledge({ team_id: 'team-01' });
await client.deleteKnowledge(
  list.items.map(k => k.knowledge_id),
  'team-01',
);

Runtime Integration and Type Definitions

The runtime gateway layer in MemoryCore/src/gateway/metadata-env.ts automates header injection for service authentication, automatically providing x-tdai-service-id and x-tdai-user-key when selecting the appropriate MetadataClient instance for incoming requests.

All TypeScript interfaces and type definitions for requests and responses are located in sdk/memory-core/typescript/src/v3/metadata-types.ts, ensuring compile-time safety for all metadata operations.

Summary

• The Memory Core service manages 14+ distinct entity domains—from users and teams to assets and knowledge—through a unified Metadata API.
• The MetadataClient class in sdk/memory-core/typescript/src/v3/metadata-client.ts provides the primary SDK interface to /v3/meta/* and /v3/knowledge/* endpoints.
• Shared validation helpers (body() and requireAnyString) enforce data integrity by stripping undefined fields and requiring at least one identifier string.
• Metadata operations form the structural backbone of the memory workspace, enabling the content pipeline to resolve ownership, permissions, and task relationships.

Frequently Asked Questions

What is the difference between metadata operations and memory-generation operations?

Metadata operations manage the structural workspace definition—such as users, teams, agents, and assets—via the MetadataClient, while memory-generation pipelines handle actual content processing like knowledge chunking, embeddings, and retrieval. Without these metadata objects, the pipeline cannot resolve which assets belong to which agents or which ACLs apply to specific resources.

How does the MetadataClient validate required parameters?

According to the source code in sdk/memory-core/typescript/src/v3/metadata-client.ts, the client uses a requireAnyString helper (defined at lines 76-85) to enforce that at least one identifying field is present in critical requests. Additionally, the body() method automatically strips undefined fields from payloads before transmission to ensure clean API requests.

Which file contains the type definitions for Metadata API requests?

All TypeScript type definitions for requests and responses are located in sdk/memory-core/typescript/src/v3/metadata-types.ts. The runtime gateway logic that handles client instantiation and header management resides in MemoryCore/src/gateway/metadata-env.ts.

Can I manage Knowledge entities through the same Metadata API?

Yes, Knowledge entities are managed through the Metadata API using the /v3/knowledge/* endpoints, which the MetadataClient exposes alongside the standard /v3/meta/* operations. This allows unified management of both structural workspace objects and knowledge content through a single SDK interface.

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