@kognitivedev/cloud-knowledge-base

Managed cloud knowledge base SDK for Kognitive agents and workflows.

This package targets managed cloud pipelines, which are also the dashboard knowledge-base resource. A pipeline ID is the knowledge-base ID across SDKs, dashboard, agents, and workflows.

Managed knowledge bases are zero-config at the API level: documents are parsed into indexed artifacts and searched through Qdrant-native hybrid retrieval, using dense semantic vectors plus Qdrant BM25 sparse vectors.

Backend requirements for managed KB indexing/search are REDIS_URL, QDRANT_URL, and OPENROUTER_API_KEY. QDRANT_API_KEY is optional depending on your Qdrant deployment. Pipeline sync is asynchronous, so clients should poll the pipeline run/status endpoints before relying on newly uploaded content in search.

Every normalized hit includes citation metadata suitable for enterprise rendering and audit trails:

• sourceId
• snippet
• filename
• mimeType
• pageNumber
• artifactType
• parseDocumentId

Search

Create and sync the pipeline with @kognitivedev/documents, wait for the run to complete, then search it from this package:

import { KognitiveDocumentsClient } from "@kognitivedev/documents";
import { searchCloudKnowledgeBase } from "@kognitivedev/cloud-knowledge-base";

const documents = new KognitiveDocumentsClient({
  baseUrl: process.env.KOGNITIVE_BASE_URL!,
  apiKey: process.env.KOGNITIVE_API_KEY,
});

const pipeline = await documents.pipelines.create({ name: "Support KB" });
const source = await documents.pipelines.addFile(pipeline.id, { fileId: "file-id" });
const run = await documents.pipelines.sync(pipeline.id, { sourceId: String(source.id) });
await documents.pipelines.getRun(pipeline.id, run.id);

const result = await searchCloudKnowledgeBase({
  baseUrl: process.env.KOGNITIVE_BASE_URL!,
  apiKey: process.env.KOGNITIVE_API_KEY,
  pipelineId: pipeline.id,
  query: "What is the retention policy?",
  topK: 5,
  resourceId: { userId: "user_123" },
});

Agent Context Adapter

import { createAgent } from "@kognitivedev/agents";
import { createCloudKnowledgeBaseContextAdapter } from "@kognitivedev/cloud-knowledge-base";

const agent = createAgent({
  name: "support-agent",
  instructions: "Answer using the managed knowledge base when relevant.",
  runtime,
  contextAdapters: [
    createCloudKnowledgeBaseContextAdapter({
      baseUrl: process.env.KOGNITIVE_BASE_URL!,
      apiKey: process.env.KOGNITIVE_API_KEY,
      pipelineId: "pipe_123",
      topK: 4,
    }),
  ],
});

Workflow Step

import { createWorkflow } from "@kognitivedev/workflows";
import { createCloudKnowledgeBaseAnswerStep } from "@kognitivedev/cloud-knowledge-base";

const workflow = createWorkflow<{ query: string }>({ name: "kb-answer" })
  .then(createCloudKnowledgeBaseAnswerStep({
    id: "answer",
    agent,
    baseUrl: process.env.KOGNITIVE_BASE_URL!,
    apiKey: process.env.KOGNITIVE_API_KEY,
    pipelineId: "pipe_123",
    getQuery: (input) => input.query,
  }))
  .build();

There is also a lower-level createCloudKnowledgeBaseSearchStep() when you want retrieval without the answering stage.