membot 0.0.1 → 0.1.1

package/.claude/skills/membot.md

@@ -0,0 +1,137 @@
+---
+name: membot
+description: Persistent, versioned context store for AI agents — ingest, search, read, and write knowledge via the membot CLI or MCP server
+trigger: when the user wants to remember, recall, or search project knowledge, ingest documents into a long-lived store, or surface relevant context for a task
+---
+
+# membot — Persistent Context for Agents
+
+You have access to a long-lived context store via `membot`. Files (markdown, PDFs, DOCX, HTML, URLs, agent notes) are ingested, converted to markdown, chunked, embedded locally, and indexed in DuckDB with hybrid search (semantic + BM25). Every artifact is addressed by a virtual `logical_path`. Every change creates a new immutable version — nothing is overwritten in place.
+
+Use this workflow:
+
+## 1. Discover what's already there
+
+Before ingesting, check whether the knowledge already exists.
+
+```bash
+membot tree                         # synthesised directory tree of logical_paths
+membot ls                           # one row per current file (size, mime, refresh status)
+membot ls docs/                     # filter by prefix
+membot search "<question>"          # hybrid search (semantic + keyword)
+```
+
+`search` is the primary discovery tool — prefer it over scanning files.
+
+## 2. Ingest
+
+```bash
+membot add ./README.md                            # single file
+membot add ./docs                                 # recursive directory walk
+membot add "docs/**/*.md"                         # glob
+membot add https://example.com/spec.pdf           # URL (auto-converted to markdown)
+membot add "inline:Decision: use X because Y"     # literal text
+membot add ./docs --refresh-frequency 24h         # auto-refresh every day
+```
+
+Each entry becomes a new version under its own `logical_path`. PDFs/DOCX/HTML are converted to markdown; images get vision captions; original bytes are kept and reachable via `membot read --bytes`.
+
+## 3. Read
+
+```bash
+membot read <logical_path>                       # current markdown surrogate
+membot read <logical_path> --bytes               # original bytes (base64) — PDF/DOCX/image as ingested
+membot read <logical_path> --version <ts>        # historical snapshot
+membot info <logical_path>                       # metadata only (no content)
+membot versions <logical_path>                   # every version, newest first
+membot diff <logical_path> --a <ts> [--b <ts>]   # unified diff between versions
+```
+
+Defaults to the current (non-tombstoned) version. Pass `--version` only when you need history.
+
+## 4. Write your own notes
+
+Persist agent-authored summaries, decisions, or synthesised context so they survive across conversations:
+
+```bash
+membot write notes/decision-2026-05.md --content "Decided to ..."
+```
+
+Inline writes create a new `(logical_path, version_id)` row just like file ingests — `membot versions` lists them, `membot diff` compares them. To mirror an external doc that should re-fetch over time, use `membot add <url> --refresh-frequency` instead.
+
+## 5. Refresh, rename, delete, prune
+
+```bash
+membot refresh <logical_path>          # re-read source; new version only if bytes changed
+membot refresh                         # refresh all rows whose schedule has elapsed
+membot mv old/path new/path            # rename (history preserved under both)
+membot rm <logical_path>               # tombstone (history still queryable)
+membot prune --before <iso-ts>         # drop non-current versions older than cutoff (irreversible)
+```
+
+Tombstones hide a path from `ls` / `tree` / `search` but `versions` and `read --version <ts>` still work. Pruning is the only way to actually remove data.
+
+## Versioning rules
+
+- Defaults always operate on the current, non-tombstoned version.
+- Pass an explicit `--version <timestamp>` (from `membot versions`) to read or diff history.
+- `membot_add`, refresh-with-changes, `write`, and `mv` each create a new version. The previous version is preserved.
+- Mutating an existing version is not possible — corrections are new versions.
+
+## When to use this skill
+
+- The user asks to remember, recall, save, or look up something across conversations.
+- You need project-specific context (specs, decisions, transcripts, rendered docs) that's larger than fits in the prompt.
+- You need to ingest a document (PDF, DOCX, HTML, URL) and reason over it.
+- You're producing a summary or decision that should survive past this conversation.
+
+## When NOT to use this skill
+
+- Reading a file the user just pointed at — use the regular file-read tool unless they want it persisted.
+- Storing secrets, credentials, or anything that shouldn't sit in `~/.membot/index.duckdb`.
+- Quick scratch state for the current turn — keep that in the conversation.
+
+## MCP server
+
+`membot serve` exposes the same operations as MCP tools (`membot_add`, `membot_search`, etc.) over stdio (default) or HTTP (`--http <port>`). When connected, prefer the MCP tools over shelling out — they return structured `outputSchema` data with `version_id` echoed on every read.
+
+## Available commands
+
+| Command                               | Purpose                                                                        |
+| ------------------------------------- | ------------------------------------------------------------------------------ |
+| `membot add <source>`                 | Ingest file, directory, glob, URL, or `inline:<text>` (one new version each)   |
+| `membot ls [prefix]`                  | List current files (size, mime, refresh status)                                |
+| `membot tree [prefix]`                | Render the synthesised logical-path tree                                       |
+| `membot read <path>`                  | Read current markdown surrogate (or `--bytes` for original)                    |
+| `membot write <path> --content <txt>` | Write inline agent-authored markdown as a new version                          |
+| `membot search <query>`               | Hybrid search (semantic + BM25); add `--include-history` to search older versions |
+| `membot info <path>`                  | Inspect metadata (source, fetcher, refresh schedule, digests) without content  |
+| `membot versions <path>`              | List every version newest-first with version_id and change notes               |
+| `membot diff <path> --a <ts>`         | Unified diff between two versions                                              |
+| `membot mv <old> <new>`               | Rename a logical_path (history preserved)                                      |
+| `membot rm <path>`                    | Tombstone a logical_path (history still queryable)                             |
+| `membot refresh [path]`               | Re-read source; create new version only if bytes changed                       |
+| `membot prune --before <ts>`          | Permanently drop non-current versions older than cutoff (irreversible)         |
+| `membot serve`                        | Start MCP server (stdio default, `--http <port>` for HTTP)                     |
+| `membot reindex`                      | Rebuild the FTS keyword index over current chunks                              |
+
+## Output formats
+
+- TTY → spinners, colors, tables. `--no-color` disables ANSI.
+- Piped, `--json`, `CI=true`, or `NO_COLOR` → JSON to stdout, structured logs to stderr, no ANSI bytes.
+- Use `--json` when parsing output programmatically (it's automatic when piped, but explicit is safer).
+- Use `--verbose` if a command fails unexpectedly.
+
+## Troubleshooting
+
+- **"ingest failed: unsupported mime"** → Add a converter or pass `--bytes` to keep the original; LLM-fallback only runs when `ANTHROPIC_API_KEY` is set.
+- **"refresh failed: auth"** → The original fetch used an authenticated mcpx tool; re-auth via `mcpx auth <server>`.
+- **Search returns nothing** → Confirm the file ingested with `membot info <path>`; if needed, run `membot reindex` to rebuild the FTS keyword index.
+- **Stale results after manual DB edits** → `membot reindex`.
+- **Two paths point at the same content** → `membot mv` doesn't merge; tombstone one with `membot rm`.
+
+## Configuration
+
+- Data lives in `~/.membot/index.duckdb` (override via `MEMBOT_HOME`).
+- Optional `ANTHROPIC_API_KEY` enables LLM fallback for messy/binary input. Without it, conversion degrades to deterministic native output.
+- Config file: `~/.membot/config.json` (see `membot --help` for the global flags).

package/.cursor/rules/membot.mdc

@@ -0,0 +1,137 @@
+---
+description: Persistent, versioned context store for AI agents — ingest, search, read, and write knowledge via the membot CLI or MCP server
+globs:
+alwaysApply: true
+---
+
+# membot — Persistent Context for Agents
+
+You have access to a long-lived context store via `membot`. Files (markdown, PDFs, DOCX, HTML, URLs, agent notes) are ingested, converted to markdown, chunked, embedded locally, and indexed in DuckDB with hybrid search (semantic + BM25). Every artifact is addressed by a virtual `logical_path`. Every change creates a new immutable version — nothing is overwritten in place.
+
+Use this workflow:
+
+## 1. Discover what's already there
+
+Before ingesting, check whether the knowledge already exists.
+
+```bash
+membot tree                         # synthesised directory tree of logical_paths
+membot ls                           # one row per current file (size, mime, refresh status)
+membot ls docs/                     # filter by prefix
+membot search "<question>"          # hybrid search (semantic + keyword)
+```
+
+`search` is the primary discovery tool — prefer it over scanning files.
+
+## 2. Ingest
+
+```bash
+membot add ./README.md                            # single file
+membot add ./docs                                 # recursive directory walk
+membot add "docs/**/*.md"                         # glob
+membot add https://example.com/spec.pdf           # URL (auto-converted to markdown)
+membot add "inline:Decision: use X because Y"     # literal text
+membot add ./docs --refresh-frequency 24h         # auto-refresh every day
+```
+
+Each entry becomes a new version under its own `logical_path`. PDFs/DOCX/HTML are converted to markdown; images get vision captions; original bytes are kept and reachable via `membot read --bytes`.
+
+## 3. Read
+
+```bash
+membot read <logical_path>                       # current markdown surrogate
+membot read <logical_path> --bytes               # original bytes (base64) — PDF/DOCX/image as ingested
+membot read <logical_path> --version <ts>        # historical snapshot
+membot info <logical_path>                       # metadata only (no content)
+membot versions <logical_path>                   # every version, newest first
+membot diff <logical_path> --a <ts> [--b <ts>]   # unified diff between versions
+```
+
+Defaults to the current (non-tombstoned) version. Pass `--version` only when you need history.
+
+## 4. Write your own notes
+
+Persist agent-authored summaries, decisions, or synthesised context so they survive across conversations:
+
+```bash
+membot write notes/decision-2026-05.md --content "Decided to ..."
+```
+
+Inline writes create a new `(logical_path, version_id)` row just like file ingests — `membot versions` lists them, `membot diff` compares them. To mirror an external doc that should re-fetch over time, use `membot add <url> --refresh-frequency` instead.
+
+## 5. Refresh, rename, delete, prune
+
+```bash
+membot refresh <logical_path>          # re-read source; new version only if bytes changed
+membot refresh                         # refresh all rows whose schedule has elapsed
+membot mv old/path new/path            # rename (history preserved under both)
+membot rm <logical_path>               # tombstone (history still queryable)
+membot prune --before <iso-ts>         # drop non-current versions older than cutoff (irreversible)
+```
+
+Tombstones hide a path from `ls` / `tree` / `search` but `versions` and `read --version <ts>` still work. Pruning is the only way to actually remove data.
+
+## Versioning rules
+
+- Defaults always operate on the current, non-tombstoned version.
+- Pass an explicit `--version <timestamp>` (from `membot versions`) to read or diff history.
+- `membot_add`, refresh-with-changes, `write`, and `mv` each create a new version. The previous version is preserved.
+- Mutating an existing version is not possible — corrections are new versions.
+
+## When to use this rule
+
+- The user asks to remember, recall, save, or look up something across conversations.
+- You need project-specific context (specs, decisions, transcripts, rendered docs) that's larger than fits in the prompt.
+- You need to ingest a document (PDF, DOCX, HTML, URL) and reason over it.
+- You're producing a summary or decision that should survive past this conversation.
+
+## When NOT to use this rule
+
+- Reading a file the user just pointed at — use the regular file-read tool unless they want it persisted.
+- Storing secrets, credentials, or anything that shouldn't sit in `~/.membot/index.duckdb`.
+- Quick scratch state for the current turn — keep that in the conversation.
+
+## MCP server
+
+`membot serve` exposes the same operations as MCP tools (`membot_add`, `membot_search`, etc.) over stdio (default) or HTTP (`--http <port>`). When connected, prefer the MCP tools over shelling out — they return structured `outputSchema` data with `version_id` echoed on every read.
+
+## Available commands
+
+| Command                               | Purpose                                                                        |
+| ------------------------------------- | ------------------------------------------------------------------------------ |
+| `membot add <source>`                 | Ingest file, directory, glob, URL, or `inline:<text>` (one new version each)   |
+| `membot ls [prefix]`                  | List current files (size, mime, refresh status)                                |
+| `membot tree [prefix]`                | Render the synthesised logical-path tree                                       |
+| `membot read <path>`                  | Read current markdown surrogate (or `--bytes` for original)                    |
+| `membot write <path> --content <txt>` | Write inline agent-authored markdown as a new version                          |
+| `membot search <query>`               | Hybrid search (semantic + BM25); add `--include-history` to search older versions |
+| `membot info <path>`                  | Inspect metadata (source, fetcher, refresh schedule, digests) without content  |
+| `membot versions <path>`              | List every version newest-first with version_id and change notes               |
+| `membot diff <path> --a <ts>`         | Unified diff between two versions                                              |
+| `membot mv <old> <new>`               | Rename a logical_path (history preserved)                                      |
+| `membot rm <path>`                    | Tombstone a logical_path (history still queryable)                             |
+| `membot refresh [path]`               | Re-read source; create new version only if bytes changed                       |
+| `membot prune --before <ts>`          | Permanently drop non-current versions older than cutoff (irreversible)         |
+| `membot serve`                        | Start MCP server (stdio default, `--http <port>` for HTTP)                     |
+| `membot reindex`                      | Rebuild the FTS keyword index over current chunks                              |
+
+## Output formats
+
+- TTY → spinners, colors, tables. `--no-color` disables ANSI.
+- Piped, `--json`, `CI=true`, or `NO_COLOR` → JSON to stdout, structured logs to stderr, no ANSI bytes.
+- Use `--json` when parsing output programmatically (it's automatic when piped, but explicit is safer).
+- Use `--verbose` if a command fails unexpectedly.
+
+## Troubleshooting
+
+- **"ingest failed: unsupported mime"** → Add a converter or pass `--bytes` to keep the original; LLM-fallback only runs when `ANTHROPIC_API_KEY` is set.
+- **"refresh failed: auth"** → The original fetch used an authenticated mcpx tool; re-auth via `mcpx auth <server>`.
+- **Search returns nothing** → Confirm the file ingested with `membot info <path>`; if needed, run `membot reindex` to rebuild the FTS keyword index.
+- **Stale results after manual DB edits** → `membot reindex`.
+- **Two paths point at the same content** → `membot mv` doesn't merge; tombstone one with `membot rm`.
+
+## Configuration
+
+- Data lives in `~/.membot/index.duckdb` (override via `MEMBOT_HOME`).
+- Optional `ANTHROPIC_API_KEY` enables LLM fallback for messy/binary input. Without it, conversion degrades to deterministic native output.
+- Config file: `~/.membot/config.json` (see `membot --help` for the global flags).

package/README.md

@@ -0,0 +1,131 @@
+# membot
+
+> Versioned context store with hybrid search for AI agents. Stdio + HTTP MCP server and CLI.
+
+[![npm](https://img.shields.io/npm/v/membot.svg)](https://www.npmjs.com/package/membot)
+[![license](https://img.shields.io/npm/l/membot.svg)](./LICENSE)
+
+`membot` is a single-binary CLI and MCP server that gives AI agents a persistent, versioned, searchable context store. Files (markdown, PDFs, DOCX, HTML, URLs, agent-authored notes) are ingested, converted to markdown, chunked, embedded **locally** with `@huggingface/transformers` (WASM, no cloud calls), and indexed in DuckDB with hybrid search (semantic vector + BM25). Every change creates a new version — nothing is overwritten in place.
+
+- **Local everything** — embeddings run on your machine; data lives in `~/.membot/index.duckdb`.
+- **One mental model** — every artifact (markdown, PDF, image, audio) becomes a markdown surrogate that flows through the same chunk → embed → search pipeline.
+- **Append-only versioning** — every ingest, refresh, or write creates a new `(logical_path, version_id)` row. History is queryable; nothing is mutated.
+- **Two surfaces, one source of truth** — every operation is exposed identically as a CLI subcommand and an MCP tool. The agent sees `membot_search`; you see `membot search`.
+
+## Install
+
+```bash
+# macOS / Linux — pre-built binary
+curl -fsSL https://raw.githubusercontent.com/evantahler/membot/main/install.sh | bash
+
+# Windows — PowerShell
+iwr -useb https://raw.githubusercontent.com/evantahler/membot/main/install.ps1 | iex
+
+# From npm (requires Bun or Node)
+bun add -g membot
+# or
+npm install -g membot
+```
+
+## Quick start
+
+```bash
+membot add ./docs                        # ingest a directory recursively
+membot add https://example.com/spec.pdf  # ingest a URL (auto-converted to markdown)
+membot ls                                # list current files
+membot search "how does refresh work?"   # hybrid search
+membot read docs/refresh.md              # read the markdown surrogate
+membot serve                             # expose the same operations as MCP tools (stdio)
+```
+
+## Use with Claude Code or Cursor
+
+`membot skill install` drops the agent skill into the right place so Claude Code or Cursor know **when** to call `membot`.
+
+```bash
+membot skill install --claude              # writes ./.claude/skills/membot.md (project)
+membot skill install --cursor              # writes ./.cursor/rules/membot.mdc (project)
+membot skill install --claude --global     # writes ~/.claude/skills/membot.md
+membot skill install --claude --cursor -f  # both, overwrite if present
+```
+
+The skill files describe the discover → ingest → search → read → write workflow and the versioning rules. You can re-run with `--force` to refresh after upgrading membot.
+
+## Commands
+
+| Command                         | Description                                                                       |
+| ------------------------------- | --------------------------------------------------------------------------------- |
+| `membot add <source>`           | Ingest a file, directory, glob, URL, or `inline:<text>`. Each match → new version |
+| `membot ls [prefix]`            | List current files (size, mime, refresh status)                                   |
+| `membot tree [prefix]`          | Render the synthesised logical-path tree                                          |
+| `membot read <path>`            | Read the markdown surrogate (or `--bytes` for original bytes, base64)             |
+| `membot search <query>`         | Hybrid search (semantic + BM25); `--include-history` searches older versions      |
+| `membot info <path>`            | Inspect metadata (source, fetcher, schedule, digests) without content             |
+| `membot versions <path>`        | List every version newest-first                                                   |
+| `membot diff <path> <a> [b]`    | Unified diff between two versions                                                 |
+| `membot write <path>`           | Write inline agent-authored markdown as a new version                             |
+| `membot mv <from> <to>`         | Rename a logical_path (history preserved under both)                              |
+| `membot rm <path>`              | Tombstone a logical_path (history still queryable)                                |
+| `membot refresh [path]`         | Re-read source; new version only if bytes changed                                 |
+| `membot prune --before <ts>`    | Permanently drop non-current versions older than cutoff (irreversible)            |
+| `membot serve`                  | Run the MCP server (stdio default; `--http <port>` for HTTP)                      |
+| `membot reindex`                | Rebuild the FTS keyword index over current chunks                                 |
+| `membot mcpx <subcommand>`      | Forward to the bundled `mcpx` CLI for managing remote MCP servers                 |
+| `membot skill install`          | Install the Claude Code / Cursor agent skill                                      |
+
+Run `membot <command> --help` for full flags and arguments. Every command produces JSON when piped, when `--json` is set, or when `CI=true`.
+
+## MCP server
+
+`membot serve` exposes every operation as an MCP tool. Stdio is the default; pass `--http <port>` for streamable HTTP.
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "membot": {
+      "command": "membot",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+**Streamable HTTP** (any MCP client that speaks HTTP):
+
+```bash
+membot serve --http 3000
+# tool endpoint: http://localhost:3000/mcp
+```
+
+Add `--watch` (and optional `--tick <sec>`) to also run the refresh daemon, which re-reads any file whose `refresh_frequency` has elapsed.
+
+## Configuration
+
+- **Data directory:** `~/.membot/` (override with `MEMBOT_HOME=/path` or `--config <path>`).
+  - `~/.membot/index.duckdb` — all content, blobs, chunks, embeddings, and metadata.
+  - `~/.membot/models/` — cached embedding model weights (`Xenova/bge-small-en-v1.5`, 384-dim).
+  - `~/.membot/logs/` — daemon logs when running `serve --watch`.
+- **Config file:** `~/.membot/config.json` (optional; defaults are sane).
+- **Environment variables:**
+  - `ANTHROPIC_API_KEY` — optional. Enables LLM fallback for messy / scanned input (vision captions for images, last-resort markdown conversion). Without it, the pipeline degrades to deterministic native conversion.
+  - `MEMBOT_HOME` — override the data directory.
+  - `NO_COLOR`, `CI`, `FORCE_COLOR` — standard output controls.
+
+## Development
+
+```bash
+bun install
+bun run dev <args>       # run from source
+bun test                 # full test suite (real ephemeral DuckDB per test)
+bun run lint             # biome + tsc
+bun run format           # biome --write
+bun run build            # compile a standalone binary into dist/membot
+```
+
+Architecture, design constraints, and reference projects are documented in [`docs/plan.md`](./docs/plan.md) and [`CLAUDE.md`](./CLAUDE.md).
+
+## License
+
+MIT © Evan Tahler

package/package.json

@@ -1,26 +1,85 @@
 {
-  "name": "membot",
-  "version": "0.0.1",
-  "description": "Versioned context store with hybrid search for AI agents. Stdio + HTTP MCP server and CLI.",
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "context",
-    "memory",
-    "agent",
-    "rag",
-    "embeddings",
-    "duckdb",
-    "bun"
-  ],
-  "license": "MIT",
-  "author": "Evan Tahler <evan@arcade.dev>",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/evantahler/membot.git"
-  },
-  "homepage": "https://github.com/evantahler/membot",
-  "bugs": {
-    "url": "https://github.com/evantahler/membot/issues"
-  }
+	"name": "membot",
+	"version": "0.1.1",
+	"description": "Versioned context store with hybrid search for AI agents. Stdio + HTTP MCP server and CLI.",
+	"type": "module",
+	"exports": {
+		".": "./src/sdk.ts",
+		"./cli": "./src/cli.ts"
+	},
+	"main": "./src/sdk.ts",
+	"types": "./src/sdk.ts",
+	"bin": {
+		"membot": "./src/cli.ts"
+	},
+	"files": [
+		"src",
+		"patches",
+		"scripts",
+		".claude",
+		".cursor",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"dev": "bun run src/cli.ts",
+		"test": "bun test",
+		"lint": "biome ci . && tsc --noEmit",
+		"format": "biome check --write .",
+		"prebuild": "bash scripts/apply-transformers-patch.sh",
+		"build": "bun build --compile --minify --sourcemap --external '@duckdb/*' ./src/cli.ts --outfile dist/membot"
+	},
+	"keywords": [
+		"mcp",
+		"model-context-protocol",
+		"context",
+		"memory",
+		"agent",
+		"rag",
+		"embeddings",
+		"duckdb",
+		"bun"
+	],
+	"license": "MIT",
+	"author": "Evan Tahler <evan@evantahler.com>",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/evantahler/membot.git"
+	},
+	"homepage": "https://github.com/evantahler/membot",
+	"bugs": {
+		"url": "https://github.com/evantahler/membot/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@anthropic-ai/sdk": "^0.32.0",
+		"@duckdb/node-api": "1.5.2-r.1",
+		"@evantahler/mcpx": "^0.21.4",
+		"@huggingface/transformers": "^4.2.0",
+		"@modelcontextprotocol/sdk": "^1.29.0",
+		"ansis": "^4.2.0",
+		"commander": "^14.0.3",
+		"gray-matter": "^4.0.3",
+		"mammoth": "^1.8.0",
+		"nanospinner": "^1.2.2",
+		"onnxruntime-web": "1.26.0-dev.20260416-b7804b056c",
+		"picomatch": "^4.0.4",
+		"@types/picomatch": "^4.0.3",
+		"tesseract.js": "^5.1.0",
+		"turndown": "^7.2.0",
+		"@types/turndown": "^5.0.5",
+		"unpdf": "^0.12.0",
+		"zod": "^4.0.0",
+		"zod-to-json-schema": "^3.23.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.4.14",
+		"@types/bun": "latest",
+		"typescript": "^6"
+	},
+	"peerDependencies": {
+		"typescript": "^6"
+	}
 }

package/patches/@huggingface%2Ftransformers@4.2.0.patch

@@ -0,0 +1,137 @@
+diff --git a/dist/transformers.node.mjs b/dist/transformers.node.mjs
+index bacb354fe1b898d4c535a39f5ef1ba5c6a463d75..0ab58f60460236259f9eba88447313f8661cc0ca 100644
+--- a/dist/transformers.node.mjs
++++ b/dist/transformers.node.mjs
+@@ -7542,7 +7542,10 @@ var uint16_to_float32 = /* @__PURE__ */ (function() {
+ })();
+ 
+ // src/backends/onnx.js
+-import * as ONNX_NODE from "onnxruntime-node";
++// PATCHED (mcpx): static `import 'onnxruntime-node'` makes Bun --compile bundle
++// the native binding which then fails to dlopen libonnxruntime at runtime.
++// We never want the native bindings — onnxruntime-web (WASM) runs fine.
++var ONNX_NODE = void 0;
+ 
+ // ../../node_modules/.pnpm/onnxruntime-web@1.26.0-dev.20260416-b7804b056c/node_modules/onnxruntime-web/dist/ort.webgpu.bundle.min.mjs
+ var ort_webgpu_bundle_min_exports = {};
+@@ -11551,23 +11554,12 @@ var ORT_SYMBOL = /* @__PURE__ */ Symbol.for("onnxruntime");
+ if (ORT_SYMBOL in globalThis) {
+   ONNX = globalThis[ORT_SYMBOL];
+ } else if (apis.IS_NODE_ENV) {
+-  ONNX = ONNX_NODE;
+-  switch (process.platform) {
+-    case "win32":
+-      supportedDevices.push("dml");
+-      break;
+-    case "linux":
+-      if (process.arch === "x64") {
+-        supportedDevices.push("cuda");
+-      }
+-      break;
+-    case "darwin":
+-      supportedDevices.push("coreml");
+-      break;
+-  }
+-  supportedDevices.push("webgpu");
+-  supportedDevices.push("cpu");
+-  defaultDevices = ["cpu"];
++  // PATCHED (mcpx): force the WASM backend in node-like envs so onnxruntime-node
++  // native bindings are never loaded (they can't be bundled into the Bun
++  // --compile single binary).
++  ONNX = ort_webgpu_bundle_min_exports;
++  supportedDevices.push("wasm");
++  defaultDevices = ["wasm"];
+ } else {
+   ONNX = ort_webgpu_bundle_min_exports;
+   if (apis.IS_WEBNN_AVAILABLE) {
+@@ -17738,7 +17730,14 @@ var CohereAsrProcessor = class extends Processor {
+ };
+ 
+ // src/utils/image.js
+-import sharp from "sharp";
++// PATCHED (mcpx): sharp has native bindings that can't be bundled into a
++// Bun --compile binary. We don't need image processing for text embeddings;
++// stub sharp with a function that throws lazily if image processing is ever
++// actually invoked. Truthy so the `else if (sharp)` branch below initializes
++// loadImageFunction normally.
++var sharp = function sharpStub() {
++  throw new Error("Image processing (sharp) is not available in this build.");
++};
+ var createCanvasFunction;
+ var ImageDataClass;
+ var loadImageFunction;
+@@ -22328,11 +22327,16 @@ function getExternalDataChunkNames(fullName, numChunks) {
+ async function getCoreModelFile(pretrained_model_name_or_path, fileName, options, suffix) {
+   const baseName = `${fileName}${suffix}.onnx`;
+   const fullPath = `${options.subfolder ?? ""}/${baseName}`;
+-  return await getModelFile(pretrained_model_name_or_path, fullPath, true, options, apis.IS_NODE_ENV);
++  // PATCHED (mcpx): always return the model bytes (buffer) instead of a path.
++  // Our patched onnxruntime backend is the bundled webgpu/web build, which
++  // can't read paths via node:fs and would try to `fetch()` a bare path,
++  // failing with `ERR_INVALID_URL`. Returning the buffer skips the fetch.
++  return await getModelFile(pretrained_model_name_or_path, fullPath, true, options, false);
+ }
+ async function getModelDataFiles(pretrained_model_name_or_path, fileName, suffix, options, use_external_data_format, session_options = {}) {
+   const baseName = `${fileName}${suffix}.onnx`;
+-  const return_path = apis.IS_NODE_ENV;
++  // PATCHED (mcpx): see getCoreModelFile patch above — return buffers, not paths.
++  const return_path = false;
+   let externalDataPromises = [];
+   const num_chunks = resolveExternalDataFormat(use_external_data_format, baseName, fileName);
+   if (num_chunks > 0) {
+diff --git a/src/backends/onnx.js b/src/backends/onnx.js
+index 13b1a748272d03aa062950ff585c1a2277ba96c9..9863c46653618091593b6428a8c16622186318d6 100644
+--- a/src/backends/onnx.js
++++ b/src/backends/onnx.js
+@@ -20,7 +20,10 @@ import { env, apis, LogLevel } from '../env.js';
+ 
+ // NOTE: Import order matters here. We need to import `onnxruntime-node` before `onnxruntime-web`.
+ // In either case, we select the default export if it exists, otherwise we use the named export.
+-import * as ONNX_NODE from 'onnxruntime-node';
++// PATCHED (mcpx): the static `import 'onnxruntime-node'` segfaults under Bun
++// (oven-sh/bun#26081). We never want the native bindings — `onnxruntime-web` (WASM) runs
++// fine on Bun + Node + browsers. The IS_NODE_ENV branch below is rerouted to ONNX_WEB.
++const ONNX_NODE = undefined;
+ import * as ONNX_WEB from 'onnxruntime-web/webgpu';
+ import { loadWasmBinary, loadWasmFactory } from './utils/cacheWasm.js';
+ import { isBlobURL, toAbsoluteURL } from '../utils/hub/utils.js';
+@@ -106,34 +109,11 @@ if (ORT_SYMBOL in globalThis) {
+     // If the JS runtime exposes their own ONNX runtime, use it
+     ONNX = globalThis[ORT_SYMBOL];
+ } else if (apis.IS_NODE_ENV) {
+-    ONNX = ONNX_NODE;
+-
+-    // Updated as of ONNX Runtime 1.23.0-dev.20250612-70f14d7670
+-    // The following table lists the supported versions of ONNX Runtime Node.js binding provided with pre-built binaries.
+-    // | EPs/Platforms         | Windows x64        | Windows arm64      | Linux x64          | Linux arm64        | MacOS x64          | MacOS arm64        |
+-    // | --------------------- | ------------------ | ------------------ | ------------------ | ------------------ | ------------------ | ------------------ |
+-    // | CPU                   | ✔️                  | ✔️                  | ✔️                  | ✔️                  | ✔️                  | ✔️                  |
+-    // | WebGPU (experimental) | ✔️                  | ✔️                  | ✔️                  | ❌                  | ✔️                  | ✔️                  |
+-    // | DirectML              | ✔️                  | ✔️                  | ❌                  | ❌                  | ❌                  | ❌                  |
+-    // | CUDA                  | ❌                  | ❌                  | ✔️ (CUDA v12)       | ❌                  | ❌                  | ❌                  |
+-    // | CoreML                | ❌                  | ❌                  | ❌                  | ❌                  | ✔️                  | ✔️                  |
+-    switch (process.platform) {
+-        case 'win32': // Windows x64 and Windows arm64
+-            supportedDevices.push('dml');
+-            break;
+-        case 'linux': // Linux x64 and Linux arm64
+-            if (process.arch === 'x64') {
+-                supportedDevices.push('cuda');
+-            }
+-            break;
+-        case 'darwin': // MacOS x64 and MacOS arm64
+-            supportedDevices.push('coreml');
+-            break;
+-    }
+-
+-    supportedDevices.push('webgpu');
+-    supportedDevices.push('cpu');
+-    defaultDevices = ['cpu'];
++    // PATCHED (mcpx): force the WASM backend in node-like envs to avoid
++    // loading onnxruntime-node native bindings (segfaults under Bun).
++    ONNX = ONNX_WEB;
++    supportedDevices.push('wasm');
++    defaultDevices = ['wasm'];
+ } else {
+     ONNX = ONNX_WEB;
+