md-semantic-search 0.5.0 → 1.0.1

package/README.md

@@ -419,13 +419,53 @@ const r = await fetch('http://localhost:8747/search', {
 const { results } = await r.json();
 ```
 
-The API is unauthenticated — by default it binds to **loopback only**
+The API is unauthenticated by default (or secured via `--api-key`) — by default it binds to **loopback only**
 (`127.0.0.1`), so other machines on your LAN cannot reach it. Pass `--host
 0.0.0.0` (or `MDSS_HOST`) only if you intend to expose it on a network, and put
 a reverse proxy (or at least a firewall rule) in front of it. Request bodies
 are capped at 64 KB (oversized → `413`), and malformed JSON gets a clear `400`
 instead of being silently swallowed.
 
+### 4. MCP Server (Claude Desktop, Cursor, Copilot, Antigravity)
+
+`md-semantic-search` provides a zero-dependency **Model Context Protocol (MCP)** server over standard I/O (JSON-RPC 2.0). This allows AI agents and IDEs to query your local notes privately by meaning without uploading text to external clouds.
+
+```bash
+mdss mcp --db /path/to/your/markdown
+```
+
+#### Available MCP Tools:
+- **`search_markdown`**: Hybrid semantic vector + BM25 search with optional `path` glob and `tag` filters.
+- **`get_chunk`**: Retrieve a specific section by file and heading.
+- **`list_files`**: List indexed Markdown files with chunk counts.
+- **`index_status`**: Inspect index health, chunk counts, and model metadata.
+
+#### Claude Desktop Configuration:
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "md-semantic-search": {
+      "command": "npx",
+      "args": ["-y", "md-semantic-search", "mcp", "--db", "C:\\path\\to\\your\\notes"]
+    }
+  }
+}
+```
+
+#### Cursor Configuration (`.cursor/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "md-semantic-search": {
+      "command": "npx",
+      "args": ["-y", "md-semantic-search", "mcp", "--db", "./notes"]
+    }
+  }
+}
+```
+
 ### Options
 
 | Flag | Meaning |
@@ -446,6 +486,8 @@ instead of being silently swallowed.
 | `--json` | Machine-readable output: `index` → build result JSON, `stats` → index stats JSON, `search` → hit list JSON (each hit includes `matches` — the query terms found in the chunk). |
 | `--semantic` | `search` only: pure vector ranking, skip lexical/RRF fusion (zero lexical tokenization). |
 | `--rerank` | Re-rank the candidate pool with a cross-encoder (`Xenova/bge-reranker-base`, ~280 MB model, downloaded on first use). Slower, sharper results — see *Reranking* below. |
+| `--graph-boost <n>` | Weight for Obsidian wikilink graph ranking and PageRank prior (search; default 0). Incorporates document centrality and 2-hop contextual propagation. |
+| `--filter <expr>` | Rich boolean filter across frontmatter tags and properties (e.g. `tag:engineering AND status != archived`). |
 | `--ann` | Approximate nearest neighbor search via IVF clustering (search; auto-enables for large corpora). |
 | `--nprobe <n>` | Number of nearest centroid clusters to probe during ANN search (default 8). |
 | `--port <n>` | HTTP port for `serve` (default 8747, or `MDSS_PORT`). |
@@ -607,6 +649,7 @@ is an in-memory dot-product sweep.
 ## Integrations
 
 - **Obsidian**: An official plugin is available in [`integrations/obsidian`](./integrations/obsidian) providing a live semantic search panel directly in your vault connected to `mdss serve`.
+- **Model Context Protocol (MCP)**: Native stdio JSON-RPC 2.0 server (`mdss mcp`) integrating with Claude Desktop, Cursor, Copilot, Antigravity, and AI agents for local knowledge retrieval.
 
 ## License
 

package/bin/cli.mjs

@@ -17,6 +17,7 @@ import os from 'node:os';
 import crypto from 'node:crypto';
 import { buildIndex } from '../dist/indexer.js';
 import { search } from '../dist/search.js';
+import { searchFederated } from '../dist/federation.js';
 import { createServe, DEFAULT_PORT, DEFAULT_HOST } from '../dist/serve.js';
 import { MODELS, DEFAULT_MODEL, resolveModel } from '../dist/models.js';
 import { decodeVec, walkMarkdown, SCHEMA_VERSION, assertSafePath } from '../dist/core.js';
@@ -41,7 +42,7 @@ function defaultCacheDir() {
 }
 
 function parseArgs(argv) {
-  const opts = { _: [], ignore: [], path: [] };
+  const opts = { _: [], ignore: [], path: [], vaults: [] };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--json') opts.json = true;
@@ -60,6 +61,7 @@ function parseArgs(argv) {
     else if (a === '--no-vectors' || a === '--no-vector') opts.noVectors = true;
     else if (a === '--output' || a === '-o') opts.output = nextValue(argv, ++i, a);
     else if (a === '--db') opts.db = nextValue(argv, ++i, a);
+    else if (a === '--vault') opts.vaults.push(nextValue(argv, ++i, a));
     else if (a === '--index-dir') opts.indexDir = nextValue(argv, ++i, a);
     else if (a === '--cache-dir') opts.cacheDir = nextValue(argv, ++i, a);
     else if (a === '--model') opts.model = nextValue(argv, ++i, a);
@@ -86,6 +88,15 @@ function parseArgs(argv) {
     else if (a === '--type') opts.type = nextValue(argv, ++i, a);
     else if (a === '--status') opts.status = nextValue(argv, ++i, a);
     else if (a === '--canonical') opts.canonical = true;
+    else if (a === '--graph-boost') opts.graphBoost = nextFloat(argv, ++i, a);
+    else if (a === '--filter') opts.filter = nextValue(argv, ++i, a);
+    else if (a === '--quantize') opts.quantize = nextValue(argv, ++i, a);
+    else if (a === '--rag') opts.rag = true;
+    else if (a === '--auto-tag') opts.autoTag = true;
+    else if (a === '--auto-summarize') opts.autoSummarize = true;
+    else if (a === '--llm-endpoint') opts.llmEndpoint = nextValue(argv, ++i, a);
+    else if (a === '--llm-model') opts.llmModel = nextValue(argv, ++i, a);
+    else if (a === '--system-prompt') opts.systemPrompt = nextValue(argv, ++i, a);
     else if (a.startsWith('-')) die(`unknown option: ${a}. Try \`mdss --help\`.`);
     else opts._.push(a);
   }
@@ -107,13 +118,23 @@ function nextInt(argv, i, flag) {
   return k;
 }
 
+/** Like nextValue but requires a non-negative float. */
+function nextFloat(argv, i, flag) {
+  const v = nextValue(argv, i, flag);
+  const f = Number.parseFloat(v);
+  if (!Number.isFinite(f) || f < 0) die(`${flag} must be a non-negative number, got "${v}"`);
+  return f;
+}
+
 const KNOWN_CONFIG_KEYS = new Set([
   'db', 'model', 'indexDir', 'index-dir', 'cacheDir', 'cache-dir',
   'ignore', 'path', 'k', 'maxPerFile', 'max-per-file', 'maxPerDoc', 'max-per-doc',
   'targetTokens', 'target-tokens', 'port', 'host', 'apiKey', 'api-key',
   'healthPublic', 'health-public', 'watch', 'watchInterval', 'watch-interval',
   'watchDelay', 'watch-delay', 'offline', 'rerank', 'semantic', 'tag', 'project', 'type', 'status', 'canonical',
-  'format', 'noVectors', 'no-vectors', 'output', 'workers', 'ann', 'nprobe'
+  'format', 'noVectors', 'no-vectors', 'output', 'workers', 'ann', 'nprobe', 'graphBoost', 'graph-boost', 'filter', 'quantize',
+  'vault', 'vaults', 'rag', 'autoTag', 'auto-tag', 'autoSummarize', 'auto-summarize',
+  'llmEndpoint', 'llm-endpoint', 'llmModel', 'llm-model', 'systemPrompt', 'system-prompt'
 ]);
 
 function findConfigFile(explicitPath) {
@@ -252,6 +273,8 @@ Options:
   --json              Machine-readable output (index, stats, search).
   --semantic          Pure vector ranking, skip lexical/RRF fusion (search).
   --rerank            Re-rank candidates with a cross-encoder (search; ~280MB model).
+  --graph-boost <n>   Boost weight for graph PageRank / Obsidian wikilinks (search, default: 0).
+  --filter <expr>     Rich boolean filter across frontmatter tags and properties (search).
   --ann               Approximate nearest neighbor search via IVF (search).
   --nprobe <n>        Number of centroids to probe for ANN (search, default: 8).
   --port <n>          HTTP port for serve (default: ${DEFAULT_PORT}).
@@ -319,6 +342,7 @@ async function cmdIndex(opts) {
       offline: resolveOffline(opts),
       workers: opts.workers,
       ann: opts.ann,
+      quantize: opts.quantize,
       log: s => {
         if (process.stderr.isTTY && !opts.json && /^\s+\d+\/\d+$/.test(s)) return;
         process.stderr.write(s + '\n');
@@ -863,35 +887,103 @@ async function cmdTui(opts) {
     offline: resolveOffline(opts),
     path: opts.path.length > 0 ? opts.path : undefined,
     rerank: !!opts.rerank,
+    rag: !!opts.rag,
   });
 }
 
-async function cmdSearch(opts) {
-  if (opts.interactive) return cmdTui(opts);
+async function cmdAsk(opts) {
+  const query = opts._.join(' ').trim();
+  if (!query) die('missing question to ask. Usage: mdss ask [--db <dir>] "question"');
+
   const db = resolveDb(opts);
   const indexDir = resolveIndexDir(opts, db);
   const cacheDir = resolveCache(opts);
+  const k = opts.k || 5;
+
+  const { askQuestion } = await import('../dist/rag.js');
+  const result = await askQuestion({
+    query,
+    indexDir,
+    cacheDir,
+    k,
+    llmEndpoint: opts.llmEndpoint,
+    llmModel: opts.llmModel,
+    systemPrompt: opts.systemPrompt,
+  });
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    return;
+  }
+
+  process.stdout.write(`\n${result.answer}\n\n`);
+  if (result.citations && result.citations.length > 0) {
+    process.stdout.write('Sources:\n');
+    for (const c of result.citations) {
+      const heading = c.heading ? ` › ${c.heading}` : '';
+      process.stdout.write(`  - ${c.file}${heading} [score: ${c.score.toFixed(3)}]\n`);
+    }
+    process.stdout.write('\n');
+  }
+}
+
+async function cmdSearch(opts) {
+  if (opts.interactive) return cmdTui(opts);
+  const cacheDir = resolveCache(opts);
   const query = opts._.join(' ').trim();
   if (!query) die('Missing query text. e.g. mdss search --db ./docs "your question"');
 
-  const results = await search({
-    indexDir, cacheDir, query,
-    k: opts.k || 6,
-    semanticOnly: !!opts.semantic,
-    offline: resolveOffline(opts),
-    path: opts.path.length > 0 ? opts.path : undefined,
-    since: opts.since,
-    rerank: !!opts.rerank,
-    tag: opts.tag,
-    project: opts.project,
-    type: opts.type,
-    status: opts.status,
-    canonicalOnly: opts.canonical,
-    explain: !!opts.explain,
-    maxPerFile: opts.maxPerFile || opts.maxPerDoc,
-    ann: opts.ann,
-    nprobe: opts.nprobe,
-  });
+  let results;
+  const isFederated = Array.isArray(opts.vaults) && opts.vaults.length > 0;
+
+  if (isFederated) {
+    results = await searchFederated({
+      vaults: opts.vaults,
+      cacheDir,
+      query,
+      k: opts.k || 6,
+      semanticOnly: !!opts.semantic,
+      offline: resolveOffline(opts),
+      path: opts.path.length > 0 ? opts.path : undefined,
+      since: opts.since,
+      rerank: !!opts.rerank,
+      tag: opts.tag,
+      project: opts.project,
+      type: opts.type,
+      status: opts.status,
+      canonicalOnly: opts.canonical,
+      explain: !!opts.explain,
+      maxPerFile: opts.maxPerFile || opts.maxPerDoc,
+      ann: opts.ann,
+      nprobe: opts.nprobe,
+      graphBoost: opts.graphBoost,
+      filter: opts.filter,
+    });
+  } else {
+    const db = resolveDb(opts);
+    const indexDir = resolveIndexDir(opts, db);
+
+    results = await search({
+      indexDir, cacheDir, query,
+      k: opts.k || 6,
+      semanticOnly: !!opts.semantic,
+      offline: resolveOffline(opts),
+      path: opts.path.length > 0 ? opts.path : undefined,
+      since: opts.since,
+      rerank: !!opts.rerank,
+      tag: opts.tag,
+      project: opts.project,
+      type: opts.type,
+      status: opts.status,
+      canonicalOnly: opts.canonical,
+      explain: !!opts.explain,
+      maxPerFile: opts.maxPerFile || opts.maxPerDoc,
+      ann: opts.ann,
+      nprobe: opts.nprobe,
+      graphBoost: opts.graphBoost,
+      filter: opts.filter,
+    });
+  }
 
   if (opts.json) { process.stdout.write(JSON.stringify(results, null, 2) + '\n'); return; }
   if (results.length === 0) { process.stdout.write('No matches.\n'); return; }
@@ -901,13 +993,14 @@ async function cmdSearch(opts) {
   // Group by file (issue #13): each file becomes a header with its hits below.
   const byFile = new Map();
   for (const r of results) {
-    if (!byFile.has(r.file)) byFile.set(r.file, []);
-    byFile.get(r.file).push(r);
+    const fileKey = r.vault ? `[${r.vault}] ${r.file}` : r.file;
+    if (!byFile.has(fileKey)) byFile.set(fileKey, []);
+    byFile.get(fileKey).push(r);
   }
   const color = !!process.stdout.isTTY; // bold matched terms only on a real terminal
   let rank = 0;
-  for (const [file, hits] of byFile) {
-    process.stdout.write(`${file}\n`);
+  for (const [fileHeader, hits] of byFile) {
+    process.stdout.write(`${fileHeader}\n`);
     for (const r of hits) {
       rank++;
       let snippet = r.snippet;
@@ -1034,6 +1127,7 @@ async function main() {
     case 'doctor': return cmdCheck(opts);
     case 'export': return cmdExport(opts);
     case 'search': return cmdSearch(opts);
+    case 'ask': return cmdAsk(opts);
     case 'tui': return cmdTui(opts);
     case 'serve': return cmdServe(opts);
     case 'mcp': return cmdMcp(opts);
@@ -1052,7 +1146,7 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
 // functions are unit-tested directly; die() is asserted via a mocked
 // process.exit so a bad flag cannot kill the test runner.
 export {
-  parseArgs, nextInt, nextValue,
+  parseArgs, nextInt, nextFloat, nextValue,
   resolveDb, resolveIndexDir, resolveCache, resolveOffline,
   findConfigFile, loadConfigFile, applyConfigDefaults, KNOWN_CONFIG_KEYS,
   checkHealth, cmdExport,

package/dist/binary-format.d.ts

@@ -0,0 +1,25 @@
+import { PersistedIndex } from './indexer.js';
+export declare const BINARY_MAGIC = "MDSSBIN1";
+export declare const BINARY_HEADER_SIZE = 64;
+export declare const BINARY_VERSION = 1;
+export declare const BINARY_FLAG_FP32 = 0;
+export declare const BINARY_FLAG_INT8 = 1;
+export interface BinaryIndexHeader {
+    version: number;
+    flags: number;
+    dim: number;
+    chunkCount: number;
+    vectorsOffset: number;
+    vectorsBytes: number;
+    metadataOffset: number;
+    metadataBytes: number;
+}
+export interface SerializeBinaryOptions {
+    quantize?: 'fp32' | 'int8';
+}
+export declare function serializeBinaryIndex(index: PersistedIndex, dim: number, options?: SerializeBinaryOptions): Buffer;
+export declare function readBinaryHeader(buffer: Buffer): BinaryIndexHeader;
+export declare function deserializeBinaryIndex(buffer: Buffer): PersistedIndex & {
+    rawVectorsBuffer: Float32Array | Int8Array;
+    quantized?: 'fp32' | 'int8';
+};

package/dist/binary-format.js

@@ -0,0 +1,178 @@
+/**
+ * Zero-Copy Binary Index Storage (vectors.bin) format (issue #95).
+ *
+ * Binary Layout:
+ * ┌────────────────────────────────────────────────────────┐
+ * │ Header (64 bytes):                                     │
+ * │  0..7:   Magic 'MDSSBIN1'                              │
+ * │  8..11:  Version (uint32 = 1)                          │
+ * │  12..15: Flags (uint32: 0=FP32, 1=INT8)               │
+ * │  16..19: Dim (uint32)                                  │
+ * │  20..23: ChunkCount (uint32)                           │
+ * │  24..31: VectorsOffset (uint64)                        │
+ * │  32..39: VectorsBytes (uint64)                         │
+ * │  40..47: MetadataOffset (uint64)                       │
+ * │  48..55: MetadataBytes (uint64)                        │
+ * │  56..63: Reserved (8 bytes zeros)                      │
+ * ├────────────────────────────────────────────────────────┤
+ * │ Vectors Section:                                       │
+ * │  Contiguous float32 array: [chunkCount * dim * 4 bytes]│
+ * ├────────────────────────────────────────────────────────┤
+ * │ Metadata Section:                                      │
+ * │  UTF-8 JSON string (chunks metadata + lexical state)   │
+ * └────────────────────────────────────────────────────────┘
+ */
+import { decodeVec } from './core.js';
+import { quantizeToInt8 } from './quantization.js';
+export const BINARY_MAGIC = 'MDSSBIN1';
+export const BINARY_HEADER_SIZE = 64;
+export const BINARY_VERSION = 1;
+export const BINARY_FLAG_FP32 = 0;
+export const BINARY_FLAG_INT8 = 1;
+export function serializeBinaryIndex(index, dim, options = {}) {
+    const isInt8 = options.quantize === 'int8';
+    const bytesPerElement = isInt8 ? 1 : 4;
+    const count = index.chunks.length;
+    const vectorsBytes = count * dim * bytesPerElement;
+    const vectorsOffset = BINARY_HEADER_SIZE;
+    const flags = isInt8 ? BINARY_FLAG_INT8 : BINARY_FLAG_FP32;
+    // Build contiguous typed array
+    const rawArray = isInt8 ? new Int8Array(count * dim) : new Float32Array(count * dim);
+    for (let i = 0; i < count; i++) {
+        const chunk = index.chunks[i];
+        let v;
+        if (typeof chunk.vec === 'string') {
+            v = decodeVec(chunk.vec, dim);
+        }
+        else if (chunk.vec instanceof Float32Array || chunk.vec instanceof Int8Array || Array.isArray(chunk.vec)) {
+            v = chunk.vec;
+        }
+        else {
+            throw new Error(`chunk ${i} is missing vector for binary serialization`);
+        }
+        if (isInt8) {
+            const q = v instanceof Int8Array ? v : quantizeToInt8(v);
+            rawArray.set(q, i * dim);
+        }
+        else {
+            rawArray.set(v, i * dim);
+        }
+    }
+    // Build metadata JSON omitting per-chunk vec strings to save space
+    const metadataChunks = index.chunks.map((c) => ({
+        file: c.file,
+        title: c.title,
+        heading: c.heading,
+        headingPath: c.headingPath,
+        text: c.text,
+        chunkHash: c.chunkHash,
+        startLine: c.startLine,
+        endLine: c.endLine,
+        meta: c.meta,
+    }));
+    const metadataObj = {
+        schemaVersion: index.schemaVersion,
+        format: 'binary-v1',
+        model: index.model,
+        modelAlias: index.modelAlias,
+        adapterFingerprint: index.adapterFingerprint,
+        dim,
+        db: index.db,
+        built: index.built,
+        complete: index.complete,
+        chunkCount: count,
+        quantized: isInt8 ? 'int8' : 'fp32',
+        lexical: index.lexical,
+        lexicalFormat: index.lexicalFormat,
+        chunks: metadataChunks,
+    };
+    const metadataBuffer = Buffer.from(JSON.stringify(metadataObj), 'utf8');
+    const metadataOffset = vectorsOffset + vectorsBytes;
+    const metadataBytes = metadataBuffer.length;
+    const totalSize = metadataOffset + metadataBytes;
+    const out = Buffer.alloc(totalSize);
+    // Write 64-byte header
+    out.write(BINARY_MAGIC, 0, 8, 'ascii');
+    out.writeUInt32LE(BINARY_VERSION, 8);
+    out.writeUInt32LE(flags, 12);
+    out.writeUInt32LE(dim, 16);
+    out.writeUInt32LE(count, 20);
+    out.writeBigUInt64LE(BigInt(vectorsOffset), 24);
+    out.writeBigUInt64LE(BigInt(vectorsBytes), 32);
+    out.writeBigUInt64LE(BigInt(metadataOffset), 40);
+    out.writeBigUInt64LE(BigInt(metadataBytes), 48);
+    // Copy vectors
+    Buffer.from(rawArray.buffer, rawArray.byteOffset, rawArray.byteLength).copy(out, vectorsOffset);
+    // Copy metadata
+    metadataBuffer.copy(out, metadataOffset);
+    return out;
+}
+export function readBinaryHeader(buffer) {
+    if (buffer.length < BINARY_HEADER_SIZE) {
+        throw new Error(`Invalid binary index: file too small (${buffer.length} bytes, expected at least ${BINARY_HEADER_SIZE})`);
+    }
+    const magic = buffer.toString('ascii', 0, 8);
+    if (magic !== BINARY_MAGIC) {
+        throw new Error(`Invalid binary index magic: expected "${BINARY_MAGIC}", got "${magic}"`);
+    }
+    const version = buffer.readUInt32LE(8);
+    const flags = buffer.readUInt32LE(12);
+    const dim = buffer.readUInt32LE(16);
+    const chunkCount = buffer.readUInt32LE(20);
+    const vectorsOffset = Number(buffer.readBigUInt64LE(24));
+    const vectorsBytes = Number(buffer.readBigUInt64LE(32));
+    const metadataOffset = Number(buffer.readBigUInt64LE(40));
+    const metadataBytes = Number(buffer.readBigUInt64LE(48));
+    return {
+        version,
+        flags,
+        dim,
+        chunkCount,
+        vectorsOffset,
+        vectorsBytes,
+        metadataOffset,
+        metadataBytes,
+    };
+}
+export function deserializeBinaryIndex(buffer) {
+    const header = readBinaryHeader(buffer);
+    const { flags, dim, chunkCount, vectorsOffset, vectorsBytes, metadataOffset, metadataBytes } = header;
+    const isInt8 = (flags & BINARY_FLAG_INT8) !== 0;
+    const expectedVectorsBytes = chunkCount * dim * (isInt8 ? 1 : 4);
+    if (buffer.length < vectorsOffset + expectedVectorsBytes || buffer.length < metadataOffset + metadataBytes) {
+        throw new Error('Corrupt binary index: unexpected truncated file');
+    }
+    const byteOffset = buffer.byteOffset + vectorsOffset;
+    let rawVectorsBuffer;
+    if (isInt8) {
+        rawVectorsBuffer = new Int8Array(buffer.buffer, byteOffset, chunkCount * dim);
+    }
+    else {
+        // Aligned 4-byte Float32Array view
+        if (byteOffset % 4 === 0) {
+            rawVectorsBuffer = new Float32Array(buffer.buffer, byteOffset, chunkCount * dim);
+        }
+        else {
+            const aligned = Buffer.alloc(vectorsBytes);
+            buffer.copy(aligned, 0, vectorsOffset, vectorsOffset + vectorsBytes);
+            rawVectorsBuffer = new Float32Array(aligned.buffer, aligned.byteOffset, chunkCount * dim);
+        }
+    }
+    // Deserialize metadata JSON
+    const metaJson = buffer.toString('utf8', metadataOffset, metadataOffset + metadataBytes);
+    const parsed = JSON.parse(metaJson);
+    // Re-attach subarray views to chunks
+    const chunks = parsed.chunks.map((c, i) => {
+        const vecSlice = rawVectorsBuffer.subarray(i * dim, (i + 1) * dim);
+        return {
+            ...c,
+            vec: vecSlice,
+        };
+    });
+    return {
+        ...parsed,
+        chunks,
+        rawVectorsBuffer,
+        quantized: isInt8 ? 'int8' : 'fp32',
+    };
+}

package/dist/core.d.ts

@@ -1,7 +1,8 @@
 import { resolveModel, ModelAdapter, Pooling, DType } from './models.js';
 import { PARSER_VERSION, StructuralChunk } from './markdown-parser.js';
 import { parseFrontmatter, DocumentMetadata } from './frontmatter.js';
-export { PARSER_VERSION, parseFrontmatter, resolveModel, DocumentMetadata, ModelAdapter, Pooling, DType };
+import { asymmetricCosineInt8 } from './quantization.js';
+export { PARSER_VERSION, parseFrontmatter, resolveModel, DocumentMetadata, ModelAdapter, Pooling, DType, asymmetricCosineInt8 };
 export declare const LOCK_FILENAME = ".mdss.lock";
 export declare function pidAlive(pid: number | null): boolean;
 export interface LockInfo {
@@ -47,7 +48,7 @@ export declare function embed(texts: string[], kind: 'query' | 'passage', model:
     delays?: number[];
     log?: (msg: string) => void;
 }): Promise<number[][]>;
-export declare function cosine(a: Float32Array | number[], b: Float32Array | number[], bOffset?: number): number;
+export declare function cosine(a: Float32Array | number[], b: Float32Array | Int8Array | number[], bOffset?: number): number;
 export declare function encodeVec(vec: number[] | Float32Array): string;
 export declare function decodeVec(s: string, dim?: number): Float32Array;
 export declare function isBinaryIndex(index: {

package/dist/core.js

@@ -5,11 +5,11 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import os from 'node:os';
 import { resolveModel } from './models.js';
 import { chunkMarkdownStructural, PARSER_VERSION } from './markdown-parser.js';
 import { parseFrontmatter } from './frontmatter.js';
-export { PARSER_VERSION, parseFrontmatter, resolveModel };
+import { asymmetricCosineInt8 } from './quantization.js';
+export { PARSER_VERSION, parseFrontmatter, resolveModel, asymmetricCosineInt8 };
 const _extractors = new Map();
 export const LOCK_FILENAME = '.mdss.lock';
 const LOCK_STALE_MS = 10 * 60 * 1000;
@@ -248,6 +248,11 @@ export async function embed(texts, kind, model, cacheDir, offline = false, retry
     return out.tolist();
 }
 export function cosine(a, b, bOffset = 0) {
+    if (b instanceof Int8Array) {
+        const qF32 = a instanceof Float32Array ? a : Float32Array.from(a);
+        const chunkInt8 = bOffset === 0 && b.length === qF32.length ? b : b.subarray(bOffset, bOffset + qF32.length);
+        return asymmetricCosineInt8(qF32, chunkInt8);
+    }
     const len = a.length;
     let s0 = 0, s1 = 0, s2 = 0, s3 = 0;
     let s4 = 0, s5 = 0, s6 = 0, s7 = 0;
@@ -364,6 +369,12 @@ export function assertSafePath(targetPath, allowedRoots) {
     if (typeof targetPath !== 'string' || !targetPath.trim()) {
         throw new Error('path must be a non-empty string');
     }
+    if (targetPath.includes('\0')) {
+        throw new Error('Forbidden path: null byte detected in path');
+    }
+    if (targetPath.startsWith('\\\\') || targetPath.startsWith('//')) {
+        throw new Error('Forbidden path: UNC network paths not allowed');
+    }
     const resolved = path.resolve(targetPath);
     let canonical = resolved;
     try {
@@ -377,40 +388,21 @@ export function assertSafePath(targetPath, allowedRoots) {
         if (process.env.MDSS_ROOT_GUARD) {
             roots = process.env.MDSS_ROOT_GUARD.split(path.delimiter).map((p) => path.resolve(p.trim())).filter(Boolean);
         }
-        else {
-            roots = [path.resolve(process.cwd())];
-            try {
-                const parent = path.resolve(process.cwd(), '..');
-                if (parent)
-                    roots.push(parent);
-            }
-            catch { }
-            try {
-                const home = os.homedir();
-                if (home)
-                    roots.push(path.resolve(home));
-            }
-            catch { }
+    }
+    if (roots && roots.length > 0) {
+        const isAllowed = roots.some((root) => {
+            let canonicalRoot = root;
             try {
-                const tmp = os.tmpdir();
-                if (tmp)
-                    roots.push(path.resolve(tmp));
+                canonicalRoot = fs.realpathSync(root);
             }
             catch { }
+            const rel = path.relative(canonicalRoot, canonical);
+            return !rel.startsWith('..') && !path.isAbsolute(rel);
+        });
+        if (!isAllowed) {
+            throw new Error(`path traversal guard: "${targetPath}" (resolving to "${canonical}") is outside allowed directory roots`);
         }
     }
-    const isAllowed = roots.some((root) => {
-        let canonicalRoot = root;
-        try {
-            canonicalRoot = fs.realpathSync(root);
-        }
-        catch { }
-        const rel = path.relative(canonicalRoot, canonical);
-        return !rel.startsWith('..') && !path.isAbsolute(rel);
-    });
-    if (!isAllowed) {
-        throw new Error(`path traversal guard: "${targetPath}" (resolving to "${canonical}") is outside allowed directory roots`);
-    }
     return canonical;
 }
 export function validateGlob(glob) {

package/dist/federation.d.ts

@@ -0,0 +1,15 @@
+import { SearchOptions, SearchResultHit } from './search.js';
+export interface VaultConfig {
+    name?: string;
+    path: string;
+    indexDir?: string;
+}
+export interface FederatedSearchOptions extends Omit<SearchOptions, 'loaded' | 'cacheDir'> {
+    vaults: Array<string | VaultConfig>;
+    cacheDir?: string;
+}
+export interface FederatedSearchResultHit extends SearchResultHit {
+    vault: string;
+    vaultPath: string;
+}
+export declare function searchFederated(opts: FederatedSearchOptions): Promise<FederatedSearchResultHit[]>;