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

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 and implemented in the SQLite schema at 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 and validated by Zod schemas in 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 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, the KnowledgeEntity interface declares the metadata structure and CRUD method signatures for the registry. The SQLite implementation in 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, ensuring that only properly structured metadata enters the system. The handlers in 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:

// 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.
• 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 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 and validated against schemas in 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.

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