pantheon-opencode 1.5.0 → 1.5.1

package/CHANGELOG.md

@@ -18,6 +18,28 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## ✅ Closed Issues
 
+## [v1.5.1] - 2026-09-22
+
+## 🐞 Fixed
+- **agents** — declare explicit read: allow for zeus
+- **ci** — drop fastembed from CI, keep pytest collection green (#163)
+- **plugin** — detect registered-plugin version drift after pantheon_delegate removal (#169)
+- **config** — correct node floor and warn on unsupported runtime (#168)
+- **mcp** — degrade gracefully when fastembed import fails (#165)
+- **mcp** — drop dead toon_codec module from published package (#167)
+- **tui** — remove dead pantheon_delegate refs after v1.5.0 V1 removal (#166)
+- **mnemosyne** — grant scoped write to memory-bank and deepwork paths (#164)
+
+## ✅ Closed Issues
+- #94 - drop fastembed from CI, keep pytest collection green (#163)
+- #158 - detect registered-plugin version drift after pantheon_delegate removal (#169)
+- #114 - correct node floor and warn on unsupported runtime (#168)
+- #160 - correct node floor and warn on unsupported runtime (#168)
+- #159 - degrade gracefully when fastembed import fails (#165)
+- #162 - drop dead toon_codec module from published package (#167)
+- #161 - remove dead pantheon_delegate refs after v1.5.0 V1 removal (#166)
+- #111 - grant scoped write to memory-bank and deepwork paths (#164)
+
 ## [v1.5.0] - 2026-09-16
 
 ### 🆕 What's New

package/README.md

@@ -30,7 +30,15 @@ way to plan work, make progress, check results, and keep useful project context.
 
 ## Start in 2 minutes
 
-Requirements: [OpenCode 1.18.4+](https://opencode.ai/docs/) and Node.js 22+.
+Requirements: [OpenCode 1.18.4+](https://opencode.ai/docs/) and Node.js
+22.22.2+ (or 24.15.0+ / 26+).
+
+Pantheon declares `engines.node` as `^22.22.2 || ^24.15.0 || >=26.0.0`. The
+floor reflects what the dependency tree actually needs — the transitive
+`ini@7` rejects earlier 22.x/24.x builds with `EBADENGINE` — and odd-numbered
+Node releases (23, 25) are out of range. The `pantheon_cost` tool also needs
+`node:sqlite`, which requires Node >= 22.5; `doctor` warns when the running
+runtime cannot load it.
 
 From the project where you want to use Pantheon:
 
@@ -246,7 +254,12 @@ Two freshness guarantees back it up:
   re-run `init` just for file copies.
 - **Drift detection** — the installer stamps the installed version in
   `.pantheon/install-state.json` and `doctor` warns when the package is newer
-  than the last sync, pointing at `update`.
+  than the last sync, pointing at `update`. `doctor` also detects **plugin
+  version drift** (issue #158): when `opencode.json` registers a plugin path
+  inside a `node_modules/pantheon-opencode` copy whose `package.json` version
+  differs from the running package, it warns that the registered tool surface
+  is stale. Re-running `init`/`update` realigns the registration onto the
+  current package.
 
 `init` also gained `--components agents,skills,...` (narrow install),
 `--clean` (alias of `--force`), `--opencode-version auto`, atomic config
@@ -256,6 +269,42 @@ the install completes but MCP entries are omitted (with a warning) instead of
 pointing at a broken interpreter. Installer messages auto-detect pt-BR via
 `LANG`/`LC_ALL`.
 
+## Migrating to 1.5.x (from 1.4.x)
+
+1.5.0 removed the custom `pantheon_delegate` tool (and the V1 delegation
+engine) in favor of OpenCode's native `task()`; see
+[Delegation (native `task()`)](#delegation-native-task). Two things change on
+an existing install:
+
+1. **The tool disappears from the plugin surface.** `pantheon_delegate` is no
+   longer registered by `src/plugin.ts` or `src/plugin-v2.ts`. Agents now
+   delegate through `task()` only — no configuration is needed.
+2. **A lockfile-pinned copy can keep the old tool alive.** `npm install` is
+   lockfile-authoritative: a `package-lock.json` pinned to `1.4.1` (which
+   satisfies `^1.4.1`) is never re-resolved, so a project's
+   `node_modules/pantheon-opencode` can stay on 1.4.x while the published
+   package moved on. The plugin path your `opencode.json` registers keeps
+   pointing at that stale copy, and you keep running the obsolete tool surface
+   — including `pantheon_delegate` — with no warning.
+
+The fix is a realignment + a detector:
+
+```bash
+# Realign the registered plugin path onto the current package (rewrites any
+# node_modules/pantheon-opencode reference in opencode.json):
+npx pantheon-opencode@latest init --yes --headless
+# or, with a global install:
+pantheon-opencode update
+
+# Then verify no drift remains:
+npx pantheon-opencode@latest doctor
+```
+
+`doctor` now reports a **Plugin Version Drift** warning (section H3) when the
+registered plugin points into an installed copy whose version differs from the
+running package, naming both versions and the removal (`pantheon_delegate` in
+1.5.0). A healthy install reports no warning.
+
 ## Releases
 
 Publication is authorized **only** by an explicit `workflow_dispatch` of the
@@ -331,6 +380,18 @@ and returns nothing. Prefer `background=true` dispatches with an explicit
 `task_status(wait=true)` fan-in so large payloads are collected deterministically.
 
 
+## Configuration (environment variables)
+
+| Variable | Default | Description |
+|---|---|---|
+| `PANTHEON_MEMORY_EMBED` | `on` | `off` (also `0`, `false`, `no`) disables the `pantheon-memory` embedding/vector pipeline — search runs in FTS5-only mode with no model download and no `sqlite-vec` writes. Also forced `off` automatically when `fastembed` fails to import, so a broken embedding install never takes the server down (issue #159). |
+
+The memory MCP degrades gracefully: when `fastembed` or `sqlite-vec` are
+unavailable (network failure, incompatible wheel), the server still starts,
+answers the MCP `initialize` handshake, and serves keyword search — only the
+semantic vector ranking is unavailable.
+
+
 ## Documentation
 
 - [Installation](docs/INSTALLATION.md) · [Quick start](docs/QUICKSTART.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pantheon-opencode",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "Multi-agent orchestration for OpenCode — 14 specialized agents, TDD, Themis review gates.",
   "type": "module",
   "publishConfig": {
@@ -119,7 +119,7 @@
   "author": "ils15",
   "license": "MIT",
   "engines": {
-    "node": ">=22"
+    "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
   },
   "preferGlobal": true
 }

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pantheon",
   "publisher": "ils15",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "displayName": "Pantheon",
   "description": "Conductor-Delegate orchestration platform with 14 specialized agents, 21 skills, and OpenCode support.",
   "agents": "./src/agents",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.backends._legacy:_Backend"
 
 [project]
 name = "pantheon"
-version = "1.5.0"
+version = "1.5.1"
 description = "Multi-agent orchestration framework"
 requires-python = ">=3.11"
 dependencies = []
@@ -39,6 +39,7 @@ ignore = ["E501"]
 "scripts/vector_memory/*.py" = ["PLC0415"]
 "tests/test_code_mode_sandbox.py" = ["PLC0415", "N806"]
 "tests/test_code_mode_server.py" = ["PLC0415"]
+"tests/test_codemap_mcp.py" = ["PLC0415"]
 "tests/test_memory_mcp_server.py" = ["PLC0415", "PLR2004"]
 # Existing public APIs and test fixtures are intentionally broad/simple; refactoring
 # them would be behavior-affecting rather than a mechanical lint correction.

package/scripts/doctor.mjs

@@ -9,6 +9,7 @@
  *   - Permission/frontmatter mismatches
  *   - OpenCode artifact freshness
  *   - Git status
+ *   - Node runtime (node:sqlite availability for pantheon_cost)
  *
  * Usage:
  *   node scripts/doctor.mjs                          # auto-detect, cwd
@@ -25,7 +26,7 @@ import { spawn as spawnAsync, spawnSync } from 'node:child_process'
 import { createHash } from 'node:crypto'
 import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { basename, dirname, join, resolve } from 'node:path'
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 // ---------------------------------------------------------------------------
@@ -159,6 +160,8 @@ function showHelp() {
    D. OpenCode Status      — OpenCode artifact layout
    E. Git Status           — uncommitted changes
    F. Runtime Layer        — venv python + pinned pip dependencies
+   H3. Plugin Drift        — registered plugin version vs this package
+   K. Node Runtime         — node:sqlite availability for pantheon_cost
 
  Exit codes:
    0  — no blocking errors (warnings are advisory)
@@ -1161,7 +1164,10 @@ function comparePantheonVersions(a, b) {
   for (let i = 0; i < 3; i++) {
     if (pa.core[i] !== pb.core[i]) return pa.core[i] - pb.core[i]
   }
-  return pa.beta - pb.beta
+  // Infinity - Infinity is NaN, which would make equal stable versions compare
+  // as drift for any caller using a strict === 0 check.
+  if (pa.beta === pb.beta) return 0
+  return pa.beta < pb.beta ? -1 : 1
 }
 
 /**
@@ -1214,6 +1220,159 @@ export function checkInstallVersionDrift(args) {
   return 'sync'
 }
 
+// ---------------------------------------------------------------------------
+// Check H3: Plugin version drift (issue #158)
+// ---------------------------------------------------------------------------
+// npm installs are lockfile-authoritative: a package-lock.json pinned to an
+// older pantheon-opencode (e.g. 1.4.1 satisfying ^1.4.1) is never re-resolved,
+// so an installed copy under node_modules/pantheon-opencode can lag several
+// releases behind the running package. The opencode.json keeps registering
+// that stale copy's plugin path and the user silently runs an obsolete tool
+// surface — 1.5.0 removed the pantheon_delegate tool, so a drifted install
+// still exposes it. This layer compares the version of the package a
+// registered plugin points into against this package's own version. Without
+// network access the "latest" version IS the running package's version.
+
+/** Locates an installed copy of this package inside a dependency tree. */
+const INSTALLED_PACKAGE_MARKER = '/node_modules/pantheon-opencode/'
+
+/**
+ * Return the installed-package root containing a plugin path, or null when the
+ * path is not inside a `node_modules/pantheon-opencode` tree.
+ *
+ * Only installed copies are compared: a dev checkout (e.g. <dev>/pantheon)
+ * and unrelated directories named pantheon-opencode are deliberately not
+ * flagged — the drift signal must never fire on a path the installer does not
+ * own (see the third-party guards in scripts/install/opencode.mjs).
+ *
+ * @param {string|null|undefined} pluginPath
+ * @returns {string|null}
+ */
+export function resolveInstalledPackageRoot(pluginPath) {
+  if (typeof pluginPath !== 'string') return null
+  const normalized = pluginPath.replaceAll('\\', '/')
+  const index = normalized.toLowerCase().lastIndexOf(INSTALLED_PACKAGE_MARKER.toLowerCase())
+  if (index === -1) return null
+  return normalized.slice(0, index + INSTALLED_PACKAGE_MARKER.length - 1)
+}
+
+/**
+ * Read the version of the installed pantheon-opencode package a registered
+ * plugin path points into.
+ * @param {string} pluginPath - absolute or config-relative plugin ref
+ * @returns {{root: string, version: string}|null} null when not an installed copy
+ */
+function readInstalledPluginVersion(pluginPath) {
+  const root = resolveInstalledPackageRoot(pluginPath)
+  if (!root) return null
+  const pkg = readJson(join(root, 'package.json'))
+  if (!pkg || typeof pkg.version !== 'string') return null
+  return { root, version: pkg.version }
+}
+
+/**
+ * Classify plugin version drift between the package a registered plugin points
+ * into and the running doctor's own package. Uses the prerelease-aware
+ * comparator so a stable release outranks its own betas (1.5.0 > 1.5.0-beta.9).
+ * Unreadable versions classify as "unknown" rather than drift, so a broken
+ * package.json never produces a false warning.
+ * @param {string|null} registeredVersion
+ * @param {string|null} packageVersion
+ * @returns {'sync'|'drift'|'unknown'}
+ */
+export function classifyPluginVersionDrift(registeredVersion, packageVersion) {
+  if (!registeredVersion || !packageVersion) return 'unknown'
+  return comparePantheonVersions(registeredVersion, packageVersion) === 0 ? 'sync' : 'drift'
+}
+
+/**
+ * Collect the plugin refs registered across opencode.json configs, from both
+ * the V1 `plugin` and V2 `plugins` lists. Each entry keeps the config it came
+ * from so relative refs resolve against the config directory (as the loader
+ * does), never against the doctor's cwd.
+ * @param {{path: string, data: object}[]} configs
+ * @returns {{path: string, configPath: string, configLabel: string}[]}
+ */
+export function collectRegisteredPluginRefs(configs) {
+  const refs = []
+  for (const cfg of configs) {
+    for (const key of ['plugin', 'plugins']) {
+      const list = cfg.data?.[key]
+      if (!Array.isArray(list)) continue
+      for (const ref of list) {
+        if (typeof ref === 'string') {
+          refs.push({ path: ref, configPath: cfg.path, configLabel: cfg.label })
+        } else if (ref && typeof ref === 'object') {
+          // Object-shaped entries carry their path under `path`/`source`.
+          const objectPath = ['path', 'source', 'id', 'name'].find(
+            (k) => typeof ref[k] === 'string',
+          )
+          if (objectPath) {
+            refs.push({ path: ref[objectPath], configPath: cfg.path, configLabel: cfg.label })
+          }
+        }
+      }
+    }
+  }
+  return refs
+}
+
+/**
+ * Compare the version of the package each registered plugin points into (when
+ * it is an installed copy under node_modules/pantheon-opencode) against this
+ * package's own version, and warn on divergence. Advisory only — a drift
+ * warning never changes the exit code, and a healthy install stays silent.
+ * @param {object} args
+ * @returns {'drift'|'sync'|'skip'|'no-plugin'|'no-version'}
+ */
+export function checkPluginVersionDrift(args) {
+  section('H3. Plugin Version Drift')
+
+  const pkg = readJson(join(ROOT, 'package.json'))
+  const packageVersion = pkg?.version
+  if (!packageVersion) {
+    info('Plugin version drift skipped — this package has no readable version')
+    return 'no-version'
+  }
+
+  const refs = collectRegisteredPluginRefs(collectMcpConfigs(args))
+  if (refs.length === 0) {
+    info('No plugin registrations found in opencode.json — version drift skipped')
+    return 'no-plugin'
+  }
+
+  const seen = new Set()
+  let compared = 0
+  let driftReported = false
+  for (const ref of refs) {
+    const absolute = isAbsolute(ref.path) ? ref.path : resolve(dirname(ref.configPath), ref.path)
+    const installed = readInstalledPluginVersion(absolute)
+    if (!installed) continue
+    // The doctor running from the very tree the plugin points at is the
+    // healthy global-install case — trivially in sync, never flagged.
+    if (resolve(installed.root) === resolve(ROOT)) continue
+    if (seen.has(installed.root)) continue
+    seen.add(installed.root)
+    compared++
+
+    if (classifyPluginVersionDrift(installed.version, packageVersion) !== 'drift') continue
+    driftReported = true
+    warn(
+      `${ref.configLabel}: plugin is registered inside pantheon-opencode v${installed.version}, but this package is v${packageVersion} — the registered tool surface is stale (pantheon_delegate was removed in 1.5.0). Run \`npx pantheon-opencode init\`, or update the package, to realign the registered plugin path`,
+    )
+  }
+
+  if (driftReported) return 'drift'
+  if (compared === 0) {
+    info(
+      'No registered plugin points into an installed pantheon-opencode copy — version drift skipped',
+    )
+    return 'skip'
+  }
+  pass(`All registered plugins point at package v${packageVersion}`)
+  return 'sync'
+}
+
 // ---------------------------------------------------------------------------
 // Check G: AGENTS.md freshness
 // ---------------------------------------------------------------------------
@@ -1424,6 +1583,71 @@ export function classifyPermissionTaskCheck(profile, installedCount, missingCoun
   return missingCount === 0 ? 'pass' : 'error'
 }
 
+// ---------------------------------------------------------------------------
+// Check K: Node Runtime — node:sqlite availability (issue #114)
+// ---------------------------------------------------------------------------
+
+// pantheon_cost uses node:sqlite as its read-only backend; below this Node
+// version the tool reports UNSUPPORTED (see the "Cost tool backend" README
+// section). Matches the floor documented for the PANTHEON_NODE fallback.
+const NODE_SQLITE_MIN = '22.5'
+
+/**
+ * Probe whether the running Node.js can load `node:sqlite` — the read-only
+ * backend used by the `pantheon_cost` tool (issue #114). Runs the import in a
+ * `--no-warnings` child so the experimental-feature notice never pollutes the
+ * doctor output, and so a probe crash can never take down the doctor itself.
+ *
+ * @param {{ execPath?: string; module?: string }} [options]
+ * @returns {{ available: boolean; version: string; reason?: string }}
+ */
+export function probeNodeSqlite(options = {}) {
+  const execPath = options.execPath ?? process.execPath
+  const target = options.module ?? 'node:sqlite'
+  const result = spawn(execPath, [
+    '--no-warnings',
+    '--input-type=module',
+    '-e',
+    `import '${target}'`,
+  ])
+  if (result.status === 0) return { available: true, version: process.version }
+  const reason = (result.stderr || result.stdout || 'import failed').split('\n')[0]
+  return { available: false, version: process.version, reason }
+}
+
+/**
+ * Classify a node:sqlite probe result for the doctor. Kept free of I/O so the
+ * contract is exercised deterministically (see tests/test_doctor_layers.mjs).
+ *
+ * @param {{ available: boolean; version: string }} probe
+ * @returns {{ status: 'ok' | 'unsupported'; message: string }}
+ */
+export function classifyNodeSqliteProbe(probe) {
+  if (probe.available) {
+    return {
+      status: 'ok',
+      message: `node:sqlite available on ${probe.version} — pantheon_cost read-only backend supported`,
+    }
+  }
+  return {
+    status: 'unsupported',
+    message: `pantheon_cost will report UNSUPPORTED on Node ${probe.version} — node:sqlite requires Node >= ${NODE_SQLITE_MIN}`,
+  }
+}
+
+function checkNodeRuntime() {
+  section('K. Node Runtime')
+  const outcome = classifyNodeSqliteProbe(probeNodeSqlite())
+  if (outcome.status === 'ok') {
+    pass(outcome.message)
+  } else {
+    warn(outcome.message)
+    info(
+      `Upgrade to Node >= ${NODE_SQLITE_MIN} (or a runtime with node:sqlite) to enable pantheon_cost`,
+    )
+  }
+}
+
 /**
  * Return the final doctor status message without masking blocking errors.
  * @param {{ error: number; warn: number }} summaryCounts
@@ -1506,12 +1730,14 @@ async function main() {
     existsSync(join(args.target, 'scripts', 'doctor.mjs')) === false
 
   // Run checks (layer order: Config → Venv → spawn paths → runtime smoke)
+  checkNodeRuntime(args)
   checkAgentFiles(args)
   checkMcpConfig(args)
   checkVenvLayer(args)
   checkCodeModeDir(args)
   checkCodeModeManifest(args)
   checkInstallVersionDrift(args)
+  checkPluginVersionDrift(args)
   await checkMcpRuntimeSmoke(args)
   checkPermissionMismatches(args)
   checkSyncStatus(args)

package/src/agents/mnemosyne.md

@@ -34,7 +34,17 @@ permission:
   bash: deny
   read: allow
   grep: allow
-  edit: allow
+  # Scoped write/edit: mnemosyne may create and modify files ONLY inside the
+  # memory-bank and deepwork directories. Everything else stays denied, keeping
+  # the SCOPE BOUNDARY below enforceable at the permission layer (issue #111).
+  write:
+    "*": deny
+    ".pantheon/memory-bank/**": allow
+    ".pantheon/deepwork/**": allow
+  edit:
+    "*": deny
+    ".pantheon/memory-bank/**": allow
+    ".pantheon/deepwork/**": allow
   task:
     "*": deny
 ---

package/src/agents/zeus.md

@@ -3,6 +3,7 @@ description: "Orquestrador central — NUNCA implementa. Roteia para especialist
 mode: primary
 reasoning_effort: medium
 permission:
+  read: allow
   edit: deny
   bash: deny
   task:

package/src/mcp/memory_mcp_server.py

@@ -6,6 +6,10 @@ for semantic memory with hybrid search (vector cosine + FTS5 BM25).
 
 Total footprint: ~50MB (sqlite-vec + fastembed) vs ~1.4GB (old chromadb).
 
+Both embedding backends are optional: if either fails to import the server
+still starts and serves FTS5-only search (``PANTHEON_MEMORY_EMBED=off``
+disables the vector pipeline explicitly).
+
 Tools:
     memory_store   — Store with automatic embedding
     memory_search  — Hybrid vector + FTS5 keyword search
@@ -30,9 +34,21 @@ from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
 
-import sqlite_vec
+# Embedding backends are optional (issue #159): a failed fastembed/sqlite_vec
+# install (network error, incompatible wheel) must not kill the server — it
+# degrades to FTS-only search instead of crashing before the MCP handshake.
+try:
+    import sqlite_vec
+except ImportError:  # pragma: no cover - degraded mode
+    sqlite_vec = None  # type: ignore[assignment]
+
 from _pantheon_paths import pantheon_home
-from fastembed import TextEmbedding
+
+try:
+    from fastembed import TextEmbedding
+except ImportError:  # pragma: no cover - degraded mode
+    TextEmbedding = None  # type: ignore[assignment]
+
 from mcp.server.fastmcp import FastMCP
 
 try:
@@ -52,6 +68,12 @@ except ImportError:  # pragma: no cover - deployed runtime may need path fix
 DB_PATH = pantheon_home() / "memory" / "memory.db"
 EMBED_CACHE = Path.home() / ".cache" / "fastembed"
 
+# PANTHEON_MEMORY_EMBED=off disables the embedding/vector pipeline so the
+# server serves FTS-only search (issue #159). Default "on" keeps the current
+# hybrid vector + FTS behavior. The flag is also forced off automatically
+# when fastembed failed to import.
+_EMBED_DISABLED = frozenset({"off", "0", "false", "no"})
+
 
 _BYTE_UNIT = 1024
 
@@ -81,11 +103,6 @@ CREATE TABLE IF NOT EXISTS memories (
 CREATE UNIQUE INDEX IF NOT EXISTS idx_memories_ns_key
     ON memories(namespace, key);
 
-CREATE VIRTUAL TABLE IF NOT EXISTS vec_memories USING vec0(
-    id INTEGER PRIMARY KEY,
-    embedding float[384]
-);
-
 CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
     namespace, key, value, metadata,
     content='memories', content_rowid='id',
@@ -113,6 +130,14 @@ CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
 END;
 """
 
+# Vector store requires the sqlite-vec extension; created only when available.
+VEC_SCHEMA_SQL = """
+CREATE VIRTUAL TABLE IF NOT EXISTS vec_memories USING vec0(
+    id INTEGER PRIMARY KEY,
+    embedding float[384]
+);
+"""
+
 # ── FastMCP App ───────────────────────────────────────────────────────────────
 
 mcp = FastMCP(
@@ -129,7 +154,8 @@ def _get_db() -> sqlite3.Connection:
     """Get or create the SQLite connection singleton.
 
     Creates DB directory, applies WAL/performance pragmas, registers
-    the sqlite-vec extension, and runs schema init.
+    the sqlite-vec extension, and runs schema init. When sqlite-vec is
+    unavailable the vector table is skipped — search degrades to FTS-only.
     """
     DB_PATH.parent.mkdir(parents=True, exist_ok=True)
     conn = sqlite3.connect(str(DB_PATH), check_same_thread=False)
@@ -137,9 +163,10 @@ def _get_db() -> sqlite3.Connection:
     conn.execute("PRAGMA journal_mode=WAL")
     conn.execute("PRAGMA busy_timeout=5000")
     conn.execute("PRAGMA foreign_keys=ON")
-    # Register sqlite-vec extension
-
-    sqlite_vec.load(conn)
+    # Register sqlite-vec extension (optional; enables vector search)
+    if sqlite_vec is not None:
+        sqlite_vec.load(conn)
+        conn.executescript(VEC_SCHEMA_SQL)
     conn.executescript(SCHEMA_SQL)
     if _codemap is not None:
         with contextlib.suppress(Exception):
@@ -155,13 +182,30 @@ def _get_conn() -> sqlite3.Connection:
 # ── Embedding ─────────────────────────────────────────────────────────────────
 
 
+def _embeddings_enabled() -> bool:
+    """Whether the embedding/vector pipeline is active.
+
+    Controlled by ``PANTHEON_MEMORY_EMBED`` (``on`` by default; ``off``,
+    ``0``, ``false`` or ``no`` disable it). Automatically disabled when
+    ``fastembed`` failed to import, so the server degrades to FTS-only
+    search instead of crashing at startup (issue #159).
+    """
+    if TextEmbedding is None:
+        return False
+    flag = os.environ.get("PANTHEON_MEMORY_EMBED", "on").strip().lower()
+    return flag not in _EMBED_DISABLED
+
+
 @functools.cache
-def _get_embedder() -> TextEmbedding:
+def _get_embedder() -> TextEmbedding | None:
     """Lazy-load fastembed model (auto-downloads on first call, ~30MB).
 
     Uses BAAI/bge-small-en-v1.5 (384-dim, CPU, ONNX) — no PyTorch needed.
-    Model is cached in ~/.cache/fastembed/.
+    Model is cached in ~/.cache/fastembed/. Returns None when fastembed is
+    unavailable.
     """
+    if TextEmbedding is None:
+        return None
     os.environ.setdefault("TQDM_DISABLE", "1")
     return TextEmbedding(
         model_name="BAAI/bge-small-en-v1.5",
@@ -169,9 +213,18 @@ def _get_embedder() -> TextEmbedding:
     )
 
 
-def _embed(text: str) -> list[float]:
-    """Generate a 384-dim embedding vector for the given text."""
-    return next(iter(_get_embedder().embed(text))).tolist()
+def _embed(text: str) -> list[float] | None:
+    """Generate a 384-dim embedding vector for the given text.
+
+    Returns None when embeddings are disabled (``PANTHEON_MEMORY_EMBED=off``
+    or fastembed missing) — callers fall back to FTS-only search.
+    """
+    if not _embeddings_enabled():
+        return None
+    embedder = _get_embedder()
+    if embedder is None:
+        return None
+    return next(iter(embedder.embed(text))).tolist()
 
 
 # ── Helpers ───────────────────────────────────────────────────────────────────
@@ -341,14 +394,14 @@ def memory_store(
         )
         entry_id = cur.lastrowid
 
-        # Generate embedding
+        # Generate embedding (None when disabled → FTS-only mode)
         embedding = _embed(value)
-        embedding_json = json.dumps(embedding)
-
-        db.execute(
-            "INSERT INTO vec_memories(id, embedding) VALUES (?, ?)",
-            [entry_id, embedding_json],
-        )
+        if embedding is not None and sqlite_vec is not None:
+            embedding_json = json.dumps(embedding)
+            db.execute(
+                "INSERT INTO vec_memories(id, embedding) VALUES (?, ?)",
+                [entry_id, embedding_json],
+            )
         db.commit()
     except sqlite3.IntegrityError as e:
         db.rollback()
@@ -406,8 +459,8 @@ def memory_search(  # noqa: C901, PLR0912
     vec_ids: list[int] = []
     fts_ids: list[int] = []
 
-    # 2. Vector search
-    if query_vec is not None:
+    # 2. Vector search (skipped when embeddings or sqlite-vec are unavailable)
+    if query_vec is not None and sqlite_vec is not None:
         nvec = top_k * 2
         try:
             if namespace:
@@ -564,8 +617,9 @@ def memory_forget(
     db = _get_conn()
     try:
         if col == "id":
-            # Vec table cascade
-            db.execute("DELETE FROM vec_memories WHERE id = ?", [id])
+            # Vec table cascade (absent when sqlite-vec is unavailable)
+            if sqlite_vec is not None:
+                db.execute("DELETE FROM vec_memories WHERE id = ?", [id])
             cur = db.execute("DELETE FROM memories WHERE id = ?", [id])
         else:
             cur = db.execute(sql, params)