@ambicuity/kindx 0.1.0 → 1.1.0

package/bin/kindx

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import child_process from 'child_process';
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath, pathToFileURL } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Path to the compiled kindx executable
+const binPath = path.join(__dirname, '..', 'dist', 'kindx.js');
+
+if (!fs.existsSync(binPath)) {
+  console.error("Executable not found at " + binPath);
+  console.error("Did you run 'npm run build'?");
+  process.exit(1);
+}
+
+// Detect if running under bun. Bun has ABI mismatches with node's better-sqlite3
+if (process.versions && process.versions.bun) {
+  console.warn("WARNING: Running KINDX under Bun is known to cause better-sqlite3 ABI crashes.");
+  console.warn("Attempting to spawn the process under Node.js instead...");
+  
+  try {
+    const result = child_process.spawnSync('node', [binPath, ...process.argv.slice(2)], {
+      stdio: 'inherit',
+      env: process.env
+    });
+    process.exit(result.status ?? 0);
+  } catch (err) {
+    console.error("Failed to spawn node. Please ensure Node.js is installed.");
+    process.exit(1);
+  }
+} else {
+  // If not bun, just import the compiled js directly
+  process.argv[1] = binPath;
+  import(pathToFileURL(binPath).href);
+}

package/capabilities/kindx/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: kindx
+description: Search markdown knowledge bases, notes, and documentation using KINDX. Use when users ask to search notes, find documents, or look up information.
+license: MIT
+compatibility: Requires kindx CLI or MCP server. Install via `npm install -g @ambicuity/kindx`.
+metadata:
+  author: riteshrana
+  version: "2.0.0"
+allowed-tools: Bash(kindx:*), mcp__kindx__*
+---
+
+# KINDX - Knowledge INDexer
+
+Local search engine for markdown content.
+
+## Status
+
+!`kindx status 2>/dev/null || echo "Not installed: npm install -g @ambicuity/kindx"`
+
+## MCP: `query`
+
+```json
+{
+  "searches": [
+    { "type": "lex", "query": "CAP theorem consistency" },
+    { "type": "vec", "query": "tradeoff between consistency and availability" }
+  ],
+  "collections": ["docs"],
+  "limit": 10
+}
+```
+
+### Query Types
+
+| Type | Method | Input |
+|------|--------|-------|
+| `lex` | BM25 | Keywords — exact terms, names, code |
+| `vec` | Vector | Question — natural language |
+| `hyde` | Vector | Answer — hypothetical result (50-100 words) |
+
+### Writing Good Queries
+
+**lex (keyword)**
+- 2-5 terms, no filler words
+- Exact phrase: `"connection pool"` (quoted)
+- Exclude terms: `performance -sports` (minus prefix)
+- Code identifiers work: `handleError async`
+
+**vec (semantic)**
+- Full natural language question
+- Be specific: `"how does the rate limiter handle burst traffic"`
+- Include context: `"in the payment service, how are refunds processed"`
+
+**hyde (hypothetical document)**
+- Write 50-100 words of what the *answer* looks like
+- Use the vocabulary you expect in the result
+
+**expand (auto-expand)**
+- Use a single-line query (implicit) or `expand: question` on its own line
+- Lets the local LLM generate lex/vec/hyde variations
+- Do not mix `expand:` with other typed lines — it's either a standalone expand query or a full query document
+
+### Combining Types
+
+| Goal | Approach |
+|------|----------|
+| Know exact terms | `lex` only |
+| Don't know vocabulary | Use a single-line query (implicit `expand:`) or `vec` |
+| Best recall | `lex` + `vec` |
+| Complex topic | `lex` + `vec` + `hyde` |
+
+First query gets 2x weight in fusion — put your best guess first.
+
+### Lex Query Syntax
+
+| Syntax | Meaning | Example |
+|--------|---------|---------|
+| `term` | Prefix match | `perf` matches "performance" |
+| `"phrase"` | Exact phrase | `"rate limiter"` |
+| `-term` | Exclude | `performance -sports` |
+
+Note: `-term` only works in lex queries, not vec/hyde.
+
+### Collection Filtering
+
+```json
+{ "collections": ["docs"] }              // Single
+{ "collections": ["docs", "notes"] }     // Multiple (OR)
+```
+
+Omit to search all collections.
+
+## Other MCP Tools
+
+| Tool | Use |
+|------|-----|
+| `get` | Retrieve doc by path or `#docid` |
+| `multi_get` | Retrieve multiple by glob/list |
+| `status` | Collections and health |
+
+## CLI
+
+```bash
+kindx query "question"              # Auto-expand + rerank
+kindx query $'lex: X\nvec: Y'       # Structured
+kindx query $'expand: question'     # Explicit expand
+kindx search "keywords"             # BM25 only (no LLM)
+kindx get "#abc123"                 # By docid
+kindx multi-get "journals/2026-*.md" -l 40  # Batch pull snippets by glob
+kindx multi-get notes/foo.md,notes/bar.md   # Comma-separated list, preserves order
+```
+
+## HTTP API
+
+```bash
+curl -X POST http://localhost:8181/query \
+  -H "Content-Type: application/json" \
+  -d '{"searches": [{"type": "lex", "query": "test"}]}'
+```
+
+## Setup
+
+```bash
+npm install -g @ambicuity/kindx
+kindx collection add ~/notes --name notes
+kindx embed
+```

package/capabilities/kindx/references/mcp-setup.md

@@ -0,0 +1,102 @@
+# KINDX MCP Server Setup
+
+## Install
+
+```bash
+npm install -g @ambicuity/kindx
+kindx collection add ~/path/to/markdown --name myknowledge
+kindx embed
+```
+
+## Configure MCP Client
+
+**Claude Code** (`~/.claude/settings.json`):
+```json
+{
+  "mcpServers": {
+    "kindx": { "command": "kindx", "args": ["mcp"] }
+  }
+}
+```
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "kindx": { "command": "kindx", "args": ["mcp"] }
+  }
+}
+```
+
+**OpenClaw** (`~/.openclaw/openclaw.json`):
+```json
+{
+  "mcp": {
+    "servers": {
+      "kindx": { "command": "kindx", "args": ["mcp"] }
+    }
+  }
+}
+```
+
+## HTTP Mode
+
+```bash
+kindx mcp --http              # Port 8181
+kindx mcp --http --daemon     # Background
+kindx mcp stop                # Stop daemon
+```
+
+## Tools
+
+### structured_search
+
+Search with pre-expanded queries.
+
+```json
+{
+  "searches": [
+    { "type": "lex", "query": "keyword phrases" },
+    { "type": "vec", "query": "natural language question" },
+    { "type": "hyde", "query": "hypothetical answer passage..." }
+  ],
+  "limit": 10,
+  "collection": "optional",
+  "minScore": 0.0
+}
+```
+
+| Type | Method | Input |
+|------|--------|-------|
+| `lex` | BM25 | Keywords (2-5 terms) |
+| `vec` | Vector | Question |
+| `hyde` | Vector | Answer passage (50-100 words) |
+
+### get
+
+Retrieve document by path or `#docid`.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `path` | string | File path or `#docid` |
+| `full` | bool? | Return full content |
+| `lineNumbers` | bool? | Add line numbers |
+
+### multi_get
+
+Retrieve multiple documents.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `pattern` | string | Glob or comma-separated list |
+| `maxBytes` | number? | Skip large files (default 10KB) |
+
+### status
+
+Index health and collections. No params.
+
+## Troubleshooting
+
+- **Not starting**: `which kindx`, `kindx mcp` manually
+- **No results**: `kindx collection list`, `kindx embed`
+- **Slow first search**: Normal, models loading (~3GB)

package/dist/catalogs.js

@@ -101,7 +101,13 @@ export function saveConfig(config) {
  */
 export function getCollection(name) {
     const config = loadConfig();
-    const collection = config.collections[name];
+    let collection;
+    if (Array.isArray(config.collections)) {
+        collection = config.collections.find((c) => c.name === name);
+    }
+    else {
+        collection = config.collections[name];
+    }
     if (!collection) {
         return null;
     }
@@ -134,7 +140,13 @@ export function getDefaultCollectionNames() {
  */
 export function updateCollectionSettings(name, settings) {
     const config = loadConfig();
-    const collection = config.collections[name];
+    let collection;
+    if (Array.isArray(config.collections)) {
+        collection = config.collections.find((c) => c.name === name);
+    }
+    else {
+        collection = config.collections[name];
+    }
     if (!collection)
         return false;
     if (settings.update !== undefined) {
@@ -162,11 +174,22 @@ export function updateCollectionSettings(name, settings) {
  */
 export function addCollection(name, path, pattern = "**/*.md") {
     const config = loadConfig();
-    config.collections[name] = {
-        path,
-        pattern,
-        context: config.collections[name]?.context, // Preserve existing context
-    };
+    if (Array.isArray(config.collections)) {
+        const existingIdx = config.collections.findIndex((c) => c.name === name);
+        if (existingIdx >= 0) {
+            config.collections[existingIdx] = { name, path, pattern, context: config.collections[existingIdx].context };
+        }
+        else {
+            config.collections.push({ name, path, pattern });
+        }
+    }
+    else {
+        config.collections[name] = {
+            path,
+            pattern,
+            context: config.collections[name]?.context, // Preserve existing context
+        };
+    }
     saveConfig(config);
 }
 /**
@@ -174,10 +197,18 @@ export function addCollection(name, path, pattern = "**/*.md") {
  */
 export function removeCollection(name) {
     const config = loadConfig();
-    if (!config.collections[name]) {
-        return false;
+    if (Array.isArray(config.collections)) {
+        const idx = config.collections.findIndex((c) => c.name === name);
+        if (idx === -1)
+            return false;
+        config.collections.splice(idx, 1);
+    }
+    else {
+        if (!config.collections[name]) {
+            return false;
+        }
+        delete config.collections[name];
     }
-    delete config.collections[name];
     saveConfig(config);
     return true;
 }
@@ -186,14 +217,24 @@ export function removeCollection(name) {
  */
 export function renameCollection(oldName, newName) {
     const config = loadConfig();
-    if (!config.collections[oldName]) {
-        return false;
+    if (Array.isArray(config.collections)) {
+        if (config.collections.some((c) => c.name === newName))
+            throw new Error(`Collection '${newName}' already exists`);
+        const idx = config.collections.findIndex((c) => c.name === oldName);
+        if (idx === -1)
+            return false;
+        config.collections[idx].name = newName;
     }
-    if (config.collections[newName]) {
-        throw new Error(`Collection '${newName}' already exists`);
+    else {
+        if (!config.collections[oldName]) {
+            return false;
+        }
+        if (config.collections[newName]) {
+            throw new Error(`Collection '${newName}' already exists`);
+        }
+        config.collections[newName] = config.collections[oldName];
+        delete config.collections[oldName];
     }
-    config.collections[newName] = config.collections[oldName];
-    delete config.collections[oldName];
     saveConfig(config);
     return true;
 }

package/dist/inference.d.ts

@@ -159,6 +159,10 @@ export interface LLM {
      * Get embeddings for text
      */
     embed(text: string, options?: EmbedOptions): Promise<EmbeddingResult | null>;
+    /**
+     * Batch get embeddings for text
+     */
+    embedBatch(texts: string[]): Promise<(EmbeddingResult | null)[]>;
     /**
      * Generate text completion
      */
@@ -180,6 +184,28 @@ export interface LLM {
      * Returns list of documents with relevance scores (higher = more relevant)
      */
     rerank(query: string, documents: RerankDocument[], options?: RerankOptions): Promise<RerankResult>;
+    /**
+     * Tokenize text into backend-specific tokens (optional, implemented by local models)
+     */
+    tokenize?(text: string): Promise<readonly any[]>;
+    /**
+     * Detokenize token IDs back to text (optional)
+     */
+    detokenize?(tokens: readonly any[]): Promise<string>;
+    /**
+     * Get device and GPU accelerator info (optional)
+     */
+    getDeviceInfo?(): Promise<{
+        gpu: string | false;
+        gpuOffloading: boolean;
+        gpuDevices: string[];
+        vram?: {
+            total: number;
+            used: number;
+            free: number;
+        };
+        cpuCores: number;
+    }>;
     /**
      * Dispose of resources
      */
@@ -216,6 +242,42 @@ export type LlamaCppConfig = {
      * memory reclaim.
      */
     disposeModelsOnInactivity?: boolean;
+    /**
+     * Force low-VRAM mode on/off.
+     * When undefined, KINDX auto-detects low VRAM from free GPU memory.
+     * Can also be set via KINDX_LOW_VRAM=1|0.
+     */
+    lowVram?: boolean;
+    /**
+     * Optional VRAM budget in MB. When set, KINDX constrains context sizing and
+     * parallelism to fit this budget. Can also be set via KINDX_VRAM_BUDGET_MB.
+     */
+    vramBudgetMB?: number;
+    /**
+     * Free VRAM threshold in MB for auto low-VRAM mode (default: 6144 MB).
+     * Can also be set via KINDX_LOW_VRAM_THRESHOLD_MB.
+     */
+    lowVramThresholdMB?: number;
+    /**
+     * Parallelism cap for embedding contexts when low-VRAM mode is active (default: 2).
+     * Can also be set via KINDX_LOW_VRAM_EMBED_PARALLELISM.
+     */
+    lowVramEmbedParallelism?: number;
+    /**
+     * Parallelism cap for reranker contexts when low-VRAM mode is active (default: 1).
+     * Can also be set via KINDX_LOW_VRAM_RERANK_PARALLELISM.
+     */
+    lowVramRerankParallelism?: number;
+    /**
+     * Expansion context size used when low-VRAM mode is active (default: 1024).
+     * Can also be set via KINDX_LOW_VRAM_EXPAND_CONTEXT_SIZE.
+     */
+    lowVramExpandContextSize?: number;
+    /**
+     * Rerank context size used when low-VRAM mode is active (default: 1024).
+     * Can also be set via KINDX_LOW_VRAM_RERANK_CONTEXT_SIZE.
+     */
+    lowVramRerankContextSize?: number;
 };
 export declare class LlamaCpp implements LLM {
     private llama;
@@ -230,6 +292,15 @@ export declare class LlamaCpp implements LLM {
     private modelCacheDir;
     private rerankContextSize;
     private expandContextSize;
+    private lowVramOverride;
+    private vramBudgetMB;
+    private lowVramThresholdMB;
+    private lowVramEmbedParallelism;
+    private lowVramRerankParallelism;
+    private lowVramExpandContextSize;
+    private lowVramRerankContextSize;
+    private memoryPolicyPromise;
+    private lowVramWarningShown;
     private embedModelLoadPromise;
     private generateModelLoadPromise;
     private rerankModelLoadPromise;
@@ -270,10 +341,14 @@ export declare class LlamaCpp implements LLM {
      * Load embedding model (lazy)
      */
     private ensureEmbedModel;
+    private showLowVramWarning;
+    private resolveMemoryPolicy;
+    private effectiveExpandContextSize;
+    private effectiveRerankContextSize;
     /**
      * Compute how many parallel contexts to create.
      *
-     * GPU: constrained by VRAM (25% of free, capped at 8).
+     * GPU: constrained by free VRAM / budget and low-VRAM policy caps.
      * CPU: constrained by cores. Splitting threads across contexts enables
      *      true parallelism (each context runs on its own cores). Use at most
      *      half the math cores, with at least 4 threads per context.
@@ -384,15 +459,15 @@ export declare function withLLMSession<T>(fn: (session: ILLMSession) => Promise<
  */
 export declare function canUnloadLLM(): boolean;
 /**
- * Get the default LlamaCpp instance (creates one if needed)
+ * Get the default LLM instance (creates one if needed)
  */
-export declare function getDefaultLlamaCpp(): LlamaCpp;
+export declare function getDefaultLLM(): LLM;
 /**
- * Set a custom default LlamaCpp instance (useful for testing)
+ * Set a custom default LLM instance (useful for testing)
  */
-export declare function setDefaultLlamaCpp(llm: LlamaCpp | null): void;
+export declare function setDefaultLLM(llm: LLM | null): void;
 /**
- * Dispose the default LlamaCpp instance if it exists.
+ * Dispose the default LLM instance if it exists.
  * Call this before process exit to prevent NAPI crashes.
  */
-export declare function disposeDefaultLlamaCpp(): Promise<void>;
+export declare function disposeDefaultLLM(): Promise<void>;