@vpxa/kb 0.1.1

package/packages/server/dist/tools/list.tool.js

@@ -0,0 +1,56 @@
+import { z } from "zod";
+function registerListTool(server, curated) {
+  server.registerTool(
+    "list",
+    {
+      description: "List curated knowledge entries. Optionally filter by category or tag.",
+      inputSchema: {
+        category: z.string().optional().describe('Filter by category (e.g., "decisions", "patterns")'),
+        tag: z.string().optional().describe("Filter by tag")
+      }
+    },
+    async ({ category, tag }) => {
+      try {
+        const entries = await curated.list({ category, tag });
+        if (entries.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "No curated knowledge entries found." + (category ? ` (category: ${category})` : "") + (tag ? ` (tag: ${tag})` : "")
+              }
+            ]
+          };
+        }
+        const formatted = entries.map((e) => {
+          const tags = e.tags.length > 0 ? ` [${e.tags.join(", ")}]` : "";
+          return `- **${e.title}** (v${e.version})${tags}
+  \`${e.path}\` \u2014 ${e.contentPreview.slice(0, 80)}\u2026`;
+        }).join("\n");
+        return {
+          content: [
+            {
+              type: "text",
+              text: `## Curated Knowledge (${entries.length} entries)
+
+${formatted}
+
+---
+_Next: Use \`read\` to view full content of any entry, or \`remember\` to store new knowledge._`
+            }
+          ]
+        };
+      } catch (err) {
+        console.error("[KB] List failed:", err);
+        return {
+          content: [{ type: "text", text: `List failed: ${err.message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+export {
+  registerListTool
+};
+//# sourceMappingURL=list.tool.js.map

package/packages/server/dist/tools/lookup.tool.d.ts

@@ -0,0 +1,4 @@
+import type { IKnowledgeStore } from '@kb/store';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerLookupTool(server: McpServer, store: IKnowledgeStore): void;
+//# sourceMappingURL=lookup.tool.d.ts.map

package/packages/server/dist/tools/lookup.tool.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+function registerLookupTool(server, store) {
+  server.registerTool(
+    "lookup",
+    {
+      description: "Look up all indexed chunks for a specific file path. Returns all chunks sorted by position.",
+      inputSchema: {
+        path: z.string().describe('Relative file path to look up (e.g., "src/index.ts")')
+      }
+    },
+    async ({ path }) => {
+      try {
+        const records = await store.getBySourcePath(path);
+        if (records.length === 0) {
+          return {
+            content: [{ type: "text", text: `No indexed content found for: ${path}` }]
+          };
+        }
+        records.sort((a, b) => a.chunkIndex - b.chunkIndex);
+        const header = `## ${path}
+**Chunks**: ${records.length} | **Type**: ${records[0].contentType}
+`;
+        const chunks = records.map((r) => {
+          const lineInfo = r.startLine ? ` (lines ${r.startLine}-${r.endLine})` : "";
+          return `### Chunk ${r.chunkIndex + 1}/${r.totalChunks}${lineInfo}
+${r.content}`;
+        }).join("\n\n");
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${header}
+${chunks}
+
+---
+_Next: Use \`search\` to find related content, or \`analyze_dependencies\` to see what this file imports._`
+            }
+          ]
+        };
+      } catch (err) {
+        console.error("[KB] Lookup failed:", err);
+        return {
+          content: [{ type: "text", text: `Lookup failed: ${err.message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+export {
+  registerLookupTool
+};
+//# sourceMappingURL=lookup.tool.js.map

package/packages/server/dist/tools/onboard.tool.d.ts

@@ -0,0 +1,5 @@
+import type { IEmbedder } from '@kb/embeddings';
+import type { IKnowledgeStore } from '@kb/store';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerOnboardTool(server: McpServer, store: IKnowledgeStore, embedder: IEmbedder): void;
+//# sourceMappingURL=onboard.tool.d.ts.map

package/packages/server/dist/tools/onboard.tool.js

@@ -0,0 +1,112 @@
+import { createHash } from "node:crypto";
+import { onboard } from "@kb/tools";
+import { z } from "zod";
+async function persistOnboardResults(store, embedder, result) {
+  for (const step of result.steps) {
+    if (step.status !== "success" || !step.output) continue;
+    try {
+      const pathHash = createHash("sha256").update(result.path).digest("hex").slice(0, 12);
+      const sourcePath = `produced/onboard/${step.name}/${pathHash}.md`;
+      const contentHash = createHash("sha256").update(step.output).digest("hex").slice(0, 16);
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const sections = step.output.length > 2e3 ? step.output.split(/(?=^## )/m).filter((s) => s.trim().length > 0) : [step.output];
+      const records = sections.map((text, i) => ({
+        id: createHash("sha256").update(`${sourcePath}::${i}`).digest("hex").slice(0, 16),
+        content: text.trim(),
+        sourcePath,
+        contentType: "produced-knowledge",
+        chunkIndex: i,
+        totalChunks: sections.length,
+        startLine: 0,
+        endLine: 0,
+        fileHash: contentHash,
+        indexedAt: now,
+        origin: "produced",
+        tags: ["onboard", step.name],
+        category: "analysis",
+        version: 1
+      }));
+      const vectors = await embedder.embedBatch(records.map((r) => r.content));
+      await store.upsert(records, vectors);
+    } catch (err) {
+      console.error(`[KB] Auto-persist onboard/${step.name} failed:`, err);
+    }
+  }
+}
+function registerOnboardTool(server, store, embedder) {
+  server.registerTool(
+    "onboard",
+    {
+      description: "First-time codebase onboarding: runs all analysis tools (structure, dependencies, entry-points, symbols, patterns, diagram) in one command. Results are auto-persisted to KB. Use mode=generate to also write structured output to .ai/kb/ directory.",
+      inputSchema: {
+        path: z.string().describe("Root path of the codebase to onboard"),
+        mode: z.enum(["memory", "generate"]).default("memory").describe(
+          "Output mode: memory = KB vector store only; generate = also write to .ai/kb/ directory"
+        ),
+        out_dir: z.string().optional().describe("Custom output directory for generate mode (default: <path>/.ai/kb)")
+      }
+    },
+    async ({ path, mode, out_dir }) => {
+      try {
+        console.error(`[KB] Starting onboard for: ${path} (mode: ${mode})`);
+        const result = await onboard({
+          path,
+          mode,
+          outDir: out_dir
+        });
+        persistOnboardResults(store, embedder, result);
+        const lines = [
+          "## Onboard Complete",
+          "",
+          `**Path:** \`${result.path}\``,
+          `**Mode:** ${result.mode}`,
+          `**Duration:** ${result.totalDurationMs}ms`,
+          ""
+        ];
+        if (result.outDir) {
+          lines.push(`**Output directory:** \`${result.outDir}\``);
+          lines.push("");
+        }
+        lines.push("### Analysis Results", "");
+        const successSteps = [];
+        const failedSteps = [];
+        for (const step of result.steps) {
+          if (step.status === "success") {
+            successSteps.push(
+              `- \u2713 **${step.name}** (${step.durationMs}ms) \u2014 ${step.output.length} chars`
+            );
+          } else {
+            failedSteps.push(`- \u2717 **${step.name}** \u2014 ${step.error}`);
+          }
+        }
+        lines.push(...successSteps);
+        if (failedSteps.length > 0) {
+          lines.push("", "### Failed", "", ...failedSteps);
+        }
+        lines.push("", "---", "");
+        for (const step of result.steps) {
+          if (step.status !== "success") continue;
+          lines.push(`### ${step.name}`, "", step.output, "", "---", "");
+        }
+        lines.push(
+          "_All results auto-saved to KB.",
+          result.mode === "generate" ? ` Files written to \`${result.outDir}\`.` : "",
+          " Next: Use `search` to query the knowledge, or `remember` to add custom insights._"
+        );
+        return {
+          content: [{ type: "text", text: lines.join("\n") }]
+        };
+      } catch (err) {
+        console.error("[KB] Onboard failed:", err);
+        return {
+          content: [{ type: "text", text: `Onboard failed: ${err.message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+export {
+  registerOnboardTool
+};
+//# sourceMappingURL=onboard.tool.js.map

package/packages/server/dist/tools/produce.tool.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerProduceKnowledgeTool(server: McpServer): void;
+//# sourceMappingURL=produce.tool.d.ts.map

package/packages/server/dist/tools/produce.tool.js

@@ -0,0 +1,74 @@
+import {
+  DependencyAnalyzer,
+  DiagramGenerator,
+  EntryPointAnalyzer,
+  KnowledgeProducer,
+  PatternAnalyzer,
+  StructureAnalyzer,
+  SymbolAnalyzer
+} from "@kb/analyzers";
+import { z } from "zod";
+function registerProduceKnowledgeTool(server) {
+  const analyzers = {
+    structure: new StructureAnalyzer(),
+    dependencies: new DependencyAnalyzer(),
+    symbols: new SymbolAnalyzer(),
+    patterns: new PatternAnalyzer(),
+    entryPoints: new EntryPointAnalyzer(),
+    diagrams: new DiagramGenerator()
+  };
+  const producer = new KnowledgeProducer(analyzers);
+  server.registerTool(
+    "produce_knowledge",
+    {
+      description: "Run automated codebase analysis and produce synthesis instructions. Executes Tier 1 deterministic analyzers, then returns structured baselines and instructions for you to synthesize knowledge using remember.",
+      inputSchema: {
+        scope: z.string().optional().describe("Root path to analyze (defaults to workspace root)"),
+        aspects: z.array(
+          z.enum([
+            "all",
+            "structure",
+            "dependencies",
+            "symbols",
+            "patterns",
+            "entry-points",
+            "diagrams"
+          ])
+        ).default(["all"]).describe("Which analysis aspects to run")
+      }
+    },
+    async ({ scope, aspects }) => {
+      try {
+        const rootPath = scope ?? ".";
+        console.error(
+          `[KB] Running knowledge production for: ${rootPath}, aspects: ${aspects.join(", ")}`
+        );
+        const baselines = await producer.runExtraction(rootPath, aspects);
+        const instructions = producer.buildSynthesisInstructions(baselines, aspects);
+        return {
+          content: [
+            {
+              type: "text",
+              text: instructions + "\n\n---\n_Next: Review the baselines above and use `remember` to store synthesized knowledge entries._"
+            }
+          ]
+        };
+      } catch (err) {
+        console.error("[KB] Knowledge production failed:", err);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Knowledge production failed: ${err.message}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+export {
+  registerProduceKnowledgeTool
+};
+//# sourceMappingURL=produce.tool.js.map

package/packages/server/dist/tools/read.tool.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CuratedKnowledgeManager } from '../curated-manager.js';
+export declare function registerReadTool(server: McpServer, curated: CuratedKnowledgeManager): void;
+//# sourceMappingURL=read.tool.d.ts.map

package/packages/server/dist/tools/read.tool.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+function registerReadTool(server, curated) {
+  server.registerTool(
+    "read",
+    {
+      description: "Read the full content of a specific curated knowledge entry by its path. Use list first to discover available entries.",
+      inputSchema: {
+        path: z.string().describe('Relative path within curated/ (e.g., "decisions/use-lancedb.md")')
+      }
+    },
+    async ({ path }) => {
+      try {
+        const entry = await curated.read(path);
+        const meta = [
+          `## ${entry.title}`,
+          `- **Path**: curated/${path}`,
+          `- **Category**: ${entry.category}`,
+          entry.tags.length ? `- **Tags**: ${entry.tags.join(", ")}` : null,
+          `- **Version**: ${entry.version}`,
+          `- **Created**: ${entry.created}`,
+          entry.updated !== entry.created ? `- **Updated**: ${entry.updated}` : null,
+          ""
+        ].filter((l) => l !== null).join("\n");
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${meta}
+${entry.content}
+
+---
+_Next: Use \`update\` to modify this entry, or \`search\` to find related entries._`
+            }
+          ]
+        };
+      } catch (err) {
+        console.error("[KB] Read failed:", err);
+        return {
+          content: [{ type: "text", text: `Read failed: ${err.message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+export {
+  registerReadTool
+};
+//# sourceMappingURL=read.tool.js.map

package/packages/server/dist/tools/reindex.tool.d.ts

@@ -0,0 +1,7 @@
+import type { KBConfig } from '@kb/core';
+import type { IncrementalIndexer } from '@kb/indexer';
+import type { IKnowledgeStore } from '@kb/store';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CuratedKnowledgeManager } from '../curated-manager.js';
+export declare function registerReindexTool(server: McpServer, indexer: IncrementalIndexer, config: KBConfig, curated: CuratedKnowledgeManager, store?: IKnowledgeStore): void;
+//# sourceMappingURL=reindex.tool.d.ts.map

package/packages/server/dist/tools/reindex.tool.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+function registerReindexTool(server, indexer, config, curated, store) {
+  server.registerTool(
+    "reindex",
+    {
+      description: "Trigger re-indexing of the knowledge base. Can do incremental (only changed files) or full re-index.",
+      inputSchema: {
+        full: z.boolean().default(false).describe("If true, force full re-index ignoring file hashes")
+      }
+    },
+    async ({ full }) => {
+      try {
+        console.error(`[KB] Starting ${full ? "full" : "incremental"} re-index...`);
+        const logProgress = (prefix) => (p) => {
+          if (p.phase === "chunking" && p.currentFile) {
+            console.error(
+              `[KB] ${prefix} [${p.filesProcessed + 1}/${p.filesTotal}] ${p.currentFile}`
+            );
+          }
+        };
+        const result = full ? await indexer.reindexAll(config, logProgress("Reindex")) : await indexer.index(config, logProgress("Index"));
+        const text = [
+          "## Re-index Complete",
+          "",
+          `- **Files Processed**: ${result.filesProcessed}`,
+          `- **Files Skipped** (unchanged): ${result.filesSkipped}`,
+          `- **Chunks Created**: ${result.chunksCreated}`,
+          `- **Files Removed**: ${result.filesRemoved}`,
+          `- **Duration**: ${(result.durationMs / 1e3).toFixed(1)}s`
+        ];
+        if (store) {
+          try {
+            await store.createFtsIndex();
+          } catch (ftsErr) {
+            text.push("", `- **FTS Index Failed**: ${ftsErr.message}`);
+          }
+        }
+        try {
+          const curatedResult = await curated.reindexAll();
+          text.push("", `- **Curated Entries Re-indexed**: ${curatedResult.indexed}`);
+          if (curatedResult.errors.length > 0) {
+            text.push(`- **Curated Errors**: ${curatedResult.errors.length}`);
+          }
+          console.error(`[KB] Curated re-index: ${curatedResult.indexed} entries`);
+        } catch (curatedErr) {
+          text.push("", `- **Curated Re-index Failed**: ${curatedErr.message}`);
+          console.error("[KB] Curated re-index failed:", curatedErr);
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: text.join("\n") + "\n\n---\n_Next: Use `search` to query the refreshed index, or `status` to verify index stats._"
+            }
+          ]
+        };
+      } catch (err) {
+        console.error("[KB] Reindex failed:", err);
+        return {
+          content: [{ type: "text", text: `Reindex failed: ${err.message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+export {
+  registerReindexTool
+};
+//# sourceMappingURL=reindex.tool.js.map

package/packages/server/dist/tools/remember.tool.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CuratedKnowledgeManager } from '../curated-manager.js';
+export declare function registerRememberTool(server: McpServer, curated: CuratedKnowledgeManager): void;
+//# sourceMappingURL=remember.tool.d.ts.map

package/packages/server/dist/tools/remember.tool.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+function registerRememberTool(server, curated) {
+  server.registerTool(
+    "remember",
+    {
+      description: "Store a new piece of curated knowledge. Use this to persist decisions, patterns, conventions, or any insight worth remembering across sessions.",
+      inputSchema: {
+        title: z.string().min(3).max(120).describe("Short descriptive title for the knowledge entry"),
+        content: z.string().min(10).describe("The markdown content to store"),
+        category: z.string().regex(/^[a-z][a-z0-9-]*$/).describe(
+          'Category slug (e.g., "decisions", "patterns", "conventions", "api-contracts")'
+        ),
+        tags: z.array(z.string()).default([]).describe("Optional tags for filtering")
+      }
+    },
+    async ({ title, content, category, tags }) => {
+      try {
+        const result = await curated.remember(title, content, category, tags);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Remembered: **${title}**
+
+Stored at \`curated/${result.path}\` and indexed for semantic search.
+
+---
+_Next: Use \`search\` to verify the entry is findable, or \`list\` to see all curated entries._`
+            }
+          ]
+        };
+      } catch (err) {
+        console.error("[KB] Remember failed:", err);
+        return {
+          content: [{ type: "text", text: `Remember failed: ${err.message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+export {
+  registerRememberTool
+};
+//# sourceMappingURL=remember.tool.js.map

package/packages/server/dist/tools/replay.tool.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerReplayTool(server: McpServer): void;
+//# sourceMappingURL=replay.tool.d.ts.map

package/packages/server/dist/tools/replay.tool.js

@@ -0,0 +1,89 @@
+import { replayClear, replayList, replayTrim } from "@kb/tools";
+import { z } from "zod";
+function registerReplayTool(server) {
+  server.registerTool(
+    "replay_list",
+    {
+      description: "View the audit trail of recent MCP tool and CLI invocations. Shows tool name, duration, status, and input/output summaries. Useful for debugging agent behavior and understanding what happened.",
+      inputSchema: {
+        last: z.number().optional().describe("Number of entries to return (default: 20)"),
+        tool: z.string().optional().describe('Filter by tool name (e.g., "search")'),
+        source: z.enum(["mcp", "cli"]).optional().describe('Filter by source: "mcp" or "cli"'),
+        since: z.string().optional().describe("ISO timestamp \u2014 only show entries after this time")
+      }
+    },
+    async ({ last, tool, source, since }) => {
+      try {
+        const entries = replayList({ last, tool, source, since });
+        if (entries.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "No replay entries found. Activity is logged when tools are invoked via MCP or CLI."
+              }
+            ]
+          };
+        }
+        const lines = entries.map((e) => {
+          const time = e.ts.split("T")[1]?.split(".")[0] ?? e.ts;
+          const status = e.status === "ok" ? "\u2713" : "\u2717";
+          return `${time} ${status} ${e.tool} (${e.durationMs}ms) [${e.source}]
+  in: ${e.input}
+  out: ${e.output}`;
+        });
+        replayTrim();
+        return {
+          content: [
+            {
+              type: "text",
+              text: `**Replay Log** (${entries.length} entries)
+
+${lines.join("\n\n")}`
+            }
+          ]
+        };
+      } catch (err) {
+        console.error("[KB] Replay list failed:", err);
+        return {
+          content: [
+            { type: "text", text: `Replay list failed: ${err.message}` }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server.registerTool(
+    "replay_clear",
+    {
+      description: "Clear the entire replay audit trail.",
+      inputSchema: {}
+    },
+    async () => {
+      try {
+        replayClear();
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Replay log cleared."
+            }
+          ]
+        };
+      } catch (err) {
+        console.error("[KB] Replay clear failed:", err);
+        return {
+          content: [
+            { type: "text", text: `Replay clear failed: ${err.message}` }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+export {
+  registerReplayTool
+};
+//# sourceMappingURL=replay.tool.js.map

package/packages/server/dist/tools/search.tool.d.ts

@@ -0,0 +1,5 @@
+import type { IEmbedder } from '@kb/embeddings';
+import type { IGraphStore, IKnowledgeStore } from '@kb/store';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerSearchTool(server: McpServer, embedder: IEmbedder, store: IKnowledgeStore, graphStore?: IGraphStore): void;
+//# sourceMappingURL=search.tool.d.ts.map