@dikolab/kbdb 0.1.5 → 0.2.0

package/README.md

@@ -88,22 +88,40 @@ search index.
 kbdb search "how does auth work" --db ./my-kb
 ```
 
-Results are ranked by relevance. Headings and code
-get extra weight so the most useful sections surface
-first.
+Results are ranked by relevance with snippets
+showing matched terms in context. Use `--offset`
+to page through large result sets.
+
+**4. Recall context**
+
+```sh
+kbdb recall <kbid> --depth 1 --db ./my-kb
+```
+
+Start with a search result's kbid and expand
+context progressively: depth 0 gives the section
+content, depth 1 adds parent documents and
+back-references, depth 2 adds siblings and forward
+references, depth 3 includes full text of
+referenced sections.
 
 ---
 
 ## What Can It Do?
 
 - **Import** Markdown files and other documents
-- **Search** with ranked results and flexible
-  query syntax
+- **Search** with ranked results, snippets, and
+  paginated output
+- **Recall** sections with progressive context --
+  from a quick summary to full related content
+- **Skills** -- store reusable prompt templates
+  with placeholder arguments
+- **Agents** -- create AI agent profiles that
+  combine a persona with skills
 - **Manage** documents, sections, and metadata
 - **Verify** database integrity and clean up
   unused data
 - **Rebuild** indexes if anything goes wrong
-- **Check status** of your knowledge base
 
 See the [CLI Reference](docs/details/cli.md)
 for the full command list and examples.
@@ -113,8 +131,9 @@ for the full command list and examples.
 ## Use It With AI Agents
 
 kbdb runs as an
-[MCP](https://modelcontextprotocol.io/) server,
-so AI agents can search your docs, store reusable
+[MCP](https://modelcontextprotocol.io/) server
+with 18 tools, so AI agents can search your docs,
+recall context progressively, store reusable
 skills, and build agent profiles -- a second brain
 that persists between sessions.
 
@@ -208,9 +227,11 @@ const client = await createWorkerClient({
 const results = await client.search({
    query: 'authentication',
    limit: 10,
+   offset: 0,
 });
 
-console.log(results);
+// results = { items, total, offset, limit, has_more }
+console.log(results.items);
 client.disconnect();
 ```
 

package/dist/cli.cjs

@@ -118,6 +118,13 @@ function parseArgs(argv) {
       case "-l":
         options.limit = parseInt(argv[++i] ?? "", 10) || DEFAULT_LIMIT;
         break;
+      case "--offset":
+      case "-o":
+        options.offset = Math.max(
+          0,
+          parseInt(argv[++i] ?? "", 10) || 0
+        );
+        break;
       case "--title":
         options.title = argv[++i];
         break;
@@ -158,29 +165,39 @@ function parseArgs(argv) {
 }
 
 // src/shared/cli/functions/format-output.function.ts
-function formatOutput(results, format) {
+function formatOutput(paged, format) {
   switch (format) {
     case "json":
-      return JSON.stringify(results, null, 2);
+      return JSON.stringify(paged, null, 2);
     case "text":
-      return formatText(results);
+      return formatText(paged);
     case "mcp":
-      return formatMcp(results);
-  }
-}
-function formatText(results) {
-  if (results.length === 0) return "No results found.";
-  return results.map(
-    (r, i) => `${String(i + 1)}. [${r.kbid}] (score: ${r.score.toFixed(4)})
-   ${r.preview}
-   matches: ${r.matches.map((m) => m.term).join(", ")}`
-  ).join("\n\n");
-}
-function formatMcp(results) {
+      return formatMcp(paged);
+  }
+}
+function formatText(paged) {
+  if (paged.items.length === 0) return "No results found.";
+  const start = paged.offset + 1;
+  const end = paged.offset + paged.items.length;
+  const lines = paged.items.map((r, i) => {
+    const num = paged.offset + i + 1;
+    const heading = r.heading ?? "(untitled)";
+    const terms = r.matched_terms.join(", ");
+    return `${String(num)}. [${r.kbid}] ${heading} (score: ${r.score.toFixed(4)})
+   ${r.snippet || r.preview || "(no snippet)"}
+   type: ${r.type}  terms: ${terms}`;
+  }).join("\n\n");
+  const footer = `
+Showing ${String(start)}-${String(end)} of ${String(paged.total)} results`;
+  const hint = paged.has_more ? `
+Use --offset ${String(end)} to see more` : "";
+  return lines + footer + hint;
+}
+function formatMcp(paged) {
   return JSON.stringify({
     type: "text",
-    text: results.map(
-      (r) => `[${r.kbid}] score=${r.score.toFixed(4)} \u2014 ${r.preview}`
+    text: paged.items.map(
+      (r) => `[${r.kbid}] ${r.heading ?? "(untitled)"} \u2014 ${r.snippet || r.preview}`
     ).join("\n")
   });
 }
@@ -188,18 +205,37 @@ function formatMcp(results) {
 // src/shared/cli/functions/run-search.function.ts
 async function runSearch(client, options) {
   const query = options.args.join(" ").trim();
-  if (!query) return [];
+  if (!query) {
+    return {
+      items: [],
+      total: 0,
+      offset: 0,
+      limit: options.limit,
+      has_more: false
+    };
+  }
   const results = await client.search({
     query,
     mode: options.mode,
-    limit: options.limit
+    limit: options.limit,
+    offset: options.offset
   });
-  return results.map((r) => ({
-    kbid: r.kbid,
-    score: r.score,
-    preview: "",
-    matches: r.matches
-  }));
+  return {
+    items: results.items.map((r) => ({
+      kbid: r.kbid,
+      heading: r.heading,
+      type: r.type,
+      docids: r.docids,
+      score: r.score,
+      snippet: r.snippet,
+      matched_terms: r.matched_terms,
+      preview: ""
+    })),
+    total: results.total,
+    offset: results.offset,
+    limit: results.limit,
+    has_more: results.has_more
+  };
 }
 
 // src/shared/cli/functions/run-learn.function.ts
@@ -919,9 +955,9 @@ async function handleDbMigrate(client, options) {
     };
   }
 }
-async function hydrateSearchPreviews(client, results) {
+async function hydrateSearchPreviews(client, paged) {
   await Promise.all(
-    results.map(async (result) => {
+    paged.items.map(async (result) => {
       try {
         const contentResult = await client.content([result.kbid]);
         result.preview = contentResult.data;
@@ -932,7 +968,7 @@ async function hydrateSearchPreviews(client, results) {
 }
 
 // src/shared/version/constants/version.constant.ts
-var VERSION = "0.1.5";
+var VERSION = "0.2.0";
 
 // src/shared/cli/functions/generate-help.function.ts
 var KNOWN_COMMANDS = /* @__PURE__ */ new Set([
@@ -1641,11 +1677,22 @@ var WorkerClient = class {
    * Searches the knowledge base.
    *
    * @param params - query parameters including the search string
-   * @returns ranked list of matching sections
+   * @returns paginated search results with metadata
    */
   async search(params) {
     return this.call("search", params);
   }
+  /**
+   * Retrieves full content and context for one or more sections by
+   * their knowledge-base identifiers.
+   *
+   * @param params - section identifier(s) and optional expansion depth
+   * @returns a single `RecallResult` when `kbid` is provided without
+   *   `kbids`, or a `RecallResult[]` when `kbids` is provided
+   */
+  async recall(params) {
+    return this.call("recall", params);
+  }
   /**
    * Adds a new section to the knowledge base.
    *
@@ -2088,7 +2135,7 @@ function createToolDefinitions() {
   return [
     {
       name: "search",
-      description: "Search the knowledge base for relevant sections using natural language queries.",
+      description: "Search the knowledge base. Returns ranked results with headings and snippets for relevance evaluation. Use `recall` to get full content of specific results.",
       inputSchema: {
         type: "object",
         properties: {
@@ -2104,6 +2151,10 @@ function createToolDefinitions() {
           limit: {
             type: "number",
             description: "Maximum results (default: 20)"
+          },
+          offset: {
+            type: "number",
+            description: "Number of results to skip for pagination (default: 0)"
           }
         },
         required: ["query"]
@@ -2112,7 +2163,8 @@ function createToolDefinitions() {
         title: "Search KB",
         readOnlyHint: true,
         destructiveHint: false,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
@@ -2148,7 +2200,8 @@ function createToolDefinitions() {
         title: "Import Content",
         readOnlyHint: false,
         destructiveHint: false,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
@@ -2168,12 +2221,13 @@ function createToolDefinitions() {
         title: "Remove Section",
         readOnlyHint: false,
         destructiveHint: true,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
       name: "retrieve",
-      description: "Retrieve a section or document by ID. Provide kbid or docid.",
+      description: "Low-level fetch of a section or document by identifier. For AI agent workflows, prefer `recall` which includes metadata, context, and back-references.",
       inputSchema: {
         type: "object",
         properties: {
@@ -2191,7 +2245,37 @@ function createToolDefinitions() {
         title: "Fetch Content",
         readOnlyHint: true,
         destructiveHint: false,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    {
+      name: "recall",
+      description: "Retrieve full content and context for sections by identifier. Use after search to read relevant results. Returns section text, metadata, references, and back-references.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          kbid: {
+            type: "string",
+            description: "Single section identifier"
+          },
+          kbids: {
+            type: "array",
+            items: { type: "string" },
+            description: "Batch section identifiers"
+          },
+          depth: {
+            type: "number",
+            description: "Expansion depth (0-3, default: 0)"
+          }
+        }
+      },
+      annotations: {
+        title: "Recall Context",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
@@ -2205,7 +2289,8 @@ function createToolDefinitions() {
         title: "DB Status",
         readOnlyHint: true,
         destructiveHint: false,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
@@ -2226,7 +2311,8 @@ function createToolDefinitions() {
         title: "Compose Content",
         readOnlyHint: true,
         destructiveHint: false,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
@@ -2240,7 +2326,8 @@ function createToolDefinitions() {
         title: "Integrity Check",
         readOnlyHint: true,
         destructiveHint: false,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
@@ -2254,7 +2341,8 @@ function createToolDefinitions() {
         title: "Garbage Collect",
         readOnlyHint: false,
         destructiveHint: true,
-        idempotentHint: false
+        idempotentHint: false,
+        openWorldHint: false
       }
     },
     {
@@ -2268,7 +2356,8 @@ function createToolDefinitions() {
         title: "Rebuild Indexes",
         readOnlyHint: false,
         destructiveHint: false,
-        idempotentHint: false
+        idempotentHint: false,
+        openWorldHint: false
       }
     },
     {
@@ -2296,7 +2385,8 @@ function createToolDefinitions() {
         title: "Create Skill",
         readOnlyHint: false,
         destructiveHint: false,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
@@ -2310,7 +2400,8 @@ function createToolDefinitions() {
         title: "List Skills",
         readOnlyHint: true,
         destructiveHint: false,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
@@ -2333,7 +2424,8 @@ function createToolDefinitions() {
         title: "Get Skill",
         readOnlyHint: true,
         destructiveHint: false,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
@@ -2353,7 +2445,8 @@ function createToolDefinitions() {
         title: "Delete Skill",
         readOnlyHint: false,
         destructiveHint: true,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
@@ -2386,7 +2479,8 @@ function createToolDefinitions() {
         title: "Create Agent",
         readOnlyHint: false,
         destructiveHint: false,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
@@ -2400,7 +2494,8 @@ function createToolDefinitions() {
         title: "List Agents",
         readOnlyHint: true,
         destructiveHint: false,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
@@ -2420,7 +2515,8 @@ function createToolDefinitions() {
         title: "Get Agent",
         readOnlyHint: true,
         destructiveHint: false,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     },
     {
@@ -2440,7 +2536,8 @@ function createToolDefinitions() {
         title: "Delete Agent",
         readOnlyHint: false,
         destructiveHint: true,
-        idempotentHint: true
+        idempotentHint: true,
+        openWorldHint: false
       }
     }
   ];
@@ -2641,6 +2738,33 @@ async function handleAgentDelete(client, args) {
   };
 }
 
+// src/shared/mcp/functions/handle-recall.function.ts
+async function handleRecall(client, args) {
+  const kbid = typeof args["kbid"] === "string" ? args["kbid"] : void 0;
+  const kbids = Array.isArray(args["kbids"]) && args["kbids"].every((item) => typeof item === "string") ? args["kbids"] : void 0;
+  if (!kbid && !kbids) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "Provide kbid or kbids"
+        }
+      ],
+      isError: true
+    };
+  }
+  const depth = typeof args["depth"] === "number" ? args["depth"] : 0;
+  const result = await client.recall({ kbid, kbids, depth });
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(result, null, 2)
+      }
+    ]
+  };
+}
+
 // src/shared/mcp/functions/handle-tool-call.function.ts
 function asString2(value, fallback) {
   return typeof value === "string" ? value : fallback;
@@ -2662,6 +2786,8 @@ async function handleToolCall(client, name, args) {
         return await handleUnlearn2(client, args);
       case "retrieve":
         return await handleRetrieve(client, args);
+      case "recall":
+        return await handleRecall(client, args);
       case "status":
         return await handleStatus2(client);
       case "content":
@@ -2715,13 +2841,18 @@ async function handleSearch2(client, args) {
   const results = await client.search({
     query: asString2(args["query"], ""),
     mode: args["mode"],
-    limit: args["limit"]
+    limit: args["limit"],
+    offset: args["offset"]
   });
+  const stripped = {
+    ...results,
+    items: results.items.map(({ score: _score, ...rest }) => rest)
+  };
   return {
     content: [
       {
         type: "text",
-        text: JSON.stringify(results, null, 2)
+        text: JSON.stringify(stripped, null, 2)
       }
     ]
   };