moflo 4.8.86 → 4.8.87-rc.2

package/.claude/guidance/shipped/moflo-core-guidance.md

@@ -644,7 +644,7 @@ All code changes MUST work on Windows, macOS, and Linux. Follow these rules:
 | Low search quality | Guidance docs missing `**Purpose:**` lines or generic headings | Follow guidance optimization rules in `guidance-memory-strategy.md` |
 | Session start slow | All three indexers running | Set `auto_index.code_map: false` in `moflo.yaml` if code map not needed |
 | Status line not showing | `statusline.cjs` error or `status_line.enabled: false` | Run `node .claude/helpers/statusline.cjs` to test, check `moflo.yaml` |
-| Embeddings falling back to hash | Transformers.js not available | Install `@xenova/transformers` — moflo includes it but some environments strip it |
+| Embeddings fail on first run (offline / air-gapped) | `fastembed` model cache missing | Pre-populate `~/.cache/fastembed` or set `FASTEMBED_CACHE` to a pre-baked cache dir — see `docs/modules/embeddings.md` "Sandbox & air-gapped first-run" |
 | `flo` command not found | Not in PATH | Use `npx flo` or `node node_modules/moflo/bin/index-guidance.mjs` |
 | Bundled guidance not indexed | Running inside moflo repo (same dir) | Bundled guidance only indexes when installed as a dependency in a different project |
 

package/.claude/guidance/shipped/moflo-memory-strategy.md

@@ -105,42 +105,28 @@ ASCII boxes, excessive emoji, rhetorical questions, and motivational text all wa
 
 ## Embedding Strategy
 
-### Embedding Models
+### Embedding Model
 
-| Model | Quality | Speed | When Used |
-|-------|---------|-------|-----------|
-| `Xenova/all-MiniLM-L6-v2` | High (true semantic) | ~3s for 1000 entries | Primary — `build-embeddings.mjs` uses this |
-| `domain-aware-hash-v1` | Good (domain clustering) | <1s for 1000 entries | Fallback when Transformers.js unavailable |
+| Model | Runtime | Speed | Notes |
+|-------|---------|-------|-------|
+| `fast-all-MiniLM-L6-v2` | `fastembed` (native ONNX + Rust tokenizer) | ~3s for 1000 entries | The only supported model — neural embeddings are mandatory (ADR-EMB-001) |
 
-**Neural embeddings (Xenova/all-MiniLM-L6-v2):**
-- Uses `@xenova/transformers` with ONNX WASM runtime
+**Neural embeddings (fast-all-MiniLM-L6-v2):**
+- Uses the `fastembed` npm package (Qdrant's embeddings-only ONNX client)
 - 384-dimensional vectors, L2-normalized
 - True semantic understanding — "soft delete" matches "mark as deleted" without keyword overlap
-- Loaded lazily on first use, cached for subsequent queries
+- Model auto-downloads to `~/.cache/fastembed` on first use; cached for subsequent queries
+- For offline / air-gapped / sandboxed runs, pre-populate the cache or set `FASTEMBED_CACHE` — see `docs/modules/embeddings.md` "Sandbox & air-gapped first-run"
 
-**Domain-aware hash embeddings (fallback):**
-- Custom SimHash-style algorithm with 12 domain clusters
-- Multi-position hashing with bigram/trigram features
-- Good at keyword-level matching but misses semantic paraphrases
-- No external dependencies — always available
+**Legacy-compatible model names:** Entries embedded by earlier moflo versions may be tagged `Xenova/all-MiniLM-L6-v2` or `onnx`. These share the same vector space as `fast-all-MiniLM-L6-v2`, so search treats them as compatible (`semantic-search.mjs` `COMPATIBLE_MODELS`).
+
+**No hash fallback.** Epic #527 removed every hash-embedding path. If the `fastembed` model cannot load, memory operations fail loudly rather than silently degrading to FNV-1a pseudo-vectors. See [ADR-EMB-001](../../../src/modules/embeddings/docs/adrs/ADR-EMB-001-neural-embeddings-mandatory.md).
 
 ### The Embedding Alignment Problem
 
 **Critical rule:** Query embeddings MUST match stored embeddings. Computing cosine similarity between vectors from different models produces meaningless scores.
 
-Both the search scripts and the MCP memory tools auto-detect the stored embedding model and generate matching query vectors. Search also filters out entries with mismatched `embedding_model`.
-
-### Domain Cluster Tuning
-
-The hash fallback's domain clusters can be extended with project-specific terms:
-
-| Cluster | Example Terms |
-|---------|--------------|
-| `database` | your ORM, database engine, schema terms |
-| `frontend` | UI framework, component library terms |
-| `backend` | DI container, API framework terms |
-| `testing` | test framework, assertion library terms |
-| `security` | auth system, permission model terms |
+Both the search scripts and the MCP memory tools use `fastembed` for query vectors and filter stored entries by `embedding_model` (via the legacy-compatible alias list above), so a mixed-version database remains coherent.
 
 ---
 

package/README.md

@@ -28,10 +28,10 @@ To verify everything is running, ask Claude to run `flo doctor` with full diagno
 MoFlo makes deliberate choices so you don't have to:
 
 - **Fully self-contained** — No external services, no cloud dependencies, no API keys. Everything runs locally on your machine.
-- **Minimal dependencies** — 4 runtime dependencies (`js-yaml`, `semver`, `sql.js`, `valibot`). The upstream Ruflo/Claude Flow packages pull in multiple internal scoped packages (`@claude-flow/cli`, `@claude-flow/mcp`, `@claude-flow/shared`) plus native crypto libraries. MoFlo consolidates everything into a single package with zero native bindings.
+- **Minimal dependencies** — small runtime dep set (`fastembed` for embeddings, plus `js-yaml`, `semver`, `sql.js`, `valibot`). The upstream Ruflo/Claude Flow packages pull in multiple internal scoped packages (`@claude-flow/cli`, `@claude-flow/mcp`, `@claude-flow/shared`) plus native crypto libraries. MoFlo consolidates everything into a single package with no native compilation on install — `fastembed`'s `onnxruntime-node` ships prebuilt binaries, and `sql.js` is WASM.
 - **Node.js runtime** — Targets Node.js specifically. All scripts, hooks, and tooling are JavaScript/TypeScript. No Python, no Rust binaries, no native compilation.
 - **sql.js (WASM)** — The memory database uses sql.js, a pure WebAssembly build of SQLite. No native `better-sqlite3` bindings to compile, no platform-specific build steps. Works identically on Windows, macOS, and Linux.
-- **Simplified embeddings pipeline** — 384-dimensional neural embeddings via Transformers.js (MiniLM-L6-v2, WASM). Same model and precision as the upstream multi-provider pipeline, but simpler — two scripts instead of an abstraction layer. Runs locally, no API calls.
+- **Neural embeddings by default** — 384-dimensional embeddings via [`fastembed`](https://www.npmjs.com/package/fastembed) (Qdrant's embeddings-only ONNX client) with `all-MiniLM-L6-v2`. No hash fallback, no peer-optional setup, no install prompts — real semantic search works out of the box. Install footprint: **~60–100 MB** post-prune (a `postinstall` script trims `onnxruntime-node` to the current platform's binaries and strips GPU-only provider libraries that fastembed never loads; unpruned it would be ~430 MB on Linux). The prune is scoped to ORT copies moflo actually owns and never touches foreign installs (e.g. an Electron cross-compile packager pulling its own ORT); set `MOFLO_NO_PRUNE=1` to disable pruning entirely, or `ONNXRUNTIME_NODE_INSTALL_CUDA=true` to keep the prune but re-enable the CUDA GPU provider. For context, the upstream Ruflo default install is ~1.1 GB. See [ADR-EMB-001](src/modules/embeddings/docs/adrs/ADR-EMB-001-neural-embeddings-mandatory.md).
 - **Full learning stack wired up OOTB** — The following are all configured and functional from `flo init`, no manual setup:
   - **SONA** (Self-Optimizing Neural Architecture) — learns from task trajectories via pure TypeScript SONA implementation in `@moflo/neural`
   - **MicroLoRA** — rank-2 LoRA weight adaptations at ~1µs per adapt via pure TypeScript MicroLoRA in `@moflo/neural`