@vpxa/kb 0.1.1

package/packages/server/dist/config.js

@@ -0,0 +1,75 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function guardContainedPath(resolved, root, label) {
+  const normalizedResolved = resolve(resolved);
+  const normalizedRoot = resolve(root);
+  if (!normalizedResolved.startsWith(normalizedRoot)) {
+    throw new Error(
+      `Config ${label} path escapes workspace root: ${resolved} is not under ${root}`
+    );
+  }
+  return normalizedResolved;
+}
+function loadConfig() {
+  const configPath = process.env.KB_CONFIG_PATH ?? (existsSync(resolve(process.cwd(), "kb.config.json")) ? resolve(process.cwd(), "kb.config.json") : resolve(__dirname, "..", "..", "..", "kb.config.json"));
+  try {
+    const raw = readFileSync(configPath, "utf-8");
+    const config = JSON.parse(raw);
+    if (!config.sources || !Array.isArray(config.sources) || config.sources.length === 0) {
+      throw new Error("Config must have at least one source");
+    }
+    if (!config.store?.path) {
+      throw new Error("Config must specify store.path");
+    }
+    const workspaceRoot = dirname(configPath);
+    config.sources = config.sources.map((source) => ({
+      ...source,
+      path: guardContainedPath(resolve(workspaceRoot, source.path), workspaceRoot, "source")
+    }));
+    config.store.path = guardContainedPath(
+      resolve(workspaceRoot, config.store.path),
+      workspaceRoot,
+      "store"
+    );
+    config.curated = config.curated ?? { path: "curated" };
+    config.curated.path = guardContainedPath(
+      resolve(workspaceRoot, config.curated.path),
+      workspaceRoot,
+      "curated"
+    );
+    return config;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`[KB] Failed to load config from ${configPath}: ${message}`);
+    console.error("[KB] Falling back to default configuration");
+    return getDefaultConfig();
+  }
+}
+function getDefaultConfig() {
+  const workspaceRoot = process.env.KB_WORKSPACE_ROOT ?? process.cwd();
+  return {
+    sources: [
+      {
+        path: workspaceRoot,
+        excludePatterns: [
+          "node_modules/**",
+          "dist/**",
+          ".git/**",
+          "coverage/**",
+          "*.lock",
+          "pnpm-lock.yaml"
+        ]
+      }
+    ],
+    indexing: { chunkSize: 1500, chunkOverlap: 200, minChunkSize: 100 },
+    embedding: { model: "mixedbread-ai/mxbai-embed-large-v1", dimensions: 1024 },
+    store: { backend: "lancedb", path: resolve(workspaceRoot, ".kb-data") },
+    curated: { path: resolve(workspaceRoot, "curated") }
+  };
+}
+export {
+  loadConfig
+};
+//# sourceMappingURL=config.js.map

package/packages/server/dist/curated-manager.d.ts

@@ -0,0 +1,86 @@
+import type { IEmbedder } from '@kb/embeddings';
+import type { IKnowledgeStore } from '@kb/store';
+export type CuratedCategory = string;
+export interface CuratedEntry {
+    path: string;
+    title: string;
+    category: string;
+    tags: string[];
+    version: number;
+    created: string;
+    updated: string;
+    contentPreview: string;
+}
+interface CuratedFrontmatter {
+    title: string;
+    category: string;
+    tags: string[];
+    created: string;
+    updated: string;
+    version: number;
+    origin: 'curated';
+    changelog: Array<{
+        version: number;
+        date: string;
+        reason: string;
+    }>;
+}
+/**
+ * Manages curated knowledge files — the LLM's persistent memory.
+ * Files are stored as markdown in a curated/ directory with YAML frontmatter.
+ */
+export declare class CuratedKnowledgeManager {
+    private readonly curatedDir;
+    private readonly store;
+    private readonly embedder;
+    constructor(curatedDir: string, store: IKnowledgeStore, embedder: IEmbedder);
+    remember(title: string, content: string, category: CuratedCategory, tags?: string[]): Promise<{
+        path: string;
+    }>;
+    update(relativePath: string, newContent: string, reason: string): Promise<{
+        path: string;
+        version: number;
+    }>;
+    forget(relativePath: string, _reason: string): Promise<{
+        path: string;
+    }>;
+    read(relativePath: string): Promise<CuratedEntry & {
+        content: string;
+    }>;
+    list(filters?: {
+        category?: CuratedCategory;
+        tag?: string;
+    }): Promise<CuratedEntry[]>;
+    /**
+     * Re-index all curated files into the vector store.
+     * Call this after the indexer has run to restore curated vectors
+     * that may have been lost, or to bulk-sync disk state to vectors.
+     */
+    reindexAll(): Promise<{
+        indexed: number;
+        errors: string[];
+    }>;
+    private indexCuratedFile;
+    private discoverCategories;
+    private guardPath;
+    private validateCategoryName;
+    private validateContentSize;
+    private slugify;
+    /** Return a unique `category/slug.md` path, appending `-2`, `-3`, … on collision. */
+    private uniqueRelativePath;
+    private hash;
+    private hashId;
+    /**
+     * Simple YAML frontmatter serializer (no gray-matter dependency).
+     */
+    private serializeFile;
+    /**
+     * Simple YAML frontmatter parser (no gray-matter dependency).
+     */
+    parseFile(raw: string): {
+        frontmatter: CuratedFrontmatter;
+        content: string;
+    };
+}
+export {};
+//# sourceMappingURL=curated-manager.d.ts.map

package/packages/server/dist/curated-manager.js

@@ -0,0 +1,357 @@
+import { createHash } from "node:crypto";
+import { mkdir, readdir, readFile, stat, unlink, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join } from "node:path";
+const MAX_CONTENT_SIZE = 50 * 1024;
+class CuratedKnowledgeManager {
+  constructor(curatedDir, store, embedder) {
+    this.curatedDir = curatedDir;
+    this.store = store;
+    this.embedder = embedder;
+  }
+  async remember(title, content, category, tags = []) {
+    this.validateCategoryName(category);
+    this.validateContentSize(content);
+    const slug = this.slugify(title);
+    const relativePath = await this.uniqueRelativePath(category, slug);
+    const filePath = join(this.curatedDir, relativePath);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const frontmatter = {
+      title,
+      category,
+      tags,
+      created: now,
+      updated: now,
+      version: 1,
+      origin: "curated",
+      changelog: [{ version: 1, date: now, reason: "Initial creation" }]
+    };
+    const fileContent = this.serializeFile(content, frontmatter);
+    await mkdir(dirname(filePath), { recursive: true });
+    await writeFile(filePath, fileContent, "utf-8");
+    await this.indexCuratedFile(relativePath, content, frontmatter);
+    return { path: relativePath };
+  }
+  async update(relativePath, newContent, reason) {
+    this.guardPath(relativePath);
+    this.validateContentSize(newContent);
+    const filePath = join(this.curatedDir, relativePath);
+    const raw = await readFile(filePath, "utf-8");
+    const { frontmatter } = this.parseFile(raw);
+    const newVersion = (frontmatter.version ?? 1) + 1;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    frontmatter.version = newVersion;
+    frontmatter.updated = now;
+    frontmatter.changelog = [
+      ...frontmatter.changelog ?? [],
+      { version: newVersion, date: now, reason }
+    ];
+    const fileContent = this.serializeFile(newContent, frontmatter);
+    await writeFile(filePath, fileContent, "utf-8");
+    await this.indexCuratedFile(relativePath, newContent, frontmatter);
+    return { path: relativePath, version: newVersion };
+  }
+  async forget(relativePath, _reason) {
+    this.guardPath(relativePath);
+    const filePath = join(this.curatedDir, relativePath);
+    const storePath = `curated/${relativePath}`;
+    await this.store.deleteBySourcePath(storePath);
+    await unlink(filePath);
+    return { path: relativePath };
+  }
+  async read(relativePath) {
+    this.guardPath(relativePath);
+    const filePath = join(this.curatedDir, relativePath);
+    const raw = await readFile(filePath, "utf-8");
+    const { frontmatter, content } = this.parseFile(raw);
+    const category = relativePath.split("/")[0];
+    return {
+      path: relativePath,
+      title: frontmatter.title ?? relativePath,
+      category,
+      tags: frontmatter.tags ?? [],
+      version: frontmatter.version ?? 1,
+      created: frontmatter.created ?? "",
+      updated: frontmatter.updated ?? "",
+      contentPreview: content.slice(0, 200),
+      content
+    };
+  }
+  async list(filters) {
+    const entries = [];
+    const categories = filters?.category ? [filters.category] : await this.discoverCategories();
+    for (const cat of categories) {
+      const catDir = join(this.curatedDir, cat);
+      try {
+        const files = await readdir(catDir);
+        for (const file of files) {
+          if (!file.endsWith(".md")) continue;
+          const filePath = join(catDir, file);
+          const raw = await readFile(filePath, "utf-8");
+          const { frontmatter, content } = this.parseFile(raw);
+          if (filters?.tag && !(frontmatter.tags ?? []).includes(filters.tag)) continue;
+          entries.push({
+            path: `${cat}/${file}`,
+            title: frontmatter.title ?? file,
+            category: cat,
+            tags: frontmatter.tags ?? [],
+            version: frontmatter.version ?? 1,
+            created: frontmatter.created ?? "",
+            updated: frontmatter.updated ?? "",
+            contentPreview: content.slice(0, 200)
+          });
+        }
+      } catch {
+      }
+    }
+    return entries;
+  }
+  /**
+   * Re-index all curated files into the vector store.
+   * Call this after the indexer has run to restore curated vectors
+   * that may have been lost, or to bulk-sync disk state to vectors.
+   */
+  async reindexAll() {
+    const categories = await this.discoverCategories();
+    const errors = [];
+    const pending = [];
+    for (const cat of categories) {
+      const catDir = join(this.curatedDir, cat);
+      let files;
+      try {
+        files = (await readdir(catDir)).filter((f) => f.endsWith(".md"));
+      } catch {
+        continue;
+      }
+      for (const file of files) {
+        const relativePath = `${cat}/${file}`;
+        const filePath = join(catDir, file);
+        try {
+          const raw = await readFile(filePath, "utf-8");
+          const { frontmatter, content } = this.parseFile(raw);
+          pending.push({ relativePath, content, frontmatter });
+        } catch (err) {
+          errors.push(`${relativePath}: ${err.message}`);
+        }
+      }
+    }
+    if (pending.length === 0) return { indexed: 0, errors };
+    const vectors = await this.embedder.embedBatch(pending.map((p) => p.content));
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const records = pending.map((p) => {
+      const storePath = `curated/${p.relativePath}`;
+      return {
+        id: this.hashId(storePath, 0),
+        content: p.content,
+        sourcePath: storePath,
+        contentType: "curated-knowledge",
+        headingPath: p.frontmatter.title,
+        chunkIndex: 0,
+        totalChunks: 1,
+        startLine: 1,
+        endLine: p.content.split("\n").length,
+        fileHash: this.hash(p.content),
+        indexedAt: now,
+        origin: "curated",
+        tags: p.frontmatter.tags,
+        category: p.frontmatter.category,
+        version: p.frontmatter.version
+      };
+    });
+    await this.store.upsert(records, vectors);
+    return { indexed: pending.length, errors };
+  }
+  // --- Private helpers ---
+  async indexCuratedFile(relativePath, content, frontmatter) {
+    const vector = await this.embedder.embed(content);
+    const storePath = `curated/${relativePath}`;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const record = {
+      id: this.hashId(storePath, 0),
+      content,
+      sourcePath: storePath,
+      contentType: "curated-knowledge",
+      headingPath: frontmatter.title,
+      chunkIndex: 0,
+      totalChunks: 1,
+      startLine: 1,
+      endLine: content.split("\n").length,
+      fileHash: this.hash(content),
+      indexedAt: now,
+      origin: "curated",
+      tags: frontmatter.tags,
+      category: frontmatter.category,
+      version: frontmatter.version
+    };
+    await this.store.upsert([record], [vector]);
+  }
+  async discoverCategories() {
+    try {
+      const entries = await readdir(this.curatedDir, { withFileTypes: true });
+      return entries.filter((e) => e.isDirectory() && /^[a-z][a-z0-9-]*$/.test(e.name)).map((e) => e.name);
+    } catch {
+      return [];
+    }
+  }
+  guardPath(relativePath) {
+    if (relativePath.includes("..") || isAbsolute(relativePath)) {
+      throw new Error(`Invalid path: ${relativePath}. Must be relative within curated/ directory.`);
+    }
+    const category = relativePath.split("/")[0];
+    this.validateCategoryName(category);
+  }
+  validateCategoryName(category) {
+    if (!/^[a-z][a-z0-9-]*$/.test(category)) {
+      throw new Error(
+        `Invalid category name: "${category}". Must be lowercase kebab-case (e.g., "decisions", "api-contracts").`
+      );
+    }
+  }
+  validateContentSize(content) {
+    if (Buffer.byteLength(content, "utf-8") > MAX_CONTENT_SIZE) {
+      throw new Error(`Content exceeds maximum size of ${MAX_CONTENT_SIZE / 1024}KB`);
+    }
+  }
+  slugify(title) {
+    return title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 80);
+  }
+  /** Return a unique `category/slug.md` path, appending `-2`, `-3`, … on collision. */
+  async uniqueRelativePath(category, slug) {
+    const base = `${category}/${slug}.md`;
+    const basePath = join(this.curatedDir, base);
+    try {
+      await stat(basePath);
+    } catch {
+      return base;
+    }
+    for (let i = 2; i <= 100; i++) {
+      const candidate = `${category}/${slug}-${i}.md`;
+      try {
+        await stat(join(this.curatedDir, candidate));
+      } catch {
+        return candidate;
+      }
+    }
+    throw new Error(`Too many entries with slug "${slug}" in category "${category}"`);
+  }
+  hash(content) {
+    return createHash("sha256").update(content).digest("hex").slice(0, 16);
+  }
+  hashId(sourcePath, chunkIndex) {
+    return this.hash(`${sourcePath}::${chunkIndex}`);
+  }
+  /**
+   * Simple YAML frontmatter serializer (no gray-matter dependency).
+   */
+  serializeFile(content, frontmatter) {
+    const yaml = [
+      "---",
+      `title: "${frontmatter.title.replace(/"/g, '\\"')}"`,
+      `category: ${frontmatter.category}`,
+      `tags: [${frontmatter.tags.map((t) => `"${t}"`).join(", ")}]`,
+      `created: ${frontmatter.created}`,
+      `updated: ${frontmatter.updated}`,
+      `version: ${frontmatter.version}`,
+      `origin: ${frontmatter.origin}`,
+      "changelog:",
+      ...frontmatter.changelog.map(
+        (c) => `  - version: ${c.version}
+    date: ${c.date}
+    reason: "${c.reason.replace(/"/g, '\\"')}"`
+      ),
+      "---"
+    ].join("\n");
+    return `${yaml}
+
+${content}
+`;
+  }
+  /**
+   * Simple YAML frontmatter parser (no gray-matter dependency).
+   */
+  parseFile(raw) {
+    const fmMatch = raw.match(/^---\n([\s\S]*?)\n---\n\n?([\s\S]*)$/);
+    if (!fmMatch) {
+      return {
+        frontmatter: {
+          title: "Untitled",
+          category: "notes",
+          tags: [],
+          created: "",
+          updated: "",
+          version: 1,
+          origin: "curated",
+          changelog: []
+        },
+        content: raw
+      };
+    }
+    const yamlStr = fmMatch[1];
+    const content = fmMatch[2].trim();
+    const fm = {};
+    const changelog = [];
+    const lines = yamlStr.split("\n");
+    let inChangelog = false;
+    let currentEntry = {};
+    for (const line of lines) {
+      if (/^changelog:\s*$/.test(line)) {
+        inChangelog = true;
+        continue;
+      }
+      if (inChangelog) {
+        const itemMatch = line.match(/^\s+-\s+version:\s*(\d+)$/);
+        if (itemMatch) {
+          if (currentEntry.version != null) changelog.push(currentEntry);
+          currentEntry = { version: parseInt(itemMatch[1], 10) };
+          continue;
+        }
+        const dateMatch = line.match(/^\s+date:\s*(.+)$/);
+        if (dateMatch) {
+          currentEntry.date = dateMatch[1].trim();
+          continue;
+        }
+        const reasonMatch = line.match(/^\s+reason:\s*"?(.*?)"?\s*$/);
+        if (reasonMatch) {
+          currentEntry.reason = reasonMatch[1];
+          continue;
+        }
+        if (/^\w/.test(line)) {
+          inChangelog = false;
+          if (currentEntry.version != null) changelog.push(currentEntry);
+          currentEntry = {};
+        }
+        continue;
+      }
+      const kvMatch = line.match(/^(\w+):\s*(.*)$/);
+      if (kvMatch) {
+        const key = kvMatch[1];
+        let value = kvMatch[2];
+        if (typeof value === "string" && value.startsWith("[") && value.endsWith("]")) {
+          value = value.slice(1, -1).split(",").map((s) => s.trim().replace(/^"|"$/g, "")).filter((s) => s.length > 0);
+        } else if (typeof value === "string" && /^\d+$/.test(value)) {
+          value = parseInt(value, 10);
+        } else if (typeof value === "string" && value.startsWith('"') && value.endsWith('"')) {
+          value = value.slice(1, -1);
+        }
+        fm[key] = value;
+      }
+    }
+    if (currentEntry.version != null) changelog.push(currentEntry);
+    return {
+      frontmatter: {
+        title: fm.title ?? "Untitled",
+        category: fm.category ?? "notes",
+        tags: fm.tags ?? [],
+        created: fm.created ?? "",
+        updated: fm.updated ?? "",
+        version: fm.version ?? 1,
+        origin: "curated",
+        changelog
+      },
+      content
+    };
+  }
+}
+export {
+  CuratedKnowledgeManager
+};
+//# sourceMappingURL=curated-manager.js.map

package/packages/server/dist/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/packages/server/dist/index.js

@@ -0,0 +1,134 @@
+import { parseArgs } from "node:util";
+import { loadConfig } from "./config.js";
+import { createMcpServer, createServer, initializeKnowledgeBase } from "./server.js";
+const { values } = parseArgs({
+  options: {
+    transport: { type: "string", default: process.env.KB_TRANSPORT ?? "stdio" },
+    port: { type: "string", default: process.env.KB_PORT ?? "3210" }
+  }
+});
+async function main() {
+  console.error("[KB] Starting MCP Knowledge Base server...");
+  const config = loadConfig();
+  console.error(
+    `[KB] Config loaded: ${config.sources.length} source(s), store at ${config.store.path}`
+  );
+  if (values.transport === "http") {
+    const { StreamableHTTPServerTransport } = await import("@modelcontextprotocol/sdk/server/streamableHttp.js");
+    const express = (await import("express")).default;
+    const kb = await initializeKnowledgeBase(config);
+    const mcpServer = createMcpServer(kb, config);
+    console.error("[KB] MCP server configured with 46 tools and 2 resources");
+    const app = express();
+    app.use(express.json());
+    app.use((_req, res, next) => {
+      res.setHeader("Access-Control-Allow-Origin", process.env.KB_CORS_ORIGIN ?? "*");
+      res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+      res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+      if (_req.method === "OPTIONS") {
+        res.status(204).end();
+        return;
+      }
+      next();
+    });
+    app.get("/health", (_req, res) => {
+      res.json({ status: "ok" });
+    });
+    app.post("/mcp", async (req, res) => {
+      try {
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: void 0 });
+        await mcpServer.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+        res.on("close", () => {
+          transport.close();
+        });
+      } catch (err) {
+        console.error("[KB] MCP handler error:", err);
+        if (!res.headersSent) {
+          res.status(500).json({
+            jsonrpc: "2.0",
+            error: { code: -32603, message: "Internal server error" },
+            id: null
+          });
+        }
+      }
+    });
+    app.get("/mcp", (_req, res) => {
+      res.writeHead(405).end(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          error: { code: -32e3, message: "Method not allowed." },
+          id: null
+        })
+      );
+    });
+    app.delete("/mcp", (_req, res) => {
+      res.writeHead(405).end(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          error: { code: -32e3, message: "Method not allowed." },
+          id: null
+        })
+      );
+    });
+    const port = Number(values.port);
+    const httpServer = app.listen(port, () => {
+      console.error(`[KB] MCP server listening on http://0.0.0.0:${port}/mcp`);
+      const runInitialIndex = async () => {
+        try {
+          const sourcePaths = config.sources.map((s) => s.path).join(", ");
+          console.error(`[KB] Running initial index for sources: ${sourcePaths}`);
+          const result = await kb.indexer.index(config, (p) => {
+            if (p.phase === "crawling" || p.phase === "done") return;
+            if (p.phase === "chunking" && p.currentFile) {
+              console.error(`[KB]   [${p.filesProcessed + 1}/${p.filesTotal}] ${p.currentFile}`);
+            }
+          });
+          console.error(
+            `[KB] Indexed ${result.filesProcessed} files (${result.filesSkipped} skipped, ${result.chunksCreated} chunks) in ${(result.durationMs / 1e3).toFixed(1)}s`
+          );
+          try {
+            const curatedResult = await kb.curated.reindexAll();
+            console.error(
+              `[KB] Curated re-index: ${curatedResult.indexed} entries restored to vector store`
+            );
+          } catch (curatedErr) {
+            console.error("[KB] Curated re-index failed:", curatedErr);
+          }
+        } catch (err) {
+          console.error("[KB] Initial index failed (will retry on kb_reindex):", err);
+        }
+      };
+      runInitialIndex();
+    });
+    const shutdown = async (signal) => {
+      console.error(`[KB] ${signal} received \u2014 shutting down...`);
+      httpServer.close();
+      await mcpServer.close();
+      await kb.store.close();
+      await kb.embedder.shutdown();
+      process.exit(0);
+    };
+    process.on("SIGINT", () => shutdown("SIGINT"));
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+  } else {
+    const { server, runInitialIndex } = await createServer(config);
+    const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("[KB] MCP server started (stdio)");
+    const autoIndex = process.env.KB_AUTO_INDEX !== "false";
+    if (autoIndex) {
+      runInitialIndex();
+    } else {
+      console.error(
+        "[KB] Auto-index disabled (KB_AUTO_INDEX=false). Use kb_reindex to index manually."
+      );
+    }
+  }
+}
+main().catch((err) => {
+  console.error("[KB] Fatal error:", err);
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/packages/server/dist/replay-interceptor.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Replay interceptor — wraps McpServer.registerTool to capture all tool invocations
+ * to the audit trail. Applied once in createMcpServer.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Wrap the McpServer's registerTool method so that every tool invocation
+ * is logged to the replay JSONL audit trail.
+ */
+export declare function installReplayInterceptor(server: McpServer): void;
+//# sourceMappingURL=replay-interceptor.d.ts.map