@ontos-ai/knowhere-claw 0.2.7 → 0.2.8

package/dist/agent-hooks.js

@@ -10,10 +10,30 @@ const KNOWHERE_PROMPT_CONTEXT = [
 	"- If the file is in the cloud (e.g. Feishu Drive), first obtain the download URL via the appropriate channel tool, then use the `url` parameter.",
 	"- Refer to your **knowhere_memory** skill for the complete step-by-step workflow.",
 	"",
+	"### ⚠️ Feishu / Lark Cloud Files",
+	"**Never** pass a raw `open.feishu.cn` or `feishu.cn/drive/file/...` URL directly to `knowhere_ingest_document`.",
+	"These URLs require authentication and will redirect to a login page, causing Knowhere to parse HTML instead of the actual document.",
+	"Instead:",
+	"1. Use `feishu_drive` (action: `download`) or equivalents to obtain an **authenticated temporary download URL**.",
+	"2. Then pass that authenticated URL to `knowhere_ingest_document(url: ...)`.",
+	"",
+	"### Empty File Rejection",
+	"If a parsed result contains 0 usable chunks, it will be **automatically rejected** and not stored.",
+	"This typically means the source file was corrupt, empty, or required authentication that was not provided.",
+	"",
 	"### Knowledge Retrieval",
 	"When answering questions about documents or the knowledge base:",
 	"- ✅ Use `knowhere_get_map`, `knowhere_get_structure`, `knowhere_read_chunks`, `knowhere_kg_query`",
-	"- ❌ Do NOT use `exec` or shell commands to read files inside `~/.knowhere/`"
+	"- ❌ Do NOT use `exec` or shell commands to read files inside `~/.knowhere/`",
+	"",
+	"### 📷 Image Delivery",
+	"**`knowhere_read_chunks` has built-in automatic image delivery.** When it returns chunks containing images,",
+	"those images are automatically sent to the user's channel (Telegram/Feishu/etc). You do NOT need to send them again.",
+	"- The tool result will contain `resolved_assets` with `mode: 'image_sent'` for successfully delivered images.",
+	"- If the user asks to **see** or **view** an image from the knowledge base, call `knowhere_read_chunks` with the relevant section — images will be auto-delivered.",
+	"- `knowhere_view_image` is for **AI visual analysis only** (it loads image pixels into your context for you to describe/analyze). It does NOT send the image to the user.",
+	"- If the user asks you to re-send a specific image, use the `message` tool with the staged file path from `~/.openclaw/knowhere-assets/`.",
+	"- **Never tell the user you cannot send images.** You CAN — via `knowhere_read_chunks` auto-delivery or `message` tool."
 ].join("\n");
 const KNOWHERE_DIR_PATTERN = ".knowhere";
 const BLOCK_REASON = "Do not use exec to read .knowhere/ directly. Use knowhere retrieval tools instead: knowhere_get_map, knowhere_get_structure, knowhere_read_chunks, knowhere_kg_query.";

package/dist/index.js

@@ -50,7 +50,8 @@ const plugin = {
 			"knowhere_get_map",
 			"knowhere_get_structure",
 			"knowhere_read_chunks",
-			"knowhere_discover_files"
+			"knowhere_discover_files",
+			"knowhere_delete_document"
 		] });
 	}
 };

package/dist/kg-service.d.ts

@@ -23,6 +23,7 @@ export declare class KnowledgeGraphService {
         keywords: string[];
         metadata: Record<string, unknown>;
     }): Promise<void>;
+    removeDocumentFromKb(kbId: string, docId: string): Promise<void>;
     scheduleBuild(kbId: string, task: () => Promise<void>): Promise<void>;
     buildKnowledgeGraph(kbId: string): Promise<void>;
     private updateKbMetadata;

package/dist/kg-service.js

@@ -1,12 +1,20 @@
 import { resolveStoredKnowhereResultRoot } from "./parser.js";
 import { buildConnections, init_connect_builder } from "./connect-builder.js";
 import { buildKnowledgeGraph } from "./graph-builder.js";
+import fs from "node:fs/promises";
 import path from "node:path";
 import os from "node:os";
 import { spawn } from "node:child_process";
-import fs from "fs-extra";
+import fs$1 from "fs-extra";
 //#region src/kg-service.ts
 init_connect_builder();
+/**
+* Directories that belong to the Store layer and must be excluded when the KG
+* scans a kb directory for document entries.  This matters when the kb
+* directory coincides with the Store root (e.g. both resolve to
+* `~/.knowhere/global/`).
+*/
+const STORE_INFRA_DIRS = new Set(["documents", "metadata"]);
 const DEFAULT_CONNECT_CONFIG = {
 	minKeywordOverlap: 3,
 	keywordScoreWeight: 1,
@@ -101,19 +109,43 @@ var KnowledgeGraphService = class {
 	}
 	async ensureKbDirectory(kbId) {
 		const kbPath = this.getKbPath(kbId);
-		await fs.ensureDir(kbPath);
+		await fs$1.ensureDir(kbPath);
 		return kbPath;
 	}
 	async saveDocumentToKb(params) {
 		const kbPath = await this.ensureKbDirectory(params.kbId);
-		const docDir = path.join(kbPath, params.docId);
-		await fs.ensureDir(docDir);
+		const linkPath = path.join(kbPath, params.docId);
 		const sourceResultRoot = await resolveStoredKnowhereResultRoot(params.sourcePath);
-		await fs.copy(sourceResultRoot, docDir, { overwrite: true });
-		const metadataPath = path.join(docDir, "metadata.json");
-		await fs.writeJSON(metadataPath, params.metadata, { spaces: 2 });
+		try {
+			const existingStat = await fs.lstat(linkPath).catch(() => null);
+			if (existingStat) {
+				if (existingStat.isSymbolicLink()) if (await fs.readlink(linkPath) === sourceResultRoot) this.logger.debug?.(`knowhere: saveDocumentToKb symlink already correct doc=${params.docId}`);
+				else {
+					await fs.unlink(linkPath);
+					await fs.symlink(sourceResultRoot, linkPath);
+				}
+				else if (existingStat.isDirectory()) {
+					await fs$1.remove(linkPath);
+					await fs.symlink(sourceResultRoot, linkPath);
+					this.logger.info(`knowhere: saveDocumentToKb replaced legacy copy with symlink doc=${params.docId}`);
+				}
+			} else await fs.symlink(sourceResultRoot, linkPath);
+		} catch (symlinkError) {
+			this.logger.warn(`knowhere: symlink failed for doc=${params.docId}, falling back to copy: ${formatUnknownError(symlinkError)}`);
+			await fs$1.ensureDir(linkPath);
+			await fs$1.copy(sourceResultRoot, linkPath, { overwrite: true });
+		}
 		this.logger.info(`Document saved to knowledge base: kb=${params.kbId} doc=${params.docId}`);
 	}
+	async removeDocumentFromKb(kbId, docId) {
+		const kbPath = this.getKbPath(kbId);
+		const docPath = path.join(kbPath, docId);
+		const stat = await fs.lstat(docPath).catch(() => null);
+		if (!stat) return;
+		if (stat.isSymbolicLink()) await fs.unlink(docPath);
+		else if (stat.isDirectory()) await fs$1.remove(docPath);
+		this.logger.info(`Document removed from knowledge base: kb=${kbId} doc=${docId}`);
+	}
 	async scheduleBuild(kbId, task) {
 		if ((this.config.concurrentBuildStrategy || "queue") === "skip") {
 			if (this.buildQueues.has(kbId)) {
@@ -132,11 +164,12 @@ var KnowledgeGraphService = class {
 	}
 	async buildKnowledgeGraph(kbId) {
 		const kbPath = this.getKbPath(kbId);
-		const docs = await fs.readdir(kbPath);
+		const docs = await fs$1.readdir(kbPath);
 		const docDirs = [];
 		for (const doc of docs) {
+			if (doc.startsWith(".") || STORE_INFRA_DIRS.has(doc)) continue;
 			const docPath = path.join(kbPath, doc);
-			if ((await fs.stat(docPath)).isDirectory() && doc !== "knowledge_graph.json" && doc !== "chunk_stats.json" && doc !== "kb_metadata.json") docDirs.push(doc);
+			if ((await fs$1.stat(docPath).catch(() => null))?.isDirectory() && doc !== "knowledge_graph.json" && doc !== "chunk_stats.json" && doc !== "kb_metadata.json") docDirs.push(doc);
 		}
 		if (docDirs.length < 1) {
 			this.logger.info(`Not enough documents for graph building (need >=2, have ${docDirs.length}), skipping`);
@@ -147,8 +180,8 @@ var KnowledgeGraphService = class {
 			const allChunks = [];
 			for (const docDir of docDirs) {
 				const chunksPath = path.join(kbPath, docDir, "chunks.json");
-				if (await fs.pathExists(chunksPath)) {
-					const chunksData = await fs.readJSON(chunksPath);
+				if (await fs$1.pathExists(chunksPath)) {
+					const chunksData = await fs$1.readJSON(chunksPath);
 					if (chunksData.chunks && Array.isArray(chunksData.chunks)) allChunks.push(...chunksData.chunks.map((c) => ({
 						...c,
 						fileKey: docDir
@@ -164,10 +197,10 @@ var KnowledgeGraphService = class {
 			this.logger.info(`Built ${connections.length} connections`);
 			const chunkStatsPath = path.join(kbPath, "chunk_stats.json");
 			let chunkStats = {};
-			if (await fs.pathExists(chunkStatsPath)) chunkStats = await fs.readJSON(chunkStatsPath);
+			if (await fs$1.pathExists(chunkStatsPath)) chunkStats = await fs$1.readJSON(chunkStatsPath);
 			const knowledgeGraph = buildKnowledgeGraph(allChunks, connections, chunkStats, false, this.logger, kbId);
 			const graphFile = path.join(kbPath, "knowledge_graph.json");
-			await fs.writeJSON(graphFile, knowledgeGraph, { spaces: 2 });
+			await fs$1.writeJSON(graphFile, knowledgeGraph, { spaces: 2 });
 			this.logger.info(`Knowledge graph saved to ${graphFile}`);
 			await this.updateKbMetadata(kbPath, {
 				lastUpdated: (/* @__PURE__ */ new Date()).toISOString(),
@@ -182,34 +215,34 @@ var KnowledgeGraphService = class {
 	async updateKbMetadata(kbPath, updates) {
 		const metadataPath = path.join(kbPath, "kb_metadata.json");
 		let metadata = {};
-		if (await fs.pathExists(metadataPath)) metadata = await fs.readJSON(metadataPath);
+		if (await fs$1.pathExists(metadataPath)) metadata = await fs$1.readJSON(metadataPath);
 		const updated = {
 			...metadata,
 			...updates
 		};
-		await fs.writeJSON(metadataPath, updated, { spaces: 2 });
+		await fs$1.writeJSON(metadataPath, updated, { spaces: 2 });
 	}
 	async queryGraph(kbId, fileKey) {
 		const graphPath = path.join(this.getKbPath(kbId), "knowledge_graph.json");
-		if (!await fs.pathExists(graphPath)) return [];
-		const graph = await fs.readJSON(graphPath);
+		if (!await fs$1.pathExists(graphPath)) return [];
+		const graph = await fs$1.readJSON(graphPath);
 		if (!fileKey) return graph.edges;
 		return graph.edges.filter((edge) => edge.source === fileKey || edge.target === fileKey);
 	}
 	async getKnowledgeGraph(kbId) {
 		const graphPath = path.join(this.getKbPath(kbId), "knowledge_graph.json");
-		if (!await fs.pathExists(graphPath)) return null;
-		return await fs.readJSON(graphPath);
+		if (!await fs$1.pathExists(graphPath)) return null;
+		return await fs$1.readJSON(graphPath);
 	}
 	async listKnowledgeBases() {
 		const knowhereRoot = path.join(os.homedir(), ".knowhere");
-		if (!await fs.pathExists(knowhereRoot)) return [];
-		return (await fs.readdir(knowhereRoot, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name);
+		if (!await fs$1.pathExists(knowhereRoot)) return [];
+		return (await fs$1.readdir(knowhereRoot, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name);
 	}
 	async getKbMetadata(kbId) {
 		const metadataPath = path.join(this.getKbPath(kbId), "kb_metadata.json");
-		if (!await fs.pathExists(metadataPath)) return null;
-		return await fs.readJSON(metadataPath);
+		if (!await fs$1.pathExists(metadataPath)) return null;
+		return await fs$1.readJSON(metadataPath);
 	}
 	isEnabled() {
 		return this.degradationMode !== "disabled";

package/dist/tools.js

@@ -125,6 +125,11 @@ async function persistIngestedDocument(params) {
 		jobResult: params.ingestResult.jobResult,
 		downloadedResult: params.ingestResult.downloadedResult
 	}, { overwrite: params.overwrite });
+	if (storedDocument.chunkCount === 0) {
+		params.api.logger.warn(`knowhere: rejecting empty document scope=${params.scope.label} docId=${storedDocument.id} title=${JSON.stringify(storedDocument.title)} — chunkCount is 0; removing from store`);
+		await params.store.removeDocument(params.scope, storedDocument.id);
+		throw new Error(`Parsed result for "${storedDocument.title || storedDocument.id}" contains no usable content (0 chunks). The file may be corrupt, empty, or require authentication to download. For cloud files (e.g. Feishu Drive), make sure to obtain an authenticated download URL first.`);
+	}
 	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,
@@ -1046,7 +1051,10 @@ async function t2EnrichChunks(chunks, docDir) {
 		if (c.type === "image" && inlinedImagePaths.has(c.path)) return false;
 		return true;
 	});
-	return chunks;
+	return {
+		chunks,
+		inlinedImagePaths
+	};
 }
 async function replacePlaceholders(text, idToRaw, docDir, inlinedTablePaths, inlinedImagePaths, manifestPaths) {
 	const matches = [];
@@ -1222,6 +1230,15 @@ async function t2ResolveAssets(params) {
 			summary: chunk.summary || chunk.content?.slice(0, 200) || ""
 		});
 	}
+	if (params.enrichedImagePaths && params.enrichedImagePaths.size > 0) for (const relativePath of params.enrichedImagePaths) {
+		if (processedPaths.has(path.join(params.docDir, relativePath))) continue;
+		await resolveOne({
+			chunkId: relativePath,
+			type: "image",
+			relativePath,
+			summary: path.basename(relativePath)
+		});
+	}
 	return assets;
 }
 function createGetMapTool(_params) {
@@ -1436,7 +1453,8 @@ function createReadChunksTool(_params) {
 					await fs.writeFile(kgPath, JSON.stringify(g, null, 2), "utf-8");
 				}
 			} catch {}
-			chunks = await t2EnrichChunks(chunks, docDir);
+			const enrichResult = await t2EnrichChunks(chunks, docDir);
+			chunks = enrichResult.chunks;
 			let resolvedAssets = [];
 			try {
 				resolvedAssets = await t2ResolveAssets({
@@ -1444,7 +1462,8 @@ function createReadChunksTool(_params) {
 					store: _params.store,
 					ctx: _params.ctx,
 					docDir,
-					returnedChunks: chunks
+					returnedChunks: chunks,
+					enrichedImagePaths: enrichResult.inlinedImagePaths
 				});
 			} catch (err) {
 				_params.api.logger.debug?.(`knowhere: read_chunks asset resolution failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -1602,6 +1621,51 @@ function createDiscoverFilesTool(_params) {
 		}
 	};
 }
+function createDeleteDocumentTool(params) {
+	return {
+		name: "knowhere_delete_document",
+		label: "Knowhere Delete Document",
+		description: "Delete a parsed document from the underlying storage and remove it from the Knowledge Graph mapping. Use this to completely remove a document or file from the user's knowledge base. You must provide the exact docId obtained from knowhere_kg_query or the ingest result.",
+		parameters: {
+			type: "object",
+			additionalProperties: false,
+			properties: { docId: {
+				type: "string",
+				description: "The targeted document ID to delete."
+			} },
+			required: ["docId"]
+		},
+		execute: async (_toolCallId, rawParams) => {
+			const docId = readString((isRecord(rawParams) ? rawParams : {}).docId);
+			if (!docId) throw new Error("docId is required.");
+			const scope = params.store.resolveScope(params.ctx);
+			const kbId = params.kgService.resolveKbId(params.ctx);
+			let wasRemovedFromStore = false;
+			try {
+				if (await params.store.removeDocument(scope, docId)) {
+					wasRemovedFromStore = true;
+					params.api.logger.info(`knowhere: document ${docId} removed from store`);
+				}
+			} catch (error) {
+				params.api.logger.warn(`knowhere: store.removeDocument failed for ${docId}: ${formatErrorMessage(error)}`);
+			}
+			let wasRemovedFromKg = false;
+			if (kbId) try {
+				await params.kgService.removeDocumentFromKb(kbId, docId);
+				wasRemovedFromKg = true;
+				params.kgService.scheduleBuild(kbId, async () => {
+					await params.kgService.buildKnowledgeGraph(kbId);
+				}).catch((e) => {
+					params.api.logger.warn(`knowhere: rebuild failed after doc removal: ${formatErrorMessage(e)}`);
+				});
+			} catch (error) {
+				params.api.logger.warn(`knowhere: kgService.removeDocumentFromKb failed for ${docId}: ${formatErrorMessage(error)}`);
+			}
+			if (wasRemovedFromStore || wasRemovedFromKg) return textResult(`Success: The document "${docId}" has been deleted from the knowledge base.\nThe Knowledge Graph is being rebuilt in the background.`);
+			else return textResult(`Failed: The document "${docId}" could not be found or removed.`);
+		}
+	};
+}
 function createKnowhereToolFactory(params) {
 	return (ctx) => [
 		createIngestTool({
@@ -1652,7 +1716,13 @@ function createKnowhereToolFactory(params) {
 			ctx
 		}),
 		createViewImageTool({ api: params.api }),
-		createDiscoverFilesTool({ api: params.api })
+		createDiscoverFilesTool({ api: params.api }),
+		createDeleteDocumentTool({
+			api: params.api,
+			store: params.store,
+			kgService: params.kgService,
+			ctx
+		})
 	];
 }
 //#endregion

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.2.7",
+  "version": "0.2.8",
   "uiHints": {
     "apiKey": {
       "label": "Knowhere API Key",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontos-ai/knowhere-claw",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "OpenClaw plugin for Knowhere-powered document ingestion and automatic grounding.",
   "files": [
     "dist/",

package/skills/knowhere_memory/SKILL.md

@@ -55,8 +55,10 @@ The plugin handles everything automatically:
 - Uploads/fetches the file for parsing
 - Polls until parsing completes
 - Downloads and extracts the result package
-- Copies parsed data to `~/.knowhere/{kbId}/`
+- Stores parsed data under `~/.knowhere/global/documents/{docId}/`
+- Creates a symlink in `~/.knowhere/{kbId}/{docId}` → the stored document
 - Builds/updates `knowledge_graph.json`
+- **Rejects** files that parse to 0 chunks (empty, corrupt, or auth-gated)
 
 After ingest completes, the new document is immediately searchable via the retrieval workflow below.
 
@@ -70,14 +72,21 @@ All knowledge data lives under `~/.knowhere/{kb_id}/`:
 
 ```text
 ~/.knowhere/
-└── {kb_id}/                          # e.g. "telegram"
+├── global/                           # Store: document storage (scopeMode=global)
+│   ├── index.json                    # Store document index
+│   ├── documents/
+│   │   └── {docId}/                  # One subdir per parsed document
+│   │       ├── chunks.json           # All chunks (the actual content)
+│   │       ├── hierarchy.json        # Document structure tree
+│   │       ├── images/               # Extracted images
+│   │       └── tables/               # Extracted tables (HTML)
+│   └── metadata/
+│       └── {docId}.json              # Document metadata
+└── {kb_id}/                          # KG: knowledge graph layer
     ├── knowledge_graph.json          # File-level overview + cross-file edges
+    ├── kb_metadata.json              # KG metadata
     ├── chunk_stats.json              # Usage stats per chunk
-    └── {document_name}/              # One subdir per parsed document
-        ├── chunks.json               # All chunks (the actual content)
-        ├── hierarchy.json            # Document structure tree
-        ├── images/                   # Extracted images
-        └── tables/                   # Extracted tables (HTML)
+    └── {docId} → ../global/documents/{docId}   # Symlink to Store
 ```
 
 ### Strategy: Prefer tools, fall back to files
@@ -165,3 +174,19 @@ Check `edges` from Step 1 for cross-document connections. If related files weren
 - **Show connections**: mention cross-file relationships from edges
 - **No internal IDs**: never expose `chunk_id` or UUID paths to the user
 - **User's language**: reply in the same language the user is using
+
+## Part 3: Deleting Knowledge
+
+When the user asks to "delete", "remove", or "forget" a specific document:
+
+1. Use `knowhere_kg_query` to search the Knowledge Graph to find the correct `docId` that uniquely identifies the document.
+2. If the user provided a filename, use it to disambiguate and cross-check multiple hits.
+3. Call `knowhere_delete_document` with the discovered `docId`.
+
+The `knowhere_delete_document` tool natively handles all internal consistency logic:
+
+- Deeply cleaning up the `chunks.json`, `images/`, and `tables/` locally.
+- Removing the symlink mapping from the knowledge base profile.
+- Dispatching a background rebuild for `knowledge_graph.json` so that the reference disappears from future queries.
+
+**Rule:** DO NOT try to execute Unix file deletion (`rm`) commands on `~/.knowhere/` directly. Always use `knowhere_delete_document`.