# Key Metadata Operations Managed by the Memory Core Service

> Discover the key metadata operations managed by the Memory Core service in TencentDB Agent. Learn about its Metadata API and standardized CRUD operations for 14+ entity domains.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: api-reference
- Published: 2026-09-04

---

**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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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.

```typescript
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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/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.