@ontos-ai/knowhere-claw 0.2.8 → 0.2.9

package/README.md

@@ -122,6 +122,12 @@ Within each scope, the plugin keeps:
 4. When needed, the agent can preview structure, search chunks, read raw result
    files, or clear stored documents.
 
+## Schema v2.1 Media Handling
+
+- `knowhere_read_chunks` now treats `[images/...]` and `[tables/...]` path references in `chunks.json` content as the primary media enrichment path.
+- Standalone `image` and `table` chunks resolve their real asset locations from `metadata.file_path`.
+- Assets without `metadata.file_path` are ignored by the runtime enrichment and delivery pipeline.
+
 ## Troubleshooting
 
 - Missing API key: `apiKey` config is optional. You can set

package/dist/__tests__/read-chunks-schema-v21.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/agent-hooks.js

@@ -22,9 +22,13 @@ const KNOWHERE_PROMPT_CONTEXT = [
 	"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`",
+	"Use this **single retrieval path** — do not skip steps:",
+	"1. `knowhere_get_map` — get the KG overview: which files exist, their keywords, importance, and cross-file edges.",
+	"2. `knowhere_get_structure` — inspect the chapter/section hierarchy of a specific document.",
+	"3. `knowhere_read_chunks` — fetch content for a specific section (use `sectionPath` to narrow scope).",
+	"If you're unsure which file contains the answer, also call `knowhere_discover_files` for keyword-based file discovery.",
 	"- ❌ Do NOT use `exec` or shell commands to read files inside `~/.knowhere/`",
+	"- ❌ Do NOT skip `knowhere_get_map` and jump directly to `knowhere_read_chunks`",
 	"",
 	"### 📷 Image Delivery",
 	"**`knowhere_read_chunks` has built-in automatic image delivery.** When it returns chunks containing images,",

package/dist/index.js

@@ -45,11 +45,10 @@ const plugin = {
 			"knowhere_get_job_status",
 			"knowhere_import_completed_job",
 			"knowhere_set_api_key",
-			"knowhere_kg_list",
-			"knowhere_kg_query",
 			"knowhere_get_map",
 			"knowhere_get_structure",
 			"knowhere_read_chunks",
+			"knowhere_view_image",
 			"knowhere_discover_files",
 			"knowhere_delete_document"
 		] });

package/dist/tools.d.ts

@@ -2,9 +2,69 @@ import { type AnyAgentTool, type OpenClawPluginApi } from "openclaw/plugin-sdk/c
 import { KnowhereStore } from "./store";
 import type { KnowledgeGraphService } from "./kg-service";
 import type { ResolvedKnowhereConfig, ToolRuntimeContext } from "./types";
+interface T2ChunkRelation {
+    relation?: string;
+    target?: string;
+    ref?: string;
+    [key: string]: unknown;
+}
+interface T2ChunkMetadata {
+    summary?: string;
+    keywords?: string[];
+    tokens?: string[];
+    file_path?: string;
+    connect_to?: T2ChunkRelation[];
+    [key: string]: unknown;
+}
+interface T2ChunkSlim {
+    chunk_id?: string;
+    type: string;
+    path: string;
+    content: string;
+    summary: string;
+    file_path?: string;
+    connect_to?: T2ChunkRelation[];
+    metadata?: T2ChunkMetadata;
+}
+interface T2EnrichResult {
+    chunks: T2ChunkSlim[];
+    /** Image paths that were inlined into text via placeholder replacement (need delivery). */
+    inlinedImagePaths: ReadonlySet<string>;
+}
+/**
+ * Runtime-only enrichment of chunks returned to the AI:
+ * 1. Prefer Schema v2.1 path refs ([images/...], [tables/...]) in text chunks
+ * 2. Normalize standalone image/table chunks to file_path-based content
+ * 3. Remove standalone table/image chunks that were already inlined into text
+ *
+ * Does NOT modify chunks.json on disk.
+ */
+declare function t2EnrichChunks(chunks: T2ChunkSlim[], docDir: string): Promise<T2EnrichResult>;
+interface T2ResolvedAsset {
+    chunk_id: string;
+    type: "image" | "table";
+    relative_path: string;
+    summary: string;
+    mode: "image_sent" | "image_failed" | "table_inline";
+    html_content?: string;
+}
+declare function t2ResolveAssets(params: {
+    api: OpenClawPluginApi;
+    store: KnowhereStore;
+    ctx: ToolRuntimeContext;
+    docDir: string;
+    returnedChunks: T2ChunkSlim[];
+    /** Image paths inlined by t2EnrichChunks that still need channel delivery. */
+    enrichedImagePaths?: ReadonlySet<string>;
+}): Promise<T2ResolvedAsset[]>;
 export declare function createKnowhereToolFactory(params: {
     api: OpenClawPluginApi;
     config: ResolvedKnowhereConfig;
     store: KnowhereStore;
     kgService: KnowledgeGraphService;
 }): (ctx: ToolRuntimeContext) => AnyAgentTool[];
+export declare const __internal: {
+    t2EnrichChunks: typeof t2EnrichChunks;
+    t2ResolveAssets: typeof t2ResolveAssets;
+};
+export {};

package/dist/tools.js

@@ -964,13 +964,7 @@ async function t2LoadChunks(docDir) {
 		if (Array.isArray(data)) chunks = data;
 		else if (isRecord(data) && Array.isArray(data.chunks)) chunks = data.chunks;
 		else continue;
-		if (fname === "chunks.json") return chunks.map((c) => ({
-			type: c.type || "text",
-			path: c.path || "",
-			content: c.content || "",
-			summary: c.metadata?.summary || c.summary || ""
-		}));
-		return chunks;
+		return chunks.map((c) => t2ToSlimChunk(c));
 	} catch {
 		continue;
 	}
@@ -979,7 +973,68 @@ async function t2LoadChunks(docDir) {
 function t2NormalizePath(s) {
 	return s.replace(/[\uFF01-\uFF5E]/g, (ch) => String.fromCharCode(ch.charCodeAt(0) - 65248)).replace(/[\s\u3000\u00A0]+/g, "").toLowerCase();
 }
-const PLACEHOLDER_RE = /(?:IMAGE|TABLE)_([a-f0-9-]+)_(?:IMAGE|TABLE)/g;
+const PATH_REF_RE = /\[((?:images|tables)\/[^\]\n]+)\]/g;
+function t2ReadConnectTo(value) {
+	if (!Array.isArray(value)) return;
+	const relations = value.filter(isRecord);
+	return relations.length > 0 ? relations : void 0;
+}
+function t2GetChunkFilePath(chunk) {
+	if (typeof chunk.file_path === "string" && chunk.file_path) return chunk.file_path;
+	if (typeof chunk.metadata?.file_path === "string" && chunk.metadata.file_path) return chunk.metadata.file_path;
+}
+function t2GetChunkAssetPath(chunk) {
+	return t2GetChunkFilePath(chunk);
+}
+function t2ToSlimChunk(chunk) {
+	const connectTo = t2ReadConnectTo(chunk.metadata?.connect_to);
+	const filePath = t2GetChunkFilePath(chunk);
+	return {
+		chunk_id: chunk.chunk_id || void 0,
+		type: chunk.type || "text",
+		path: chunk.path || "",
+		content: chunk.content || "",
+		summary: chunk.metadata?.summary || chunk.summary || "",
+		file_path: filePath,
+		connect_to: connectTo,
+		metadata: chunk.metadata ? {
+			...chunk.metadata,
+			file_path: filePath,
+			connect_to: connectTo
+		} : void 0
+	};
+}
+function t2HydrateChunk(chunk, idToRaw, pathToRaw) {
+	const raw = (chunk.chunk_id ? idToRaw.get(chunk.chunk_id) : void 0) || (chunk.path ? pathToRaw.get(chunk.path) : void 0);
+	if (!raw) return chunk;
+	const rawFilePath = t2GetChunkFilePath(raw);
+	const connectTo = chunk.connect_to || t2ReadConnectTo(raw.metadata?.connect_to);
+	return {
+		...chunk,
+		chunk_id: chunk.chunk_id || raw.chunk_id,
+		file_path: chunk.file_path || rawFilePath,
+		connect_to: connectTo,
+		metadata: {
+			...raw.metadata || {},
+			...chunk.metadata || {},
+			file_path: chunk.file_path || rawFilePath,
+			connect_to: connectTo
+		}
+	};
+}
+async function t2ReadTableHtml(docDir, relativePath) {
+	try {
+		return await fs.readFile(path.join(docDir, relativePath), "utf-8");
+	} catch {
+		return null;
+	}
+}
+function t2HasUnresolvedMediaReference(text) {
+	PATH_REF_RE.lastIndex = 0;
+	const hasPathRef = PATH_REF_RE.test(text);
+	PATH_REF_RE.lastIndex = 0;
+	return hasPathRef;
+}
 async function t2LoadRawChunks(docDir) {
 	try {
 		const raw = await fs.readFile(path.join(docDir, "chunks.json"), "utf-8");
@@ -993,62 +1048,59 @@ async function t2LoadRawChunks(docDir) {
 }
 /**
 * Runtime-only enrichment of chunks returned to the AI:
-* 1. Replace IMAGE_uuid_IMAGE placeholders with [📷 path] in text chunks
-* 2. Replace TABLE_uuid_TABLE placeholders with actual HTML content in text chunks
-* 3. Remove standalone table chunks that were inlined via placeholders
-* 4. Strip self-referencing placeholders from image/table chunk content & summary
+* 1. Prefer Schema v2.1 path refs ([images/...], [tables/...]) in text chunks
+* 2. Normalize standalone image/table chunks to file_path-based content
+* 3. Remove standalone table/image chunks that were already inlined into text
 *
 * Does NOT modify chunks.json on disk.
 */
 async function t2EnrichChunks(chunks, docDir) {
 	const rawChunks = await t2LoadRawChunks(docDir);
 	const idToRaw = /* @__PURE__ */ new Map();
-	for (const rc of rawChunks) if (rc.chunk_id) idToRaw.set(rc.chunk_id, rc);
-	const manifestPaths = /* @__PURE__ */ new Map();
-	try {
-		const manifest = JSON.parse(await fs.readFile(path.join(docDir, "manifest.json"), "utf-8"));
-		if (isRecord(manifest) && isRecord(manifest.files)) {
-			const files = manifest.files;
-			for (const entry of Array.isArray(files.images) ? files.images : []) if (typeof entry.id === "string" && typeof entry.file_path === "string") manifestPaths.set(entry.id, {
-				type: "image",
-				filePath: entry.file_path
-			});
-			for (const entry of Array.isArray(files.tables) ? files.tables : []) if (typeof entry.id === "string" && typeof entry.file_path === "string") manifestPaths.set(entry.id, {
-				type: "table",
-				filePath: entry.file_path
-			});
-		}
-	} catch {}
+	const pathToRaw = /* @__PURE__ */ new Map();
+	for (const rc of rawChunks) {
+		if (rc.chunk_id) idToRaw.set(rc.chunk_id, rc);
+		if (rc.path) pathToRaw.set(rc.path, rc);
+	}
+	chunks = chunks.map((chunk) => t2HydrateChunk(chunk, idToRaw, pathToRaw));
 	const inlinedTablePaths = /* @__PURE__ */ new Set();
 	const inlinedImagePaths = /* @__PURE__ */ new Set();
 	for (const chunk of chunks) {
-		if (!chunk.content) continue;
-		PLACEHOLDER_RE.lastIndex = 0;
-		if (PLACEHOLDER_RE.test(chunk.content)) {
-			PLACEHOLDER_RE.lastIndex = 0;
-			chunk.content = await replacePlaceholders(chunk.content, idToRaw, docDir, chunk.type === "text" ? inlinedTablePaths : void 0, chunk.type === "text" ? inlinedImagePaths : void 0, manifestPaths);
-			PLACEHOLDER_RE.lastIndex = 0;
-			if (chunk.type !== "text" && chunk.path && PLACEHOLDER_RE.test(chunk.content)) {
-				if (chunk.type === "table") try {
-					const html = await fs.readFile(path.join(docDir, chunk.path), "utf-8");
-					chunk.content = chunk.content.replace(PLACEHOLDER_RE, `\n${html.slice(0, 8e3)}\n`);
-				} catch {
-					chunk.content = chunk.content.replace(PLACEHOLDER_RE, `[📊 ${chunk.path}]`);
-				}
-				else if (chunk.type === "image") chunk.content = chunk.content.replace(PLACEHOLDER_RE, `[📷 ${chunk.path}]`);
-			}
+		const relativePath = t2GetChunkAssetPath(chunk);
+		if (!relativePath) continue;
+		chunk.file_path = relativePath;
+		chunk.metadata = {
+			...chunk.metadata || {},
+			file_path: relativePath,
+			connect_to: chunk.connect_to
+		};
+		if (chunk.type === "image") {
+			chunk.content = `[📷 ${relativePath}]`;
+			continue;
 		}
-		if (chunk.summary) {
-			PLACEHOLDER_RE.lastIndex = 0;
-			if (PLACEHOLDER_RE.test(chunk.summary)) {
-				PLACEHOLDER_RE.lastIndex = 0;
-				chunk.summary = await replacePlaceholders(chunk.summary, idToRaw, docDir, void 0, void 0, manifestPaths);
+		if (chunk.type === "table") {
+			const html = await t2ReadTableHtml(docDir, relativePath);
+			if (html) chunk.content = html.slice(0, 8e3);
+			else if (!chunk.content) chunk.content = `[📊 ${relativePath}]`;
+		}
+	}
+	for (const chunk of chunks) {
+		const relativePath = t2GetChunkAssetPath(chunk);
+		if (chunk.content) {
+			if (chunk.type === "text") chunk.content = await replacePathReferences(chunk.content, docDir, inlinedTablePaths, inlinedImagePaths);
+			if (chunk.type !== "text" && relativePath && t2HasUnresolvedMediaReference(chunk.content)) {
+				if (chunk.type === "table") {
+					const html = await t2ReadTableHtml(docDir, relativePath);
+					chunk.content = html ? html.slice(0, 8e3) : `[📊 ${relativePath}]`;
+				} else if (chunk.type === "image") chunk.content = `[📷 ${relativePath}]`;
 			}
 		}
+		if (chunk.summary) chunk.summary = await replacePathReferences(chunk.summary, docDir);
 	}
 	chunks = chunks.filter((c) => {
-		if (c.type === "table" && inlinedTablePaths.has(c.path)) return false;
-		if (c.type === "image" && inlinedImagePaths.has(c.path)) return false;
+		const relativePath = t2GetChunkAssetPath(c) || "";
+		if (c.type === "table" && relativePath && inlinedTablePaths.has(relativePath)) return false;
+		if (c.type === "image" && relativePath && inlinedImagePaths.has(relativePath)) return false;
 		return true;
 	});
 	return {
@@ -1056,50 +1108,33 @@ async function t2EnrichChunks(chunks, docDir) {
 		inlinedImagePaths
 	};
 }
-async function replacePlaceholders(text, idToRaw, docDir, inlinedTablePaths, inlinedImagePaths, manifestPaths) {
+async function replacePathReferences(text, docDir, inlinedTablePaths, inlinedImagePaths) {
 	const matches = [];
-	const re = /(?:(IMAGE|TABLE))_([a-f0-9-]+)_(?:IMAGE|TABLE)/g;
-	let m;
-	while ((m = re.exec(text)) !== null) matches.push({
-		full: m[0],
-		type: m[1],
-		id: m[2],
-		start: m.index,
-		end: m.index + m[0].length
+	let match;
+	PATH_REF_RE.lastIndex = 0;
+	while ((match = PATH_REF_RE.exec(text)) !== null) matches.push({
+		full: match[0],
+		relativePath: match[1],
+		start: match.index,
+		end: match.index + match[0].length
 	});
+	PATH_REF_RE.lastIndex = 0;
 	if (matches.length === 0) return text;
 	const replacements = [];
-	for (const match of matches) {
-		const raw = idToRaw.get(match.id);
-		let resolvedPath = raw?.path;
-		if (!resolvedPath && manifestPaths) {
-			const mEntry = manifestPaths.get(match.id);
-			if (mEntry) resolvedPath = mEntry.filePath;
-		}
-		if (!resolvedPath) {
-			replacements.push(match.full);
+	for (const ref of matches) {
+		if (ref.relativePath.startsWith("images/")) {
+			replacements.push(`[📷 ${ref.relativePath}]`);
+			inlinedImagePaths?.add(ref.relativePath);
 			continue;
 		}
-		if (match.type === "IMAGE") {
-			replacements.push(`[📷 ${resolvedPath}]`);
-			inlinedImagePaths?.add(resolvedPath);
-		} else {
-			const htmlPath = path.join(docDir, resolvedPath);
-			try {
-				const html = await fs.readFile(htmlPath, "utf-8");
-				replacements.push(`\n${html.slice(0, 8e3)}\n`);
-				inlinedTablePaths?.add(resolvedPath);
-			} catch {
-				const tableContent = raw?.content || "";
-				if (tableContent && tableContent.includes("<")) {
-					replacements.push(`\n${tableContent}\n`);
-					inlinedTablePaths?.add(resolvedPath);
-				} else replacements.push(`[📊 ${resolvedPath}]`);
-			}
-		}
+		const html = await t2ReadTableHtml(docDir, ref.relativePath);
+		if (html) {
+			replacements.push(`\n${html.slice(0, 8e3)}\n`);
+			inlinedTablePaths?.add(ref.relativePath);
+		} else replacements.push(`[📊 ${ref.relativePath}]`);
 	}
 	let result = text;
-	for (let i = matches.length - 1; i >= 0; i--) result = result.slice(0, matches[i].start) + replacements[i] + result.slice(matches[i].end);
+	for (let index = matches.length - 1; index >= 0; index -= 1) result = result.slice(0, matches[index].start) + replacements[index] + result.slice(matches[index].end);
 	return result;
 }
 function t2ComputeTfIdfKeywords(rawChunks, topK = 10) {
@@ -1221,14 +1256,17 @@ async function t2ResolveAssets(params) {
 			params.api.logger.debug?.(`knowhere: t2ResolveAssets image delivery failed: ${absolutePath} — ${err instanceof Error ? err.message : String(err)}`);
 		}
 	};
-	for (const chunk of params.returnedChunks) if ((chunk.type === "image" || chunk.type === "table") && chunk.path) {
-		if (chunk.type === "table" && chunk.content && !/TABLE_[a-f0-9-]+_TABLE/.test(chunk.content)) continue;
-		await resolveOne({
-			chunkId: chunk.path,
-			type: chunk.type,
-			relativePath: chunk.path,
-			summary: chunk.summary || chunk.content?.slice(0, 200) || ""
-		});
+	for (const chunk of params.returnedChunks) {
+		const relativePath = t2GetChunkAssetPath(chunk);
+		if ((chunk.type === "image" || chunk.type === "table") && relativePath) {
+			if (chunk.type === "table" && chunk.content && !t2HasUnresolvedMediaReference(chunk.content)) continue;
+			await resolveOne({
+				chunkId: chunk.chunk_id || relativePath,
+				type: chunk.type,
+				relativePath,
+				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;

package/dist/types.d.ts

@@ -232,7 +232,8 @@ export interface FileEdge {
     }>;
 }
 /**
- * File metadata in knowledge graph (matches SKILL.md schema)
+ * File metadata in knowledge graph (v2.0 schema — matches graph-builder.ts output).
+ * `hit_count` and `last_hit` are maintained at runtime by `knowhere_read_chunks`.
  */
 export interface FileMetadata {
     chunks_count: number;
@@ -240,12 +241,22 @@ export interface FileMetadata {
     top_keywords: string[];
     top_summary: string;
     importance: number;
+    /** ISO timestamp of when this file entry was first created in the graph. */
+    created_at: string;
+    /** Number of times chunks from this file have been read via knowhere_read_chunks. */
+    hit_count?: number;
+    /** ISO timestamp of the last knowhere_read_chunks access for this file. */
+    last_hit?: string;
 }
 /**
- * Knowledge graph structure (matches SKILL.md schema)
+ * Knowledge graph structure (v2.0 schema — matches graph-builder.ts output).
  */
 export interface KnowledgeGraph {
     version: string;
+    /** ISO timestamp of the last graph build or partial update. */
+    updated_at: string;
+    /** Knowledge base ID this graph belongs to. */
+    kb_id: string;
     stats: {
         total_files: number;
         total_chunks: number;

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

package/package.json

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

package/skills/knowhere_memory/SKILL.md

@@ -89,17 +89,19 @@ All knowledge data lives under `~/.knowhere/{kb_id}/`:
     └── {docId} → ../global/documents/{docId}   # Symlink to Store
 ```
 
-### Strategy: Prefer tools, fall back to files
+### Strategy: Use the Tier-2 retrieval tools
 
-#### If `knowhere_kg_list` / `knowhere_kg_query` tools are available → use them
+The canonical retrieval path is **always** the Tier-2 tool chain — do not skip steps:
 
-These tools provide efficient access to the knowledge graph:
+1. `knowhere_get_map` — get the full KG overview: which files exist, their keywords, importance scores, and cross-file edges. Pass `kbId` if known, or leave empty to scan all knowledge bases.
+2. `knowhere_discover_files` — if you're unsure which file contains the answer, run a keyword search across all KB documents and merge with the `get_map` results.
+3. `knowhere_get_structure` — inspect the chapter/section hierarchy of the most relevant document.
+4. `knowhere_read_chunks` — fetch the actual content. Use `sectionPath` to narrow to the specific chapter and minimize token usage.
 
-1. `knowhere_kg_list` — list all available knowledge bases
-2. `knowhere_kg_query(kbId)` — returns the full knowledge graph (files, keywords, edges)
-3. Then read individual `chunks.json` files with your file reading tool for detailed content
+❌ Do **not** use `exec` or shell commands to read `~/.knowhere/` files directly.
+❌ Do **not** skip `knowhere_get_map` and jump straight to `knowhere_read_chunks`.
 
-#### If no KG tools are available → self-navigate using file tools
+#### If no Knowhere tools are available → self-navigate using file tools
 
 Follow this pattern — do NOT explore the filesystem blindly:
 
@@ -115,13 +117,17 @@ Read `~/.knowhere/{kb_id}/knowledge_graph.json`:
 ```json
 {
   "version": "2.0",
-  "stats": { "total_files": 5, "total_chunks": 327 },
+  "updated_at": "2026-04-09T10:00:00.000Z",
+  "kb_id": "telegram",
+  "stats": { "total_files": 5, "total_chunks": 327, "total_cross_file_edges": 12 },
   "files": {
     "report.docx": {
       "chunks_count": 198,
       "types": { "text": 135, "table": 21, "image": 42 },
       "top_keywords": ["excavation", "retaining", "construction"],
-      "importance": 0.85
+      "top_summary": "Construction safety report for the Lujiazui project.",
+      "importance": 0.85,
+      "created_at": "2026-04-09T08:00:00.000Z"
     }
   },
   "edges": [
@@ -129,8 +135,16 @@ Read `~/.knowhere/{kb_id}/knowledge_graph.json`:
       "source": "file_A.docx",
       "target": "file_B.pdf",
       "connection_count": 20,
+      "avg_score": 0.91,
       "top_connections": [
-        { "source_chunk": "Chapter 3", "target_chunk": "Safety Policy", "score": 1.0 }
+        {
+          "source_chunk": "Chapter 3",
+          "source_id": "uuid-a",
+          "target_chunk": "Safety Policy",
+          "target_id": "uuid-b",
+          "relation": "keyword",
+          "score": 1.0
+        }
       ]
     }
   ]
@@ -179,8 +193,8 @@ Check `edges` from Step 1 for cross-document connections. If related files weren
 
 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.
+1. Use `knowhere_get_map` to get an overview of all files in the knowledge base, then identify the correct `docId` that uniquely corresponds to the document the user named.
+2. If the user provided a filename, use it to disambiguate across multiple hits.
 3. Call `knowhere_delete_document` with the discovered `docId`.
 
 The `knowhere_delete_document` tool natively handles all internal consistency logic: