# Knowledge Metadata Registry in MemoryCore: Purpose, Architecture, and Implementation

> Discover the purpose of the Knowledge Metadata Registry in MemoryCore. This component manages a queryable catalog of Knowledge entity metadata, not the actual data.

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

---

**The Knowledge Metadata Registry is a management-plane component in MemoryCore that maintains a centralized, queryable catalog of Knowledge entity metadata—such as wiki pages and code graphs—without handling the actual data-plane content.**

The TencentDB-Agent-Memory repository provides a multi-tenant memory system for AI agents, with MemoryCore serving as its central storage and retrieval engine. Within this architecture, the **knowledge metadata registry** acts as the authoritative directory for all Knowledge assets, enabling safe metadata operations and efficient cross-service discovery while keeping metadata separate from heavy content payloads.

## Core Responsibilities of the Knowledge Metadata Registry

The registry fulfills four critical functions within the MemoryCore ecosystem.

### Centralized Registration and Storage

Every Knowledge item receives a unique `knowledge_id` and is indexed in the `entity_knowledge` collection. This registry resides in the core's storage layer, defined in [`MemoryCore/src/core/store/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/store/types.ts) and implemented in the SQLite schema at [`MemoryCore/src/core/store/sqlite.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/store/sqlite.ts). The storage layer ensures that metadata remains lightweight and quickly accessible, distinct from the vector embeddings or document content stored in the data-plane.

### Metadata CRUD API

The registry exposes RESTful endpoints under `/v3/knowledge/*` for creating, retrieving, updating, deleting, and listing knowledge entities. These routes are implemented in [`MemoryCore/src/gateway/knowledge-handlers.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/knowledge-handlers.ts) and validated by Zod schemas in [`MemoryCore/src/gateway/knowledge-schemas.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/knowledge-schemas.ts). Importantly, these APIs manipulate only metadata fields—such as `name`, `summary`, `service_url`, `repo_url`, and `branch`—and never touch the actual content stored in the data-plane.

### Cross-Service Lookup and Resolution

Downstream services like the Proxy or Knowledge Service query the registry to resolve a `knowledge_id` to its corresponding metadata. This resolution enables rendering, routing, and synchronization of the actual knowledge payload. The VDB implementation in [`MemoryCore/src/core/store/tcvdb.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/store/tcvdb.ts) references this "knowledge entities registry" during upsert and query operations, demonstrating how the metadata catalog facilitates data-plane interactions without embedding heavy payload logic in the registry itself.

### Team-Scoped Isolation

Knowledge metadata is stored per-team using the `team_id` field and optionally filtered by type (`wiki` or `code-graph`). This design guarantees strict tenant isolation, ensuring that each team views and manages only its own knowledge assets within the shared MemoryCore infrastructure.

## Implementation Architecture

The registry's implementation spans the storage layer and API gateway, maintaining clean separation between metadata management and content storage.

### Storage Layer Definitions

In [`MemoryCore/src/core/store/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/store/types.ts), the `KnowledgeEntity` interface declares the metadata structure and CRUD method signatures for the registry. The SQLite implementation in [`MemoryCore/src/core/store/sqlite.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/store/sqlite.ts) creates the `entity_knowledge` table with appropriate indexes, providing a durable, embedded store for the metadata catalog.

### API Gateway Integration

The gateway layer validates incoming requests using schemas defined in [`MemoryCore/src/gateway/knowledge-schemas.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/knowledge-schemas.ts), ensuring that only properly structured metadata enters the system. The handlers in [`MemoryCore/src/gateway/knowledge-handlers.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/knowledge-handlers.ts) implement the business logic for the management-plane API, coordinating between the HTTP interface and the underlying storage layer.

## Working with the Knowledge Metadata Registry

The following TypeScript examples demonstrate how to interact with the registry through its client interface:

```typescript
// Create a new knowledge metadata entry (idempotent)
await metadataClient.createKnowledge({
  knowledge_id: "wiki-docs",
  type: "wiki",
  name: "Project Wiki",
  service_url: "http://ks:8421/v3",
  team_id: "team-1",
});

// Retrieve metadata for a knowledge ID
const meta = await metadataClient.getKnowledge("wiki-docs", "team-1");

// Update selective fields (e.g., rename)
await metadataClient.updateKnowledge({
  knowledge_id: "wiki-docs",
  name: "Renamed Wiki",
});

// List all wiki-type knowledge for a team
const list = await metadataClient.listKnowledge({
  team_id: "team-1",
  type: "wiki",
});

```

These operations target only the metadata layer, leaving the actual document vectors and content to be managed by the data-plane services.

## Summary

- The **knowledge metadata registry** provides a lightweight, searchable catalog of Knowledge assets in MemoryCore, separate from content storage.
- It maintains centralized registration in the `entity_knowledge` collection, indexed by unique `knowledge_id` values and defined in [`MemoryCore/src/core/store/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/store/types.ts).
- The registry exposes CRUD operations via `/v3/knowledge/*` endpoints implemented in the gateway layer, handling metadata fields without touching data-plane payloads.
- Cross-service resolution allows downstream components to locate and route knowledge assets using the registry as an authoritative directory.
- Team-scoped isolation via `team_id` ensures multi-tenant safety, with optional filtering by knowledge type (`wiki` or `code-graph`).

## Frequently Asked Questions

### What is the difference between the knowledge metadata registry and actual knowledge storage?

The registry stores only metadata—such as `knowledge_id`, `name`, `service_url`, and `team_id`—in the `entity_knowledge` collection. It does not store the actual content, vectors, or embeddings, which reside in the data-plane storage such as the VDB implementation. This separation allows the registry to remain lightweight while the data-plane handles heavy payloads.

### How does the registry enforce multi-tenant isolation?

All knowledge metadata entries include a mandatory `team_id` field. The registry filters all queries and operations by this identifier, ensuring that teams can only access, modify, and list their own knowledge assets. This team-scoped isolation is enforced at the storage layer in [`MemoryCore/src/core/store/sqlite.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/store/sqlite.ts) and validated through the API gateway.

### Which HTTP endpoints interact with the knowledge metadata registry?

The registry exposes the `/v3/knowledge/*` route family, including endpoints for create, get, update, delete, and list operations. These are implemented in [`MemoryCore/src/gateway/knowledge-handlers.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/knowledge-handlers.ts) and validated against schemas in [`MemoryCore/src/gateway/knowledge-schemas.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/knowledge-schemas.ts), providing a complete management-plane API for knowledge entities.

### What types of knowledge can be registered in the metadata catalog?

The registry supports distinct knowledge types, specifically `wiki` and `code-graph`, as indicated by the `type` field in the metadata schema. This typing allows MemoryCore to apply appropriate handling logic for different knowledge formats while maintaining a unified catalog structure.