context-mode 1.0.26 → 1.0.28

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Claude Code plugins by Mert Koseoğlu",
-    "version": "1.0.26"
+    "version": "1.0.28"
   },
   "plugins": [
     {
       "name": "context-mode",
       "source": "./",
       "description": "Claude Code MCP plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
-      "version": "1.0.26",
+      "version": "1.0.28",
       "author": {
         "name": "Mert Koseoğlu"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.26",
+  "version": "1.0.28",
   "description": "MCP server that saves 98% of your context window with session continuity. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and automatic state restore across compactions.",
   "author": {
     "name": "Mert Koseoğlu",

package/.openclaw-plugin/openclaw.plugin.json

@@ -3,7 +3,7 @@
   "name": "Context Mode",
   "kind": "tool",
   "description": "OpenClaw plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
-  "version": "1.0.26",
+  "version": "1.0.28",
   "sandbox": {
     "mode": "permissive",
     "filesystem_access": "full",

package/.openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.26",
+  "version": "1.0.28",
   "description": "OpenClaw plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
   "author": {
     "name": "Mert Koseoğlu",

package/README.md

@@ -484,7 +484,9 @@ The extension handles session continuity (event capture, resume snapshots, compa
 <details>
 <summary><strong>Build Prerequisites</strong> <sup>(CentOS, RHEL, Alpine)</sup></summary>
 
-Context Mode uses [better-sqlite3](https://github.com/WiseLibs/better-sqlite3), which ships prebuilt native binaries for most platforms. On glibc >= 2.31 systems (Ubuntu 20.04+, Debian 11+, Fedora 34+, macOS, Windows), `npm install` works without any build tools.
+Context Mode uses [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) on Node.js, which ships prebuilt native binaries for most platforms. On glibc >= 2.31 systems (Ubuntu 20.04+, Debian 11+, Fedora 34+, macOS, Windows), `npm install` works without any build tools.
+
+**Bun users:** No native compilation needed. Context Mode automatically detects Bun and uses the built-in `bun:sqlite` module via a compatibility adapter. `better-sqlite3` and all its build dependencies are skipped entirely.
 
 On older glibc systems (CentOS 7/8, RHEL 8, Debian 10), prebuilt binaries don't load and better-sqlite3 **automatically falls back to compiling from source** via `prebuild-install || node-gyp rebuild --release`. This requires a C++20 compiler (GCC 10+), Make, and Python with setuptools.
 
@@ -541,17 +543,26 @@ When output exceeds 5 KB and an `intent` is provided, Context Mode switches to i
 
 ## How the Knowledge Base Works
 
-The `ctx_index` tool chunks markdown content by headings while keeping code blocks intact, then stores them in a **SQLite FTS5** (Full-Text Search 5) virtual table. Search uses **BM25 ranking** — a probabilistic relevance algorithm that scores documents based on term frequency, inverse document frequency, and document length normalization. **Porter stemming** is applied at index time so "running", "runs", and "ran" match the same stem.
+The `ctx_index` tool chunks markdown content by headings while keeping code blocks intact, then stores them in a **SQLite FTS5** (Full-Text Search 5) virtual table. Search uses **BM25 ranking** — a probabilistic relevance algorithm that scores documents based on term frequency, inverse document frequency, and document length normalization. **Porter stemming** is applied at index time so "running", "runs", and "ran" match the same stem. Titles and headings are weighted **5x** in BM25 scoring for precise navigational queries.
+
+When you call `ctx_search`, it returns relevant content snippets focused around matching query terms — not full documents, not approximations, the actual indexed content with smart extraction around what you're looking for. `ctx_fetch_and_index` extends this to URLs: fetch, convert HTML to markdown, chunk, index. The raw page never enters context. Use the `contentType` parameter to filter results by type (e.g. `code` or `prose`).
+
+### Ranking: Reciprocal Rank Fusion
+
+Search runs two parallel strategies and merges them with **Reciprocal Rank Fusion (RRF)**:
+
+- **Porter stemming** — FTS5 MATCH with porter tokenizer. "caching" matches "cached", "caches", "cach".
+- **Trigram substring** — FTS5 trigram tokenizer matches partial strings. "useEff" finds "useEffect", "authenticat" finds "authentication".
+
+RRF merges both ranked lists into a single result set, so a document that ranks well in both strategies surfaces higher than one that ranks well in only one. This replaces the old cascading fallback approach where trigram results were only used if porter returned nothing.
 
-When you call `ctx_search`, it returns relevant content snippets focused around matching query terms — not full documents, not approximations, the actual indexed content with smart extraction around what you're looking for. `ctx_fetch_and_index` extends this to URLs: fetch, convert HTML to markdown, chunk, index. The raw page never enters context.
+### Proximity Reranking
 
-### Fuzzy Search
+Multi-term queries get an additional reranking pass. Results where query terms appear close together are boosted — `"session continuity"` ranks passages with adjacent terms higher than pages where "session" and "continuity" appear paragraphs apart.
 
-Search uses a three-layer fallback to handle typos, partial terms, and substring matches:
+### Fuzzy Correction
 
-- **Layer 1 — Porter stemming**: Standard FTS5 MATCH with porter tokenizer. "caching" matches "cached", "caches", "cach".
-- **Layer 2 — Trigram substring**: FTS5 trigram tokenizer matches partial strings. "useEff" finds "useEffect", "authenticat" finds "authentication".
-- **Layer 3 — Fuzzy correction**: Levenshtein distance corrects typos before re-searching. "kuberntes" → "kubernetes", "autentication" → "authentication".
+Levenshtein distance corrects typos before re-searching. "kuberntes" becomes "kubernetes", "autentication" becomes "authentication".
 
 ### Smart Snippets
 

package/build/cli.js

@@ -256,21 +256,21 @@ async function doctor() {
         p.log.warn(color.yellow("Plugin enabled: WARN") +
             ` — ${pluginCheck.message}`);
     }
-    // FTS5 / better-sqlite3
-    p.log.step("Checking FTS5 / better-sqlite3...");
+    // FTS5 / SQLite
+    p.log.step("Checking FTS5 / SQLite...");
     try {
-        const Database = (await import("better-sqlite3")).default;
+        const Database = (await import("./db-base.js")).loadDatabase();
         const db = new Database(":memory:");
         db.exec("CREATE VIRTUAL TABLE fts_test USING fts5(content)");
         db.exec("INSERT INTO fts_test(content) VALUES ('hello world')");
         const row = db.prepare("SELECT * FROM fts_test WHERE fts_test MATCH 'hello'").get();
         db.close();
         if (row && row.content === "hello world") {
-            p.log.success(color.green("FTS5 / better-sqlite3: PASS") + " — native module works");
+            p.log.success(color.green("FTS5 / SQLite: PASS") + " — native module works");
         }
         else {
             criticalFails++;
-            p.log.error(color.red("FTS5 / better-sqlite3: FAIL") + " — query returned unexpected result");
+            p.log.error(color.red("FTS5 / SQLite: FAIL") + " — query returned unexpected result");
         }
     }
     catch (err) {
@@ -397,7 +397,7 @@ async function upgrade() {
         }
         const items = [
             "build", "src", "hooks", "skills", ".claude-plugin",
-            "start.mjs", "server.bundle.mjs", "cli.bundle.mjs", "package.json",
+            "start.mjs", "native-abi.mjs", "server.bundle.mjs", "cli.bundle.mjs", "package.json",
         ];
         for (const item of items) {
             try {

package/build/db-base.d.ts

@@ -22,9 +22,21 @@ export interface PreparedStatement {
     iterate(...params: unknown[]): IterableIterator<unknown>;
 }
 /**
- * Lazy-load better-sqlite3. Only resolves the native module on first call.
- * This allows the MCP server to start instantly even when the native addon
- * is not yet installed (marketplace first-run scenario).
+ * Wraps a bun:sqlite Database to provide better-sqlite3-compatible API.
+ * Bridges: .pragma(), multi-statement .exec(), .get() null→undefined.
+ */
+export declare class BunSQLiteAdapter {
+    #private;
+    constructor(rawDb: any);
+    pragma(source: string): any;
+    exec(sql: string): any;
+    prepare(sql: string): any;
+    transaction(fn: (...args: any[]) => any): any;
+    close(): void;
+}
+/**
+ * Lazy-load better-sqlite3. Falls back to bun:sqlite via BunSQLiteAdapter
+ * when better-sqlite3 is unavailable (Bun runtime, issue #45).
  */
 export declare function loadDatabase(): typeof DatabaseConstructor;
 /**

package/build/db-base.js

@@ -10,18 +10,110 @@ import { unlinkSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 // ─────────────────────────────────────────────────────────
+// bun:sqlite adapter (#45)
+// ─────────────────────────────────────────────────────────
+/**
+ * Wraps a bun:sqlite Database to provide better-sqlite3-compatible API.
+ * Bridges: .pragma(), multi-statement .exec(), .get() null→undefined.
+ */
+export class BunSQLiteAdapter {
+    #raw;
+    constructor(rawDb) {
+        this.#raw = rawDb;
+    }
+    pragma(source) {
+        const stmt = this.#raw.prepare(`PRAGMA ${source}`);
+        const rows = stmt.all();
+        if (!rows || rows.length === 0)
+            return undefined;
+        // Multi-row pragmas (table_xinfo, etc.) → return array
+        if (rows.length > 1)
+            return rows;
+        // Single-row: extract scalar value (e.g. journal_mode = "wal")
+        const values = Object.values(rows[0]);
+        return values.length === 1 ? values[0] : rows[0];
+    }
+    exec(sql) {
+        // bun:sqlite .exec() is single-statement only.
+        // Split multi-statement SQL respecting string literals (don't split on ; inside quotes).
+        let current = "";
+        let inString = null;
+        for (let i = 0; i < sql.length; i++) {
+            const ch = sql[i];
+            if (inString) {
+                current += ch;
+                if (ch === inString)
+                    inString = null;
+            }
+            else if (ch === "'" || ch === '"') {
+                current += ch;
+                inString = ch;
+            }
+            else if (ch === ";") {
+                const trimmed = current.trim();
+                if (trimmed)
+                    this.#raw.prepare(trimmed).run();
+                current = "";
+            }
+            else {
+                current += ch;
+            }
+        }
+        const trimmed = current.trim();
+        if (trimmed)
+            this.#raw.prepare(trimmed).run();
+        return this;
+    }
+    prepare(sql) {
+        const stmt = this.#raw.prepare(sql);
+        return {
+            run: (...args) => stmt.run(...args),
+            get: (...args) => {
+                const r = stmt.get(...args);
+                return r === null ? undefined : r;
+            },
+            all: (...args) => stmt.all(...args),
+            iterate: (...args) => stmt.iterate(...args),
+        };
+    }
+    transaction(fn) {
+        return this.#raw.transaction(fn);
+    }
+    close() {
+        this.#raw.close();
+    }
+}
+// ─────────────────────────────────────────────────────────
 // Lazy loader
 // ─────────────────────────────────────────────────────────
 let _Database = null;
 /**
- * Lazy-load better-sqlite3. Only resolves the native module on first call.
- * This allows the MCP server to start instantly even when the native addon
- * is not yet installed (marketplace first-run scenario).
+ * Lazy-load better-sqlite3. Falls back to bun:sqlite via BunSQLiteAdapter
+ * when better-sqlite3 is unavailable (Bun runtime, issue #45).
  */
 export function loadDatabase() {
     if (!_Database) {
         const require = createRequire(import.meta.url);
-        _Database = require("better-sqlite3");
+        try {
+            _Database = require("better-sqlite3");
+        }
+        catch {
+            // better-sqlite3 unavailable (Bun runtime) — wrap bun:sqlite
+            if (!globalThis.Bun) {
+                throw new Error("better-sqlite3 failed to load and Bun runtime not detected");
+            }
+            // Compute module name at runtime to prevent esbuild from resolving at bundle time.
+            // esbuild constant-folds string concat but NOT Array.join().
+            const bunSqliteMod = ["bun", "sqlite"].join(":");
+            const BunDB = require(bunSqliteMod).Database;
+            _Database = function BunDatabaseFactory(path, opts) {
+                const raw = new BunDB(path, {
+                    readonly: opts?.readonly,
+                    create: true,
+                });
+                return new BunSQLiteAdapter(raw);
+            };
+        }
     }
     return _Database;
 }

package/build/server.js

@@ -15,6 +15,7 @@ import { detectRuntimes, getRuntimeSummary, getAvailableLanguages, hasBunRuntime
 import { classifyNonZeroExit } from "./exit-classify.js";
 import { startLifecycleGuard } from "./lifecycle.js";
 import { getWorktreeSuffix } from "./session/db.js";
+import { loadDatabase } from "./db-base.js";
 const __pkg_dir = dirname(fileURLToPath(import.meta.url));
 const VERSION = (() => {
     for (const rel of ["../package.json", "./package.json"]) {
@@ -1318,8 +1319,7 @@ server.registerTool("ctx_stats", {
         const worktreeSuffix = getWorktreeSuffix();
         const sessionDbPath = join(homedir(), ".claude", "context-mode", "sessions", `${dbHash}${worktreeSuffix}.db`);
         if (existsSync(sessionDbPath)) {
-            const require = createRequire(import.meta.url);
-            const Database = require("better-sqlite3");
+            const Database = loadDatabase();
             const sdb = new Database(sessionDbPath, { readonly: true });
             const eventTotal = sdb.prepare("SELECT COUNT(*) as cnt FROM session_events").get();
             const byCategory = sdb.prepare("SELECT category, COUNT(*) as cnt FROM session_events GROUP BY category ORDER BY cnt DESC").all();