knowledge-mcp-server 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 1.0.0
+
+Initial release. Extracted from guitar-app project.
+
+- MCP server with 8 tools: search, lookup, graph, list, write, delete, validate, stats
+- BM25 full-text search with optional Voyage AI vector embeddings (hybrid RRF fusion)
+- CLI with subcommands: serve, embeddings, init, validate
+- Zero-config mode (works without knowledge.config.yaml)
+- Programmatic API via `createKnowledgeServer()`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ross Sheridan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,205 @@
+# knowledge-mcp-server
+
+MCP server for semantic search, CRUD, and graph operations over hierarchical knowledge bases stored as Markdown with YAML frontmatter.
+
+Provides 8 tools via [Model Context Protocol](https://modelcontextprotocol.io/): `knowledge_search`, `knowledge_lookup`, `knowledge_graph`, `knowledge_list`, `knowledge_write`, `knowledge_delete`, `knowledge_validate`, and `knowledge_stats`.
+
+## Quick Start
+
+```bash
+# Initialize a new knowledge directory
+npx knowledge-mcp-server init
+
+# Start the MCP server
+npx knowledge-mcp-server
+```
+
+## Installation
+
+```bash
+npm install knowledge-mcp-server
+```
+
+## Claude Code Integration
+
+Add to your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "knowledge": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["knowledge-mcp-server", "--knowledge-dir", "./knowledge"],
+      "env": {
+        "VOYAGE_API_KEY": "${VOYAGE_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+The `VOYAGE_API_KEY` is optional — without it, the server uses BM25 full-text search only. With it, search results are improved via hybrid BM25 + vector scoring with Reciprocal Rank Fusion.
+
+## CLI Reference
+
+```
+knowledge-mcp-server [command] [options]
+
+Commands:
+  serve       Start the MCP server over stdio (default)
+  embeddings  Generate embeddings for all documents via Voyage AI
+  init        Scaffold a new knowledge/ directory with config template
+  validate    Run graph integrity checks and report issues
+
+Options:
+  --knowledge-dir <path>  Path to knowledge directory (default: ./knowledge)
+  --help, -h              Show help
+  --version               Show version
+```
+
+### Generate Embeddings
+
+```bash
+VOYAGE_API_KEY=your-key npx knowledge-mcp-server embeddings
+```
+
+Uses incremental hashing — only re-embeds documents whose content has changed.
+
+### Validate Graph
+
+```bash
+npx knowledge-mcp-server validate
+```
+
+Checks for: orphaned documents, broken references, circular parents, missing tags, empty summaries, stale documents (>6 months), and embedding coverage. Exits with code 1 if integrity issues are found.
+
+## Programmatic API
+
+```typescript
+import { createKnowledgeServer } from "knowledge-mcp-server";
+
+const { server, graph, tfidfIndex, config } = createKnowledgeServer("./knowledge");
+```
+
+### Exported Types
+
+```typescript
+import type {
+  KnowledgeServerResult,
+  KnowledgeGraph,
+  KnowledgeDocument,
+  KnowledgeConfig,
+} from "knowledge-mcp-server";
+```
+
+## Document Format
+
+Knowledge documents are Markdown files with YAML frontmatter:
+
+```markdown
+---
+id: technology/audio-detection/pitch-detection
+title: Pitch Detection Pipeline
+type: detail
+domain: technology
+subdomain: audio-detection
+tags: [audio, ml, crepe, yin]
+phase: [1]
+related: [technology/audio-detection/chord-recognition]
+---
+
+Your document content here in Markdown.
+```
+
+### Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `id` | yes | Unique document ID (lowercase, hyphens, slashes) |
+| `title` | yes | Human-readable title |
+| `type` | yes | `summary`, `detail`, `decision`, or `reference` |
+| `domain` | yes | Top-level domain |
+| `subdomain` | no | Subdomain within the domain |
+| `tags` | yes | Array of searchable tags |
+| `phase` | yes | Array of applicable phase numbers |
+| `related` | no | Array of related document IDs |
+| `status` | no | `active` (default), `draft`, or `deprecated` |
+
+### Directory Structure
+
+```
+knowledge/
+├── knowledge.config.yaml    # Configuration (optional)
+├── _summary.md              # Root node
+├── .embeddings.json         # Generated embeddings (optional)
+├── .embeddings-hashes.json  # Content hashes for change detection
+├── .tags.json               # Tag taxonomy (optional)
+├── technology/
+│   ├── _summary.md
+│   └── audio-detection/
+│       ├── _summary.md
+│       └── pitch-detection.md
+└── business/
+    ├── _summary.md
+    └── pricing-tiers.md
+```
+
+## Configuration
+
+`knowledge.config.yaml` is optional. Without it, the server runs in zero-config mode (permissive validation, auto-discovered domains).
+
+```yaml
+name: "my-project"
+
+# Strict domain validation (only these domains are accepted)
+domains:
+  - technology
+  - architecture
+  - business
+
+# Phase definitions with optional aliases
+phases:
+  - id: 1
+    name: "Foundation"
+    aliases: ["launch", "mvp"]
+  - id: 2
+    name: "Growth"
+
+# Query hints for domain classification
+query_hints:
+  technology: ["api", "database", "framework", "library"]
+  business: ["pricing", "revenue", "market"]
+
+# Synonym expansion for search
+synonyms:
+  ml: ["machine learning"]
+  ai: ["artificial intelligence"]
+  dkt: ["deep knowledge tracing"]
+
+# Embedding configuration
+embeddings:
+  provider: "voyage"
+  model: "voyage-3-lite"
+  api_key_env: "VOYAGE_API_KEY"
+```
+
+## Search Architecture
+
+The search pipeline uses a 4-stage hybrid approach:
+
+1. **Query Classification** — extracts domains, phases, and query type from natural language
+2. **Metadata Pre-filter** — O(1) lookups via in-memory indices (domain, phase, tag, type)
+3. **Hybrid Scoring** — BM25 full-text search (k1=1.2, b=0.75, title 3x boost) + optional Voyage AI vector embeddings, merged via Reciprocal Rank Fusion (RRF, k=60)
+4. **Hierarchical Expansion** — includes ancestor documents and cross-references within a word budget
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `VOYAGE_API_KEY` | No | Voyage AI API key for semantic embeddings |
+| `LOG_LEVEL` | No | Logging verbosity: `debug`, `info` (default), `warn`, `error` |
+
+## License
+
+MIT

package/dist/analytics.d.ts

@@ -0,0 +1,24 @@
+import type { KnowledgeGraph } from "./graph.js";
+export interface GraphStats {
+    totalDocs: number;
+    byType: Map<string, number>;
+    byDomain: Map<string, number>;
+    byPhase: Map<string, number>;
+    topTags: Array<{
+        tag: string;
+        count: number;
+    }>;
+    crossLinkDensity: number;
+    mostConnected: Array<{
+        id: string;
+        connections: number;
+    }>;
+    orphanCount: number;
+    embeddingCoverage: {
+        total: number;
+        covered: number;
+        percent: number;
+    };
+}
+export declare function computeStats(graph: KnowledgeGraph): GraphStats;
+export declare function formatStats(stats: GraphStats): string;

package/dist/analytics.js

@@ -0,0 +1,102 @@
+export function computeStats(graph) {
+    const byType = new Map();
+    const byDomain = new Map();
+    const byPhase = new Map();
+    const tagCounts = new Map();
+    const connectionCounts = new Map();
+    let totalRelated = 0;
+    let orphanCount = 0;
+    for (const doc of graph.documents.values()) {
+        // By type
+        byType.set(doc.type, (byType.get(doc.type) || 0) + 1);
+        // By domain
+        byDomain.set(doc.domain, (byDomain.get(doc.domain) || 0) + 1);
+        // By phase
+        for (const p of doc.phase) {
+            const key = `phase-${p}`;
+            byPhase.set(key, (byPhase.get(key) || 0) + 1);
+        }
+        // Tag counts
+        for (const tag of doc.tags) {
+            const lower = tag.toLowerCase();
+            tagCounts.set(lower, (tagCounts.get(lower) || 0) + 1);
+        }
+        // Connection counts (forward related + backlinks)
+        const forwardCount = doc.related.length;
+        const backlinks = graph.backlinkIndex.get(doc.id);
+        const backlinkCount = backlinks ? backlinks.size : 0;
+        const total = forwardCount + backlinkCount;
+        connectionCounts.set(doc.id, total);
+        totalRelated += forwardCount;
+        // Orphan: no related links in or out
+        if (forwardCount === 0 && backlinkCount === 0) {
+            orphanCount++;
+        }
+    }
+    // Top 20 tags by frequency
+    const topTags = [...tagCounts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 20)
+        .map(([tag, count]) => ({ tag, count }));
+    // Most connected docs (top 5)
+    const mostConnected = [...connectionCounts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5)
+        .map(([id, connections]) => ({ id, connections }));
+    // Cross-link density
+    const totalDocs = graph.documents.size;
+    const crossLinkDensity = totalDocs > 0 ? Math.round((totalRelated / totalDocs) * 100) / 100 : 0;
+    // Embedding coverage
+    const covered = [...graph.documents.keys()].filter((id) => graph.embeddings.vectors.has(id)).length;
+    return {
+        totalDocs,
+        byType,
+        byDomain,
+        byPhase,
+        topTags,
+        crossLinkDensity,
+        mostConnected,
+        orphanCount,
+        embeddingCoverage: {
+            total: totalDocs,
+            covered,
+            percent: totalDocs > 0 ? Math.round((covered / totalDocs) * 100) : 0,
+        },
+    };
+}
+export function formatStats(stats) {
+    const lines = ["Knowledge Graph Statistics", "=".repeat(26), ""];
+    lines.push(`Total documents: ${stats.totalDocs}`);
+    lines.push("");
+    lines.push("By type:");
+    for (const [type, count] of [...stats.byType].sort((a, b) => b[1] - a[1])) {
+        lines.push(`  ${type}: ${count}`);
+    }
+    lines.push("");
+    lines.push("By domain:");
+    for (const [domain, count] of [...stats.byDomain].sort((a, b) => b[1] - a[1])) {
+        lines.push(`  ${domain}: ${count}`);
+    }
+    lines.push("");
+    lines.push("By phase:");
+    for (const [phase, count] of [...stats.byPhase].sort()) {
+        lines.push(`  ${phase}: ${count}`);
+    }
+    lines.push("");
+    lines.push("Top tags:");
+    for (const { tag, count } of stats.topTags) {
+        lines.push(`  ${tag}: ${count}`);
+    }
+    lines.push("");
+    lines.push(`Cross-link density: ${stats.crossLinkDensity} related links/doc (avg)`);
+    lines.push(`Unlinked documents: ${stats.orphanCount}`);
+    lines.push("");
+    lines.push("Most connected documents:");
+    for (const { id, connections } of stats.mostConnected) {
+        lines.push(`  ${id}: ${connections} connections`);
+    }
+    lines.push("");
+    lines.push(`Embedding coverage: ${stats.embeddingCoverage.covered}/${stats.embeddingCoverage.total} (${stats.embeddingCoverage.percent}%)`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=analytics.js.map

package/dist/analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.js","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { createKnowledgeServer } from "./index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { buildGraph } from "./graph.js";
+import { validateGraph, formatValidationReport } from "./validator.js";
+import { loadConfig, getEffectiveDomains } from "./config.js";
+import { generateEmbeddings } from "./generate-embeddings.js";
+import { initKnowledgeDir } from "./init.js";
+import { log } from "./logger.js";
+const VERSION = "1.0.0";
+const COMMANDS = ["serve", "embeddings", "init", "validate"];
+function printUsage() {
+    console.log(`knowledge-mcp-server v${VERSION}
+
+Usage: knowledge-mcp-server [command] [options]
+
+Commands:
+  serve       Start the MCP server over stdio (default)
+  embeddings  Generate embeddings for all documents via Voyage AI
+  init        Scaffold a new knowledge/ directory with config template
+  validate    Run graph integrity checks and report issues
+
+Options:
+  --knowledge-dir <path>  Path to knowledge directory (default: ./knowledge)
+  --help, -h              Show this help message
+  --version               Show version number`);
+}
+function parseArgs(argv) {
+    const args = argv.slice(2);
+    let command = "serve";
+    let knowledgeDir = resolve(process.cwd(), "knowledge");
+    // First non-flag argument is the command
+    if (args[0] && !args[0].startsWith("-") && COMMANDS.includes(args[0])) {
+        command = args.shift();
+    }
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--knowledge-dir" && args[i + 1]) {
+            knowledgeDir = resolve(args[++i]);
+        }
+        else if (args[i] === "--help" || args[i] === "-h") {
+            printUsage();
+            process.exit(0);
+        }
+        else if (args[i] === "--version") {
+            console.log(VERSION);
+            process.exit(0);
+        }
+    }
+    return { command, knowledgeDir };
+}
+async function serve(knowledgeDir) {
+    const { server } = createKnowledgeServer(knowledgeDir);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    log.info("server_started", { transport: "stdio" });
+}
+function validate(knowledgeDir) {
+    if (!existsSync(knowledgeDir)) {
+        console.error(`Error: Knowledge directory not found: ${knowledgeDir}`);
+        process.exit(1);
+    }
+    const config = loadConfig(knowledgeDir);
+    const validDomains = getEffectiveDomains(config, knowledgeDir);
+    const graph = buildGraph(knowledgeDir, validDomains);
+    const report = validateGraph(graph);
+    console.log(formatValidationReport(report));
+    const hasIssues = report.orphans.length > 0 ||
+        report.brokenRelated.length > 0 ||
+        report.brokenChildren.length > 0 ||
+        report.circularParents.length > 0;
+    if (hasIssues) {
+        process.exit(1);
+    }
+}
+async function main() {
+    const { command, knowledgeDir } = parseArgs(process.argv);
+    switch (command) {
+        case "serve":
+            await serve(knowledgeDir);
+            break;
+        case "embeddings":
+            await generateEmbeddings(knowledgeDir);
+            break;
+        case "init":
+            initKnowledgeDir(knowledgeDir);
+            break;
+        case "validate":
+            validate(knowledgeDir);
+            break;
+    }
+}
+main().catch((err) => {
+    log.error("fatal", { error: String(err) });
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,39 @@
+export interface PhaseConfig {
+    id: number;
+    name: string;
+    aliases?: string[];
+}
+export interface KnowledgeConfig {
+    name?: string;
+    domains?: string[];
+    phases?: PhaseConfig[];
+    query_hints?: Record<string, string[]>;
+    synonyms?: Record<string, string[]>;
+    embeddings?: {
+        provider?: string;
+        model?: string;
+        api_key_env?: string;
+    };
+}
+/**
+ * Load knowledge.config.yaml from the knowledge directory root.
+ * Returns null if the file is missing or invalid.
+ */
+export declare function loadConfig(knowledgeDir: string): KnowledgeConfig | null;
+/**
+ * Discover domains by scanning top-level directories in the knowledge directory.
+ * Excludes directories starting with ".".
+ */
+export declare function discoverDomains(knowledgeDir: string): string[];
+/**
+ * Return the effective domain list for validation.
+ * - If config specifies domains, return them (strict validation).
+ * - Otherwise return null (permissive — accept any domain).
+ */
+export declare function getEffectiveDomains(config: KnowledgeConfig | null, _knowledgeDir: string): string[] | null;
+/**
+ * Return the effective phase IDs for validation.
+ * - If config specifies phases, return their IDs (strict validation).
+ * - Otherwise return null (permissive — accept any positive integer).
+ */
+export declare function getEffectivePhaseIds(config: KnowledgeConfig | null): number[] | null;

package/dist/config.js

@@ -0,0 +1,80 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { log } from "./logger.js";
+const CONFIG_FILENAME = "knowledge.config.yaml";
+/**
+ * Load knowledge.config.yaml from the knowledge directory root.
+ * Returns null if the file is missing or invalid.
+ */
+export function loadConfig(knowledgeDir) {
+    const configPath = join(knowledgeDir, CONFIG_FILENAME);
+    let raw;
+    try {
+        raw = readFileSync(configPath, "utf-8");
+    }
+    catch {
+        // File doesn't exist — zero-config mode
+        return null;
+    }
+    try {
+        const parsed = parseYaml(raw);
+        if (!parsed || typeof parsed !== "object") {
+            log.warn("config", { error: "Config file is empty or not an object" });
+            return null;
+        }
+        return parsed;
+    }
+    catch (err) {
+        log.warn("config", {
+            error: `Failed to parse ${CONFIG_FILENAME}: ${err instanceof Error ? err.message : String(err)}`,
+        });
+        return null;
+    }
+}
+/**
+ * Discover domains by scanning top-level directories in the knowledge directory.
+ * Excludes directories starting with ".".
+ */
+export function discoverDomains(knowledgeDir) {
+    try {
+        return readdirSync(knowledgeDir)
+            .filter((entry) => {
+            if (entry.startsWith("."))
+                return false;
+            try {
+                return statSync(join(knowledgeDir, entry)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        })
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Return the effective domain list for validation.
+ * - If config specifies domains, return them (strict validation).
+ * - Otherwise return null (permissive — accept any domain).
+ */
+export function getEffectiveDomains(config, _knowledgeDir) {
+    if (config?.domains && config.domains.length > 0) {
+        return config.domains;
+    }
+    return null;
+}
+/**
+ * Return the effective phase IDs for validation.
+ * - If config specifies phases, return their IDs (strict validation).
+ * - Otherwise return null (permissive — accept any positive integer).
+ */
+export function getEffectivePhaseIds(config) {
+    if (config?.phases && config.phases.length > 0) {
+        return config.phases.map((p) => p.id);
+    }
+    return null;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAqBlC,MAAM,eAAe,GAAG,uBAAuB,CAAC;AAEhD;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,YAAoB;IAC7C,MAAM,UAAU,GAAG,IAAI,CAAC,YAAY,EAAE,eAAe,CAAC,CAAC;IACvD,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,wCAAwC;QACxC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAY,CAAC;QACzC,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC1C,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,uCAAuC,EAAE,CAAC,CAAC;YACvE,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,MAAyB,CAAC;IACnC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE;YACjB,KAAK,EAAE,mBAAmB,eAAe,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;SACjG,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,YAAoB;IAClD,IAAI,CAAC;QACH,OAAO,WAAW,CAAC,YAAY,CAAC;aAC7B,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;YAChB,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;gBAAE,OAAO,KAAK,CAAC;YACxC,IAAI,CAAC;gBACH,OAAO,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;YAC3D,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC,CAAC;aACD,IAAI,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAA8B,EAC9B,aAAqB;IAErB,IAAI,MAAM,EAAE,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjD,OAAO,MAAM,CAAC,OAAO,CAAC;IACxB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAA8B;IACjE,IAAI,MAAM,EAAE,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/C,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/embeddings.d.ts

@@ -0,0 +1,26 @@
+import type { KnowledgeDocument } from "./loader.js";
+export interface EmbeddingsStore {
+    vectors: Map<string, number[]>;
+    available: boolean;
+}
+export declare function loadEmbeddings(knowledgeDir: string): EmbeddingsStore;
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+export declare function embedQuery(query: string): Promise<number[] | null>;
+export declare function tokenize(text: string): string[];
+export interface Bm25Index {
+    docTermFreqs: Map<string, Map<string, number>>;
+    docFreq: Map<string, number>;
+    idf: Map<string, number>;
+    docLengths: Map<string, number>;
+    avgDocLength: number;
+    docCount: number;
+}
+/** @deprecated Use Bm25Index — kept for backward compatibility */
+export type TfIdfIndex = Bm25Index;
+export declare function buildTfIdfIndex(docs: Map<string, KnowledgeDocument>): Bm25Index;
+export declare function bm25Score(query: string, docId: string, index: Bm25Index): number;
+/** @deprecated Use bm25Score — kept for backward compatibility */
+export declare const tfidfScore: typeof bm25Score;
+export declare function updateBm25Index(index: Bm25Index, docId: string, doc: KnowledgeDocument | null): void;
+export declare function embedSingleDocument(embeddingsStore: EmbeddingsStore, knowledgeDir: string, doc: KnowledgeDocument): Promise<void>;
+export declare function removeEmbedding(embeddingsStore: EmbeddingsStore, knowledgeDir: string, docId: string): void;