@ontos-ai/knowhere-claw 0.2.0 → 0.2.2-beta.1

package/dist/store.d.ts

@@ -0,0 +1,79 @@
+import type { ChannelRouteRecord, KnowhereScope, PluginLogger, SaveStoredDocumentPayload, ScopeMode, StoredDocumentPayload, StoredDocumentRecord } from "./types";
+export declare class KnowhereStore {
+    private readonly rootDir;
+    private readonly scopeMode;
+    private readonly logger;
+    private readonly indexCache;
+    private readonly documentPayloadCache;
+    private readonly scopeAccessChains;
+    private readonly scopeKeyAliases;
+    private readonly sessionScopeKeysBySessionId;
+    private readonly sessionScopeKeysBySessionKey;
+    private readonly channelRoutes;
+    private routesLoaded;
+    constructor(params: {
+        rootDir: string;
+        scopeMode: ScopeMode;
+        logger: PluginLogger;
+    });
+    registerScopeAlias(context: {
+        scopeKey: string;
+        sessionKey?: string;
+        sessionId?: string;
+    }): string;
+    registerMessageScope(context: {
+        sessionKey?: string;
+        sessionId?: string;
+        messageContext: unknown;
+    }): string | undefined;
+    registerChannelRoute(params: {
+        channelId: string;
+        accountId?: string;
+        conversationId?: string;
+    }): Promise<void>;
+    resolveChannelRoute(params: {
+        channelId?: string;
+        conversationId?: string;
+        sessionKey?: string;
+    }): Promise<ChannelRouteRecord | undefined>;
+    private lookupChannelRoute;
+    inheritScopeAlias(context: {
+        childSessionKey?: string;
+        childSessionId?: string;
+        requesterSessionKey?: string;
+        requesterSessionId?: string;
+    }): string | undefined;
+    resolveScope(context?: {
+        agentId?: string;
+        sessionKey?: string;
+        sessionId?: string;
+    }): KnowhereScope;
+    listDocuments(scope: KnowhereScope): Promise<StoredDocumentRecord[]>;
+    loadDocumentPayload(scope: KnowhereScope, docId: string): Promise<StoredDocumentPayload | null>;
+    getResultFileAbsolutePath(scope: KnowhereScope, docId: string, relativePath: string): string;
+    readResultFile(scope: KnowhereScope, docId: string, relativePath: string): Promise<{
+        document: StoredDocumentRecord;
+        relativePath: string;
+        text: string | null;
+    } | null>;
+    saveDownloadedDocument(scope: KnowhereScope, payload: SaveStoredDocumentPayload, options?: {
+        overwrite?: boolean;
+    }): Promise<StoredDocumentRecord>;
+    removeDocument(scope: KnowhereScope, docId: string): Promise<StoredDocumentRecord | null>;
+    clearScope(scope: KnowhereScope): Promise<StoredDocumentRecord[]>;
+    private getIndex;
+    private persistIndex;
+    private runWithScopeAccessLock;
+    private removeDocumentArtifacts;
+    private buildDocumentPayloadCacheKey;
+    private touchDocumentPayloadCache;
+    private deleteDocumentPayloadCache;
+    private deleteScopeDocumentPayloadCaches;
+    private loadOrBuildBrowseIndex;
+    private buildRouteKey;
+    private ensureRoutesLoaded;
+    private persistRoutes;
+    private resolveCanonicalScopeKey;
+    private resolveKnownScopeKey;
+    private rebuildIndex;
+}

package/dist/text.d.ts

@@ -0,0 +1,10 @@
+export declare function normalizeWhitespace(value: unknown): string;
+export declare function truncateText(value: unknown, maxChars: number): string;
+export declare function slugify(value: unknown, fallback?: string): string;
+export declare function hashString(value: string): string;
+export declare function sanitizeStringArray(value: unknown): string[];
+export declare function toComparableText(value: unknown): string;
+export declare function stripHtmlTags(text: string): string;
+export declare function stripLatex(text: string): string;
+export declare function normalizeUnicode(text: string): string;
+export declare function normalizeForGrep(text: string): string;

package/dist/tools.d.ts

@@ -0,0 +1,10 @@
+import { type AnyAgentTool, type OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { KnowhereStore } from "./store";
+import type { KnowledgeGraphService } from "./kg-service";
+import type { ResolvedKnowhereConfig, ToolRuntimeContext } from "./types";
+export declare function createKnowhereToolFactory(params: {
+    api: OpenClawPluginApi;
+    config: ResolvedKnowhereConfig;
+    store: KnowhereStore;
+    kgService: KnowledgeGraphService;
+}): (ctx: ToolRuntimeContext) => AnyAgentTool[];

package/dist/tools.js

@@ -9,6 +9,13 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk/core";
 //#region src/tools.ts
+const TERMINAL_JOB_STATUSES = new Set([
+	"cancelled",
+	"canceled",
+	"done",
+	"error",
+	"failed"
+]);
 async function buildKnowledgeGraphAsync(params) {
 	const docDir = path.join(params.scope.documentsDir, params.docId);
 	const metadataPath = path.join(docDir, "metadata.json");
@@ -95,6 +102,67 @@ function buildStoredDocumentSummaryLines(params) {
 	if (params.includeUpdatedAt) lines.push(`Updated: ${params.document.updatedAt}`);
 	return lines;
 }
+function isTerminalJobStatus(status, hasError) {
+	return TERMINAL_JOB_STATUSES.has(status.trim().toLowerCase()) || hasError;
+}
+function startKnowledgeGraphBuild(params) {
+	if (!params.kgService.isEnabled()) return;
+	const kbId = params.kgService.resolveKbId(params.ctx);
+	if (!kbId) return;
+	params.api.logger.info(`knowhere: initiating knowledge graph build kbId=${kbId} docId=${params.document.id}`);
+	buildKnowledgeGraphAsync({
+		kgService: params.kgService,
+		kbId,
+		docId: params.document.id,
+		documentPayload: params.ingestResult,
+		scope: params.scope,
+		ctx: params.ctx,
+		api: params.api,
+		channelRoute: params.channelRoute,
+		sessionKey: params.sessionKey
+	}).catch((kgError) => {
+		params.api.logger.error(`knowhere: knowledge graph build failed kbId=${kbId} docId=${params.document.id}: ${formatErrorMessage(kgError)}`);
+	});
+}
+async function persistIngestedDocument(params) {
+	const storedDocument = await params.store.saveDownloadedDocument(params.scope, {
+		sourceType: params.sourceType,
+		source: params.source,
+		fileName: params.fileName,
+		docId: params.docId,
+		title: params.title,
+		dataId: params.dataId,
+		tags: params.tags,
+		job: params.ingestResult.job,
+		jobResult: params.ingestResult.jobResult,
+		downloadedResult: params.ingestResult.downloadedResult
+	}, { overwrite: params.overwrite });
+	params.api.logger.info(`knowhere: knowhere_ingest_document stored document scope=${params.scope.label} jobId=${params.ingestResult.job.job_id} docId=${storedDocument.id}`);
+	startKnowledgeGraphBuild({
+		api: params.api,
+		channelRoute: params.channelRoute,
+		ctx: params.ctx,
+		document: storedDocument,
+		ingestResult: params.ingestResult,
+		kgService: params.kgService,
+		scope: params.scope,
+		sessionKey: params.sessionKey
+	});
+	return storedDocument;
+}
+function formatCompletedIngestResult(params) {
+	return [
+		"Ingest complete.",
+		...buildStoredDocumentSummaryLines({
+			document: params.document,
+			scopeLabel: params.scopeLabel,
+			includeJobId: true,
+			includeSource: true
+		}),
+		`Source type: ${params.sourceType}`,
+		"Next: use knowhere_preview_document for a structural overview or knowhere_grep to search the parsed content."
+	].join("\n");
+}
 function readString(value) {
 	return typeof value === "string" && value.trim() ? value.trim() : void 0;
 }
@@ -531,7 +599,7 @@ function createIngestTool(params) {
 	return {
 		name: "knowhere_ingest_document",
 		label: "Knowhere Ingest",
-		description: "Parse a local file or remote URL with Knowhere and store the result in the current scope. Before calling this for a document that might already be stored in the current scope, use knowhere_list_documents and reuse the existing stored document when Source, File, or Title clearly match unless the user explicitly asks for a fresh parse or overwrite. When the user provides a URL to a document (PDF link, web page, etc.), pass it as the url parameter — Knowhere fetches it directly, no local download needed. Returns immediately with a job ID while parsing continues in the background. Use knowhere_get_job_status only when the current turn needs the parsed result. Use lang to control the language of any user-facing background status update (`en` by default, `ch` for Chinese). Provide either filePath or url, not both.",
+		description: "Parse a local file or remote URL with Knowhere and store the result in the current scope. Before calling this for a document that might already be stored in the current scope, use knowhere_list_documents and reuse the existing stored document when Source, File, or Title clearly match unless the user explicitly asks for a fresh parse or overwrite. When the user provides a URL to a document (PDF link, web page, etc.), pass it as the url parameter — Knowhere fetches it directly, no local download needed. Knowhere must be the only parser for supported files. If Knowhere returns an error, surface that exact error to the user and do not fall back to other parsing methods or fabricate a preview. By default blockUntilComplete is false, so this tool is fire-and-forget and returns a job ID while parsing continues in the background. Set blockUntilComplete to true only when the current turn explicitly needs the parsed result before continuing. Use lang to control the language of any user-facing background status update (`en` by default, `ch` for Chinese). Provide either filePath or url, not both.",
 		parameters: {
 			type: "object",
 			additionalProperties: false,
@@ -573,6 +641,10 @@ function createIngestTool(params) {
 					type: "boolean",
 					description: "Replace an existing stored document with the same docId."
 				},
+				blockUntilComplete: {
+					type: "boolean",
+					description: "When true, wait for Knowhere to finish parsing, store the result, and return a ready-to-use stored-document summary. Defaults to false, which returns immediately with a job ID and continues parsing in the background."
+				},
 				lang: {
 					type: "string",
 					description: "Language for any user-facing background status update sent after parsing completes or fails. Supports en and ch; unsupported values fall back to en."
@@ -628,13 +700,14 @@ function createIngestTool(params) {
 				filePath: resolvedFilePath,
 				url: urlParam
 			});
+			const blockUntilComplete = readBoolean(paramsRecord.blockUntilComplete, false);
 			const tags = sanitizeStringArray(paramsRecord.tags);
 			const overwrite = readBoolean(paramsRecord.overwrite, false);
 			const trackerLanguage = readIngestTrackerLanguage(paramsRecord.lang);
 			const sessionKey = params.ctx.sessionKey;
 			const sourceType = urlParam ? "url" : "file";
 			const channelRoute = await params.store.resolveChannelRoute({ sessionKey });
-			params.api.logger.info(`knowhere: knowhere_ingest_document starting background ingest scope=${scope.label} sourceType=${sourceType} label=${JSON.stringify(progressLabel)} overwrite=${overwrite} docId=${docId ?? "auto"} dataId=${dataId ?? "none"} lang=${trackerLanguage} routeState=${channelRoute ? "resolved" : "missing"} routeAccountId=${channelRoute?.accountId ?? "none"}`);
+			params.api.logger.info(`knowhere: knowhere_ingest_document starting ingest scope=${scope.label} sourceType=${sourceType} label=${JSON.stringify(progressLabel)} mode=${blockUntilComplete ? "blocking" : "background"} overwrite=${overwrite} docId=${docId ?? "auto"} dataId=${dataId ?? "none"} lang=${trackerLanguage} routeState=${channelRoute ? "resolved" : "missing"} routeAccountId=${channelRoute?.accountId ?? "none"}`);
 			let resolveJobCreated;
 			const jobCreatedPromise = new Promise((resolve) => {
 				resolveJobCreated = resolve;
@@ -653,40 +726,52 @@ function createIngestTool(params) {
 					resolveJobCreated(job);
 				}
 			});
+			if (blockUntilComplete) {
+				const ingestResult = await ingestPromise.catch(rethrowWithPaymentHint);
+				params.api.logger.info(`knowhere: knowhere_ingest_document download completed scope=${scope.label} jobId=${ingestResult.job.job_id}; storing extracted result`);
+				return textResult(formatCompletedIngestResult({
+					document: await persistIngestedDocument({
+						api: params.api,
+						channelRoute,
+						ctx: params.ctx,
+						dataId,
+						docId,
+						fileName,
+						ingestResult,
+						kgService: params.kgService,
+						overwrite,
+						scope,
+						sessionKey,
+						source: urlParam || resolvedFilePath || "",
+						sourceType,
+						store: params.store,
+						tags,
+						title
+					}),
+					scopeLabel: scope.label,
+					sourceType
+				}));
+			}
 			ingestPromise.then(async (ingestResult) => {
 				params.api.logger.info(`knowhere: knowhere_ingest_document download completed scope=${scope.label} jobId=${ingestResult.job.job_id}; storing extracted result`);
-				const storedDocument = await params.store.saveDownloadedDocument(scope, {
-					sourceType,
-					source: urlParam || resolvedFilePath || "",
-					fileName,
-					docId,
-					title,
+				const storedDocument = await persistIngestedDocument({
+					api: params.api,
+					channelRoute,
+					ctx: params.ctx,
 					dataId,
+					docId,
+					fileName,
+					ingestResult,
+					kgService: params.kgService,
+					overwrite,
+					scope,
+					sessionKey,
+					source: urlParam || resolvedFilePath || "",
+					sourceType,
+					store: params.store,
 					tags,
-					job: ingestResult.job,
-					jobResult: ingestResult.jobResult,
-					downloadedResult: ingestResult.downloadedResult
-				}, { overwrite });
-				params.api.logger.info(`knowhere: knowhere_ingest_document stored document scope=${scope.label} jobId=${ingestResult.job.job_id} docId=${storedDocument.id} label=${JSON.stringify(progressLabel)}`);
-				if (params.kgService.isEnabled()) {
-					const kbId = params.kgService.resolveKbId(params.ctx);
-					if (kbId) {
-						params.api.logger.info(`knowhere: initiating knowledge graph build kbId=${kbId} docId=${storedDocument.id}`);
-						buildKnowledgeGraphAsync({
-							kgService: params.kgService,
-							kbId,
-							docId: storedDocument.id,
-							documentPayload: ingestResult,
-							scope,
-							ctx: params.ctx,
-							api: params.api,
-							channelRoute,
-							sessionKey
-						}).catch((kgError) => {
-							params.api.logger.error(`knowhere: knowledge graph build failed kbId=${kbId} docId=${storedDocument.id}: ${formatErrorMessage(kgError)}`);
-						});
-					}
-				}
+					title
+				});
 				await notifyBackgroundIngestOutcome({
 					api: params.api,
 					context: params.ctx,
@@ -737,7 +822,7 @@ function createIngestTool(params) {
 				`Job ID: ${createdJob.job_id}`,
 				`File: ${progressLabel}`,
 				`Scope: ${scope.label}`,
-				"Use knowhere_get_job_status only if this turn needs the parsed result."
+				"This call does not include parsed content yet."
 			].join("\n"));
 		}
 	};
@@ -746,7 +831,7 @@ function createJobStatusTool(params) {
 	return {
 		name: "knowhere_get_job_status",
 		label: "Knowhere Job Status",
-		description: "Check the status of a Knowhere parsing job by job ID. Returns job status, progress, duration, credits spent, and whether the result is already stored locally. Use this to monitor a running job or inspect a past job before importing it with knowhere_import_completed_job.",
+		description: "Check the status of a Knowhere parsing job by job ID. Returns job status, progress, duration, credits spent, and whether the result is already stored locally. Use this to monitor a running job or inspect a past job before importing it with knowhere_import_completed_job. Do not assume a running job is stuck just because progress is unchanged or slow. Only treat the job as failed or stuck when Knowhere returns an explicit failure status or error code.",
 		parameters: {
 			type: "object",
 			additionalProperties: false,
@@ -798,6 +883,10 @@ function createJobStatusTool(params) {
 				lines.push(`Result URL: ${job.result_url}`);
 				if (job.result_url_expires_at) lines.push(`Result URL expires: ${job.result_url_expires_at}`);
 			}
+			const hasExplicitError = Boolean(job.error?.code || job.error?.message);
+			if (job.status.trim().toLowerCase() === "done") lines.push("Interpretation: completed.");
+			else if (isTerminalJobStatus(job.status, hasExplicitError)) lines.push("Interpretation: Knowhere reported an explicit failure. Surface this error to the user and do not fall back to other parsing methods.");
+			else lines.push("Interpretation: still running. Do not describe this job as stuck or failed unless a later Knowhere API response returns an explicit failure status or error code.");
 			if (matchingDocuments.length === 0) lines.push("Stored docs in scope: none");
 			else {
 				lines.push("Stored docs in scope:");

package/dist/tracker-progress.d.ts

@@ -0,0 +1,10 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import type { ChannelRouteRecord } from "./types";
+export declare function sendTrackerProgress(params: {
+    api: OpenClawPluginApi;
+    context?: unknown;
+    sessionKey?: string;
+    messages?: unknown[];
+    channelRoute?: ChannelRouteRecord;
+    text: string;
+}): Promise<boolean>;

package/dist/types.d.ts

@@ -0,0 +1,320 @@
+export type ScopeMode = "session" | "agent" | "global";
+export type StringRecord = Record<string, unknown>;
+export interface PluginLogger {
+    debug?: (message: string) => void;
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+}
+export interface ToolRuntimeContext {
+    workspaceDir?: string;
+    agentId?: string;
+    accountId?: string;
+    sessionKey?: string;
+    sessionId?: string;
+}
+export interface ResolvedKnowhereConfig {
+    apiKey: string;
+    baseUrl: string;
+    storageDir: string;
+    scopeMode: ScopeMode;
+    pollIntervalMs: number;
+    pollTimeoutMs: number;
+    requestTimeoutMs: number;
+    uploadTimeoutMs: number;
+}
+export interface KnowhereStatistics {
+    total_chunks?: number;
+    text_chunks?: number;
+    image_chunks?: number;
+    table_chunks?: number;
+    total_pages?: number;
+}
+export interface KnowhereChecksum {
+    algorithm?: string;
+    value?: string;
+}
+export interface KnowhereManifest {
+    version?: string;
+    job_id?: string;
+    data_id?: string;
+    source_file_name?: string;
+    processing_date?: string;
+    checksum?: KnowhereChecksum;
+    statistics?: KnowhereStatistics;
+    files?: StringRecord;
+}
+export interface StoredChunk {
+    chunkId: string;
+    type: "text" | "image" | "table";
+    path: string | null;
+    summary: string;
+    content: string;
+    tokens: number | null;
+    keywords: string[];
+    relationships: unknown[];
+    metadata: StringRecord;
+    assetFilePath: string | null;
+    originalName: string | null;
+    tableType: string | null;
+}
+export interface StoredPathRecord {
+    path: string;
+    parentPath: string | null;
+    depth: number;
+    childPaths: string[];
+    chunkIds: string[];
+    directChunkCount: number;
+    chunkCount: number;
+    textChunkCount: number;
+    imageChunkCount: number;
+    tableChunkCount: number;
+}
+export type StoredResultFileKind = "manifest" | "chunks" | "fullMarkdown" | "kbCsv" | "hierarchy" | "hierarchyView" | "image" | "table" | "other";
+export interface StoredResultFileRecord {
+    relativePath: string;
+    kind: StoredResultFileKind;
+    chunkId: string | null;
+    format: string | null;
+    sizeBytes: number | null;
+}
+export interface StoredBrowseIndex {
+    version: number;
+    paths: StoredPathRecord[];
+    chunkOrder: string[];
+    resultFiles: StoredResultFileRecord[];
+}
+export interface KnowhereParseResult {
+    manifest: KnowhereManifest;
+    chunks: StoredChunk[];
+    fullMarkdown: string;
+    hierarchy: unknown;
+    browseIndex: StoredBrowseIndex;
+}
+export interface KnowhereDownloadedResult {
+    zipBytes: Buffer;
+    rawZipSha1: string;
+}
+export interface KnowhereJob {
+    job_id: string;
+    status: string;
+    source_type: string;
+    data_id?: string | null;
+    created_at?: string | null;
+    upload_url?: string | null;
+    upload_headers?: Record<string, string> | null;
+    expires_in?: number | null;
+}
+export interface KnowhereJobError {
+    code?: string;
+    message?: string;
+    request_id?: string;
+    details?: unknown;
+}
+export interface KnowhereJobResult {
+    job_id: string;
+    status: string;
+    source_type: string;
+    data_id?: string | null;
+    created_at?: string | null;
+    progress?: unknown;
+    error?: KnowhereJobError | null;
+    result?: StringRecord | null;
+    result_url?: string | null;
+    result_url_expires_at?: string | null;
+    file_name?: string | null;
+    file_extension?: string | null;
+    model?: string | null;
+    ocr_enabled?: boolean | null;
+    duration_seconds?: number | null;
+    credits_spent?: number | null;
+}
+export interface KnowhereJobList {
+    jobs: KnowhereJobResult[];
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+}
+export interface KnowhereJobListRequest {
+    page?: number;
+    pageSize?: number;
+    jobStatus?: string;
+    jobType?: string;
+    recentDays?: 1 | 7 | 30;
+    startTime?: string;
+    endTime?: string;
+}
+export interface KnowhereParsingParams {
+    model?: "base" | "advanced";
+    ocr_enabled?: boolean;
+    kb_dir?: string;
+    doc_type?: string;
+    smart_title_parse?: boolean;
+    summary_image?: boolean;
+    summary_table?: boolean;
+    summary_txt?: boolean;
+    add_frag_desc?: string;
+}
+export interface KnowhereIngestRequest {
+    filePath?: string;
+    fileName?: string;
+    url?: string;
+    dataId?: string;
+    parsingParams?: KnowhereParsingParams;
+    onJobCreated?: (job: KnowhereJob) => void | Promise<void>;
+    onJobUpdated?: (jobResult: KnowhereJobResult) => void | Promise<void>;
+}
+export interface KnowhereIngestResult {
+    job: KnowhereJob;
+    jobResult: KnowhereJobResult;
+    downloadedResult: KnowhereDownloadedResult;
+}
+export interface KnowhereScope {
+    mode: ScopeMode | "global";
+    key: string;
+    label: string;
+    rootDir: string;
+    documentsDir: string;
+    indexPath: string;
+}
+export interface StoredDocumentRecord {
+    id: string;
+    title: string;
+    sourceType: "file" | "url";
+    source: string;
+    sourceLabel: string;
+    fileName: string | null;
+    originalFileName: string | null;
+    dataId: string | null;
+    jobId: string | null;
+    checksum: string | null;
+    resultUrl: string | null;
+    resultUrlExpiresAt: string | null;
+    scopeLabel: string;
+    tags: string[];
+    ingestedAt: string;
+    updatedAt: string;
+    chunkCount: number;
+    statistics: KnowhereStatistics;
+}
+export interface StoredDocumentPayload {
+    version: number;
+    document: StoredDocumentRecord;
+    manifest: KnowhereManifest;
+    jobResult: KnowhereJobResult;
+    fullMarkdown: string;
+    hierarchy: unknown;
+    browseIndex: StoredBrowseIndex;
+    rawZipSha1: string;
+    chunks: StoredChunk[];
+}
+export interface StoredDocumentMetadata {
+    version: number;
+    document: StoredDocumentRecord;
+    jobResult: KnowhereJobResult;
+    rawZipSha1: string;
+}
+export interface KnowhereIndex {
+    version: number;
+    scopeMode: string;
+    scopeKey: string;
+    updatedAt: string | null;
+    documents: StoredDocumentRecord[];
+}
+export interface SaveStoredDocumentPayload {
+    sourceType: "file" | "url";
+    source: string;
+    sourceLabel?: string;
+    fileName: string | null;
+    docId?: string;
+    title?: string;
+    dataId?: string;
+    tags: string[];
+    job: KnowhereJob;
+    jobResult: KnowhereJobResult;
+    downloadedResult: KnowhereDownloadedResult;
+}
+export interface JsonSchemaObject {
+    [key: string]: unknown;
+}
+export interface ChannelRouteRecord {
+    readonly channelId: string;
+    readonly accountId: string;
+    readonly conversationId?: string;
+    readonly updatedAt: string;
+}
+export declare function isRecord(value: unknown): value is StringRecord;
+export declare function isNodeError(error: unknown): error is NodeJS.ErrnoException;
+export type KbIdSource = "disabled" | "agent" | "agent-session" | "global";
+export interface KnowledgeGraphConnectConfig {
+    minKeywordOverlap: number;
+    keywordScoreWeight: number;
+    maxConnectionsPerChunk: number;
+    minScoreThreshold: number;
+    crossFileOnly: boolean;
+    maxContentOverlap: number;
+}
+export interface KnowledgeGraphConfig {
+    enableKnowledgeGraph: boolean;
+    kbId?: string;
+    kbIdSource?: KbIdSource;
+    concurrentBuildStrategy?: "queue" | "skip";
+    buildTimeout?: number;
+    notifyOnGraphFailure?: boolean;
+    connectConfig?: Partial<KnowledgeGraphConnectConfig>;
+}
+export interface GraphConnection {
+    source: string;
+    target: string;
+    score: number;
+    sharedKeywords: string[];
+    connectionType: string;
+}
+/**
+ * File-level edge in knowledge graph (matches SKILL.md schema)
+ */
+export interface FileEdge {
+    source: string;
+    target: string;
+    connection_count: number;
+    avg_score: number;
+    top_connections: Array<{
+        source_chunk: string;
+        source_id: string;
+        target_chunk: string;
+        target_id: string;
+        relation: string;
+        score: number;
+    }>;
+}
+/**
+ * File metadata in knowledge graph (matches SKILL.md schema)
+ */
+export interface FileMetadata {
+    chunks_count: number;
+    types: Record<string, number>;
+    top_keywords: string[];
+    top_summary: string;
+    importance: number;
+}
+/**
+ * Knowledge graph structure (matches SKILL.md schema)
+ */
+export interface KnowledgeGraph {
+    version: string;
+    stats: {
+        total_files: number;
+        total_chunks: number;
+        total_cross_file_edges: number;
+    };
+    files: Record<string, FileMetadata>;
+    edges: FileEdge[];
+}
+export interface KbMetadata {
+    kbId: string;
+    createdAt: string;
+    lastUpdated: string;
+    documentCount: number;
+    config: Partial<KnowledgeGraphConnectConfig>;
+}

package/openclaw.plugin.json

@@ -3,7 +3,7 @@
   "name": "Knowhere",
   "description": "Parse documents with Knowhere and expose the stored result as tool-queryable document state for OpenClaw agents.",
   "skills": ["./skills"],
-  "version": "0.1.5",
+  "version": "0.2.2",
   "uiHints": {
     "apiKey": {
       "label": "Knowhere API Key",