@lincoln504/pi-research 1.6.19 → 1.6.20

package/dist/thread-worker.mjs

@@ -2699,6 +2699,13 @@ var ConfigSchema = Type.Object({
   WORKER_CONCURRENCY: Type.Number({ minimum: 1, maximum: 10, default: 2 }),
   /** Knowledge store isolation mode (default: 'global' — one shared store across every directory) */
   KNOWLEDGE_STORE_MODE: Type.Union([Type.Literal("none"), Type.Literal("project"), Type.Literal("global")], { default: "global" }),
+  /** Knowledge store retrieval strategy (default: 'vector' — current hybrid dense+sparse behavior).
+   *  'vector' = hybrid search (embedding similarity + BM25/FTS fused via RRF; requires the
+   *  optional @huggingface/transformers dependency and a downloaded embedding model).
+   *  'bm25'   = pure lexical/BM25 retrieval over the same stored findings — NO embedding model:
+   *  never initialized, downloaded, or invoked. Uses a separate lexical table in the same
+   *  LanceDB database, so existing vector stores are untouched (no migration). */
+  KNOWLEDGE_STORE_RETRIEVAL: Type.Union([Type.Literal("vector"), Type.Literal("bm25")], { default: "vector" }),
   /** Embedding model to use for the knowledge store */
   EMBEDDING_MODEL: Type.String({ default: "onnx-community/granite-embedding-small-english-r2-ONNX" }),
   /** Hardware backend for embeddings: 'auto' (probe WebGPU viability out-of-process, fall back to CPU), 'webgpu' (force), or 'cpu' (force).

package/docs/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.20] - 2026-09-21
+
+### Added
+
+- **BM25-only (lexical) knowledge-store retrieval mode: the store can now run entirely without an embedding model** (merged PR #14 by @akmalayari). A new project-scoped setting, `PI_RESEARCH_KNOWLEDGE_STORE_RETRIEVAL` (`vector` — the default and unchanged hybrid behavior — or `bm25`), selects how stored findings are retrieved. In `bm25` mode, retrieval is pure BM25 over LanceDB's Tantivy full-text indexes (the same lexical half the hybrid path already used, now standing alone over the summary text and full page Markdown) — the `@huggingface/transformers` dependency is never resolved, loaded, downloaded, or invoked, so a bm25-only installation works with `--omit=optional` and no model download. Each strategy keeps its own table in the same database directory (`knowledge` vs `knowledge-bm25`), so switching requires no migration and existing vector stores are untouched. The mode is exposed everywhere the scoping mode is: `knowledge-config set retrieval <vector|bm25>` and `show` on the CLI, a Knowledge Retrieval entry in the `/research-config` menu (embedding model/device entries hide in bm25 mode), the healthcheck, and the availability probe — which in bm25 mode no longer demands the optional embedding package. New tests cover the lexical round-trip, BM25 ranking sanity, scope isolation, cross-mode coexistence, per-mode availability probing, config parsing, and a hard embedder-factory-never-called isolation assertion; docs (KNOWLEDGE-STORE.md, CONFIGURATION.md, `.env.example`) document the three-way scoping × retrieval story.
+
+### Changed
+
+- **pi packages updated to the 0.87.0 line and the compatibility floor/tested-ceiling moved to match.** `@earendil-works/pi-ai`, `pi-coding-agent`, `pi-server` and `pi-tui` move `>=0.85.0 <1` → `>=0.87.0 <1` (all four verified at 0.87.0); `PI_MIN_VERSION` and `PI_TESTED_MAX_VERSION` move 0.85.0 → 0.87.0 with the floor's rationale updated for the 0.86 pi-ai TranscriptContext / JSON-value / fail-closed-user_bash changes and the 0.87 `SessionEntry` union (`ContextEditEntry`), SessionManager-canonical provider context, and `shouldStopAfterTurn` → `finishTurn` boundary. All four type-checks, lint, and the full unit suite (3,120 tests) pass against the 0.87.0 packages; `src/index.ts`'s runtime-check comment tracks the new floor.
+- **`@lancedb/lancedb` moves 0.38.0 → 0.39.0** (same-semver native store; the full unit suite passes against it, and the `apache-arrow` hold below was re-verified against the new native reader — the 21.2.0 IPC failure reproduces identically under 0.39.0).
+
+### Fixed
+
+- **CodeQL alert #267 (`js/unused-local-variable`, note): an unused `vi` import left in the PR #14 test file `store-bm25.test.ts` is removed.** Caught by the CodeQL run on the merge commit; no other open alerts remain.
+- **Dependency holds re-verified and enforced again after an attempted refresh:** `apache-arrow` stays 21.1.0 — 21.2.0 breaks `@lancedb/lancedb` 0.39.0's IPC schema parsing (the RangeOutOfBounds footer error reproduces in the test runner; a create-then-read of the store schema fails at `createTable`), confirming the existing hold against the new native reader; `playwright-core` stays 1.60.0 (camoufox-js 0.12.0's peer range still caps `<1.61.0` — 1.63.0 fails `npm install` with ERESOLVE); `@huggingface/transformers` stays 4.2.0 (4.3.0 pulls `onnxruntime-node` 1.30.0 and reshuffles the optional native stack for no needed gain, per the 1.6.18 hold); `typebox` moves 1.3.7 → 1.3.27, realigning the lockstep rule with the new host line (pi 0.87.0's own packages pin 1.3.27 — 1.3.34 was briefly tried and reverted for breaking that rule). Dev-only in-range bumps: `eslint` 10.10.0 → 10.11.0, `@typescript-eslint/*` 8.70.0 → 8.70.1.
+
 ## [1.6.19] - 2026-09-18
 
 ### Added

package/docs/CONFIGURATION.md

@@ -27,6 +27,7 @@ variables still take effect.) A setting is written to one of two scopes:
 |---------|-------|--------|---------|
 | `/research` depth | project | normal · deep · ultra | `PI_RESEARCH_DEFAULT_RESEARCH_DEPTH` |
 | Knowledge Mode | project | none · project · global | `PI_RESEARCH_KNOWLEDGE_STORE_MODE` |
+| Knowledge Retrieval | project | vector · bm25 | `PI_RESEARCH_KNOWLEDGE_STORE_RETRIEVAL` |
 | Researcher Timeout | user | 3 · 5 · 10 · 15 · 20 · 30 (minutes) | `PI_RESEARCH_TIMEOUT_MS` |
 | Max Concurrency | user | 1 – 5 | `PI_RESEARCH_MAX_RESEARCHERS` |
 | Scrape Batches | user | unlimited · 1 · 2 · 3 · 5 · 10 · 15 | `PI_RESEARCH_MAX_SCRAPE_BATCHES` |
@@ -127,7 +128,8 @@ See the [knowledge store doc](KNOWLEDGE-STORE.md) for what each value does.
 
 | Variable | Default | Range | Description |
 |----------|---------|-------|-------------|
-| `PI_RESEARCH_KNOWLEDGE_STORE_MODE` (TUI) `[project]` | `global` | none · project · global | Store scope: one shared store across every directory (`global`), scoped to the current directory (`project`), or disabled (`none`). Independently of this setting, the store is cleanly OFF when its required packages are not installed (optional `@huggingface/transformers` skipped at install, broken `@lancedb/lancedb`): init fails fast instead of retry-storming, and `pi-research knowledge-config`, the `/research-config` menu, and the healthcheck all name the missing package and the repair. |
+| `PI_RESEARCH_KNOWLEDGE_STORE_MODE` (TUI) `[project]` | `global` | none · project · global | Store scope: one shared store across every directory (`global`), scoped to the current directory (`project`), or disabled (`none`). Independently of this setting, the store is cleanly OFF when its required packages are not installed (optional `@huggingface/transformers` skipped at install, broken `@lancedb/lancedb`): init fails fast instead of retry-storming, and `pi-research knowledge-config`, the `/research-config` menu, and the healthcheck all name the missing package and the repair. In `bm25` retrieval mode the embedding package is not required at all. |
+| `PI_RESEARCH_KNOWLEDGE_STORE_RETRIEVAL` (TUI) `[project]` | `vector` | vector · bm25 | Retrieval strategy: `vector` = hybrid (embedding similarity + BM25 fused via RRF; needs the optional embedding model), `bm25` = pure lexical BM25 (no embedding model — never downloaded or initialized; works with `--omit=optional`). Each strategy keeps its own table in the same database directory, so switching requires no migration. |
 | `PI_RESEARCH_EMBEDDING_MODEL` (TUI) | `onnx-community/granite-embedding-small-english-r2-ONNX` | — | Embedding model. Changing it clears the store and starts fresh. |
 | `PI_RESEARCH_EMBEDDING_DEVICE` (TUI) | `auto` | auto · webgpu · cpu | Inference backend. `auto` probes WebGPU viability out-of-process and falls back to CPU; `cpu` forces CPU; `webgpu` forces the GPU path with no probe (advanced — can hard-crash on a software GPU). The TUI exposes only `auto` (as "GPU") and `cpu`. |
 | `PI_RESEARCH_CACHE_TTL_DAYS` (TUI) | `30` | 1–365 | How long cached findings are kept before eviction. |

package/docs/KNOWLEDGE-STORE.md

@@ -58,6 +58,35 @@ The embedding model is lazy — it only downloads and initializes the first time
 the store is actually written or searched, so the `global` default adds no startup
 cost until a run caches its first page.
 
+### Retrieval strategies: vector (hybrid) and bm25 (lexical)
+
+Independent of scope, the store's retrieval strategy is set by
+`PI_RESEARCH_KNOWLEDGE_STORE_RETRIEVAL` (a project-scoped setting, default
+`vector`):
+
+| Strategy | Behavior |
+|----------|----------|
+| `vector` (default) | Hybrid search: embedding similarity + BM25 keyword matching over the stored summaries and full page text, fused via reciprocal rank fusion (RRF). Richest matching, especially for paraphrases. Requires the optional `@huggingface/transformers` dependency and a downloaded embedding model. |
+| `bm25` | Pure lexical search: BM25 ranking over the same stored summaries and full page text. **No embedding model** — never downloaded, initialized, or invoked — so a bm25-only installation works with `--omit=optional` and adds no model download. |
+
+Change the strategy for the current directory with the `/research-config` TUI
+(Knowledge Retrieval), or with `pi-research knowledge-config set retrieval
+<vector|bm25>` on the standalone CLI. Like Knowledge Mode, it persists to the
+per-directory project registry and applies without a restart.
+
+The two strategies keep **separate tables** in the same database directory
+(`knowledge` for vector, `knowledge-bm25` for bm25). An existing vector store is
+never touched by bm25 mode and vice versa — switching strategies requires no
+migration, and each mode keeps its own history while the other is active. In
+`bm25` mode, `exportKnowledge()` omits vectors, and the embedding settings
+(`PI_RESEARCH_EMBEDDING_MODEL`, `PI_RESEARCH_EMBEDDING_DEVICE`,
+`PI_RESEARCH_EMBEDDING_MODEL_INIT_TIMEOUT_MS`) are ignored entirely.
+
+BM25 ranking uses Tantivy (LanceDB's full-text engine) with its default Unicode
+tokenization and lowercasing, over both the summary text and the full page
+Markdown — so lexical mode matches the same fields the hybrid mode's keyword
+half does.
+
 ### How a run uses the store
 
 The store is driven by the orchestrator, not called ad hoc by researcher agents,
@@ -76,6 +105,9 @@ synthesized answer with citations — or reports that live research is needed.
 
 ### Embeddings and the model
 
+Applies to the `vector` (hybrid) retrieval strategy only — `bm25` mode runs with
+no embedding model at all.
+
 Embeddings are computed locally with
 [`@huggingface/transformers`](https://github.com/huggingface/transformers.js) over
 ONNX. The default model is
@@ -173,7 +205,8 @@ keep history longer.
 
 ### Changing the model: migration
 
-When the configured embedding model differs from the one the stored vectors were
+Applies to the `vector` retrieval strategy. When the configured embedding model
+differs from the one the stored vectors were
 built with, the store is migrated according to `PI_RESEARCH_MIGRATION_STRATEGY`:
 
 | Strategy | What happens |
@@ -209,12 +242,13 @@ indices are pruned to keep it bounded. There is no manual maintenance command.
 | Setting | Variable | Default |
 |---------|----------|---------|
 | Knowledge Mode (project-scoped) | `PI_RESEARCH_KNOWLEDGE_STORE_MODE` | `global` |
-| Embedding model | `PI_RESEARCH_EMBEDDING_MODEL` | `onnx-community/granite-embedding-small-english-r2-ONNX` |
-| Embedding device | `PI_RESEARCH_EMBEDDING_DEVICE` | `auto` |
+| Retrieval strategy (project-scoped) | `PI_RESEARCH_KNOWLEDGE_STORE_RETRIEVAL` | `vector` |
+| Embedding model (vector mode only) | `PI_RESEARCH_EMBEDDING_MODEL` | `onnx-community/granite-embedding-small-english-r2-ONNX` |
+| Embedding device (vector mode only) | `PI_RESEARCH_EMBEDDING_DEVICE` | `auto` |
 | Cache retention (days) | `PI_RESEARCH_CACHE_TTL_DAYS` | `30` |
 | Migration strategy | `PI_RESEARCH_MIGRATION_STRATEGY` | `backup` |
 | Database directory | `PI_RESEARCH_KNOWLEDGE_DIR` | `~/.pi/research/knowledge_db` |
-| Model init timeout (ms) | `PI_RESEARCH_EMBEDDING_MODEL_INIT_TIMEOUT_MS` | `300000` |
+| Model init timeout, vector mode only (ms) | `PI_RESEARCH_EMBEDDING_MODEL_INIT_TIMEOUT_MS` | `300000` |
 | Re-probe WebGPU | `PI_RESEARCH_WEBGPU_REPROBE` | _(unset)_ |
 
 See [CONFIGURATION.md](CONFIGURATION.md) for the full configuration model, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "1.6.19",
+  "version": "1.6.20",
   "description": "Web research for your agents with smart and safe tooling + knowledge store",
   "type": "module",
   "private": false,
@@ -115,12 +115,12 @@
     "image": "https://raw.githubusercontent.com/Lincoln504/pi-research/main/docs/media/hero.png"
   },
   "dependencies": {
-    "@earendil-works/pi-ai": ">=0.85.0 <1",
-    "@earendil-works/pi-coding-agent": ">=0.85.0 <1",
-    "@earendil-works/pi-server": ">=0.85.0 <1",
-    "@earendil-works/pi-tui": ">=0.85.0 <1",
+    "@earendil-works/pi-ai": ">=0.87.0 <1",
+    "@earendil-works/pi-coding-agent": ">=0.87.0 <1",
+    "@earendil-works/pi-server": ">=0.87.0 <1",
+    "@earendil-works/pi-tui": ">=0.87.0 <1",
     "@kreuzberg/html-to-markdown-node": "^3.7.2",
-    "@lancedb/lancedb": "0.38.0",
+    "@lancedb/lancedb": "0.39.0",
     "apache-arrow": "21.1.0",
     "bgutils-js": "^4.0.3",
     "camoufox-js": "^0.12.0",
@@ -131,7 +131,7 @@
     "pdf-oxide-wasm": "^0.3.77",
     "playwright-core": "1.60.0",
     "poolifier": "^5.3.2",
-    "typebox": "1.3.7",
+    "typebox": "1.3.27",
     "undici": "^8.10.2",
     "youtubei.js": "^18.0.0"
   },
@@ -157,12 +157,12 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/jsdom": "^30.0.0",
-    "@typescript-eslint/eslint-plugin": "^8.70.0",
-    "@typescript-eslint/parser": "^8.70.0",
+    "@typescript-eslint/eslint-plugin": "8.70.1",
+    "@typescript-eslint/parser": "8.70.1",
     "@vitest/coverage-v8": "^5.0.1",
     "dependency-cruiser": "^18.2.0",
     "depngn": "^0.6.0",
-    "eslint": "^10.10.0",
+    "eslint": "10.11.0",
     "npm-check-updates": "^23.1.0",
     "typescript": ">=6.0.3 <6.1.0",
     "vite": "^8.2.2",

package/src/cli.ts

@@ -8,6 +8,7 @@
  *   pi-research research "<query>" [--depth N] [--model provider/id]
  *   pi-research knowledge "<q>" ["<q2>" ...]
  *   pi-research knowledge-config [set <none|project|global>]
+ *   pi-research knowledge-config set retrieval <vector|bm25>
  *   pi-research status [--json]
  *   pi-research help
  *
@@ -895,6 +896,32 @@ export async function cmdKnowledgeConfig(kc: NonNullable<ParsedArgs['knowledgeCo
   // silently breaking the documented `--json: Emit a JSON object` contract for
   // this one subcommand.
   try {
+    if (kc.action === 'set-retrieval') {
+      const before = getConfig(cwd, 'cli').KNOWLEDGE_STORE_RETRIEVAL;
+      const cfg = { ...getConfig(cwd, 'cli'), KNOWLEDGE_STORE_RETRIEVAL: kc.retrieval! };
+      // Persist ONLY the retrieval strategy for this directory — mirrors the
+      // scoping-mode `set` branch above (changedKeys-scoped registry write).
+      saveConfig(cfg, 'local', cwd, ['PI_RESEARCH_KNOWLEDGE_STORE_RETRIEVAL']);
+      resetConfig();
+      const info = describeKnowledgeStoreMode(cwd, 'cli');
+      const overridden = info.retrieval !== kc.retrieval;
+      if (kc.json) {
+        toStdout(pretty({ command: 'knowledge-config', action: 'set-retrieval', requested: kc.retrieval, previous: before, saved: true, effectiveOverriddenBy: overridden ? info.retrievalOrigin : null, ...info, cwd }));
+        return EXIT.OK;
+      }
+      toStdout(
+        `knowledge store retrieval for this directory: ${before} -> ${kc.retrieval}  (saved per-directory)\n` +
+        `  strategy: ${kc.retrieval === 'bm25' ? 'lexical BM25 — no embedding model needed' : 'hybrid (embedding + BM25, fused) — needs the optional embedding dependency'}\n` +
+        `  saved:    per-directory (${cwd})\n` +
+        `  db dir:   ${info.dbDir}\n` +
+        (info.available ? '' : `  state:    ${info.unavailableReason}\n`) +
+        (overridden
+          ? `\nNOTE: the effective retrieval here is still '${info.retrieval}' because a higher-precedence ${info.retrievalOrigin} overrides it. Clear that source for this setting to take effect.\n`
+          : ''),
+      );
+      return EXIT.OK;
+    }
+
     if (kc.action === 'set') {
       const before = getConfig(cwd, 'cli').KNOWLEDGE_STORE_MODE;
       const cfg = { ...getConfig(cwd, 'cli'), KNOWLEDGE_STORE_MODE: kc.mode! };
@@ -932,11 +959,14 @@ export async function cmdKnowledgeConfig(kc: NonNullable<ParsedArgs['knowledgeCo
     }
     toStdout(
       `knowledge store mode: ${info.mode}   (source: ${info.origin})\n` +
-      `  scope:   ${info.mode === 'none' ? 'disabled here' : info.mode === 'project' ? 'this directory only' : 'shared across all directories'}\n` +
-      `  db dir:  ${info.dbDir}\n` +
-      (info.available ? '' : `  state:   ${info.unavailableReason}\n`) +
-      `\nchange it for THIS directory:  ${BINARY_NAME} knowledge-config set <none|project|global>\n` +
-      `change the machine-wide default: set PI_RESEARCH_KNOWLEDGE_STORE_MODE=<mode> in ${resolvedConfigPaths().configEnv}\n`,
+      `knowledge store retrieval: ${info.retrieval}   (source: ${info.retrievalOrigin})\n` +
+      `  scope:     ${info.mode === 'none' ? 'disabled here' : info.mode === 'project' ? 'this directory only' : 'shared across all directories'}\n` +
+      `  strategy:  ${info.retrieval === 'bm25' ? 'lexical BM25 — no embedding model needed' : 'hybrid (embedding + BM25, fused)'}\n` +
+      `  db dir:    ${info.dbDir}\n` +
+      (info.available ? '' : `  state:     ${info.unavailableReason}\n`) +
+      `\nchange scope for THIS directory:     ${BINARY_NAME} knowledge-config set <none|project|global>\n` +
+      `change retrieval for THIS directory: ${BINARY_NAME} knowledge-config set retrieval <vector|bm25>\n` +
+      `change the machine-wide defaults: set PI_RESEARCH_KNOWLEDGE_STORE_MODE=<mode> and/or PI_RESEARCH_KNOWLEDGE_STORE_RETRIEVAL=<vector|bm25> in ${resolvedConfigPaths().configEnv}\n`,
     );
     return EXIT.OK;
   } catch (err) {
@@ -1235,7 +1265,7 @@ interface ParsedArgs {
   command?: string;
   research?: ResearchArgs;
   knowledge?: { queries: string[]; json?: boolean };
-  knowledgeConfig?: { action: 'show' | 'set'; mode?: 'none' | 'project' | 'global'; json?: boolean };
+  knowledgeConfig?: { action: 'show' | 'set' | 'set-retrieval'; mode?: 'none' | 'project' | 'global'; retrieval?: 'vector' | 'bm25'; json?: boolean };
   status?: { json?: boolean };
   skill?: { action: 'install' | 'uninstall' | 'status'; json?: boolean; dryRun?: boolean; copy?: boolean };
   configPath?: string;
@@ -1270,6 +1300,10 @@ COMMANDS
     --json                       Emit a JSON object.
   knowledge-config set <mode>    Set the mode for THIS directory (none | project | global);
                                  persisted per-directory. Takes effect on the next run.
+  knowledge-config set retrieval <vector|bm25>
+                                 Set the retrieval strategy for THIS directory: 'vector'
+                                 (hybrid embedding+BM25, default) or 'bm25' (pure lexical,
+                                 no embedding model). Persisted per-directory.
 
   status                         Show detected config, model/key, and readiness.
     --config <path>              Layer this config file on top (highest file precedence; base
@@ -1303,6 +1337,7 @@ CONFIGURE
 
   Knowledge store — ON by default in every directory (mode 'global', one shared store).
     per-directory:  ${BINARY_NAME} knowledge-config set <none|project|global>
+                    ${BINARY_NAME} knowledge-config set retrieval <vector|bm25>
     machine-wide:   PI_RESEARCH_KNOWLEDGE_STORE_MODE=<mode>  in ${p.configEnv}
     'project' scopes the store to the current directory; 'none' disables it here.
 
@@ -1421,6 +1456,24 @@ export function parseArgs(argv: string[]): ParsedArgs {
       return out;
     }
     if (action === 'set') {
+      // Extended form: `knowledge-config set retrieval <vector|bm25>` — switches the
+      // retrieval STRATEGY (the scoping mode uses the original single-arg form).
+      if (positional[1] === 'retrieval') {
+        const retrieval = positional[2];
+        if (retrieval === undefined) {
+          throw new UsageError('knowledge-config set retrieval requires a strategy: vector | bm25.');
+        }
+        if (retrieval !== 'vector' && retrieval !== 'bm25') {
+          throw new UsageError(`invalid retrieval strategy "${retrieval}". Use one of: vector | bm25.`);
+        }
+        if (positional.length > 3) {
+          throw new UsageError(`unexpected argument "${positional[3]}" after "knowledge-config set retrieval ${retrieval}".`);
+        }
+        out.command = 'knowledge-config';
+        out.knowledgeConfig = { action: 'set-retrieval', retrieval, json };
+        out.configPath = configPath;
+        return out;
+      }
       const mode = positional[1];
       if (mode === undefined) {
         throw new UsageError('knowledge-config set requires a mode: none | project | global.');
@@ -1436,7 +1489,7 @@ export function parseArgs(argv: string[]): ParsedArgs {
       out.configPath = configPath;
       return out;
     }
-    throw new UsageError(`unknown knowledge-config action "${action}". Use: show | set <none|project|global>.`);
+    throw new UsageError(`unknown knowledge-config action "${action}". Use: show | set <none|project|global> | set retrieval <vector|bm25>.`);
   }
 
   if (cmd === 'skill') {

package/src/config.ts

@@ -50,6 +50,13 @@ export const ConfigSchema = Type.Object({
   WORKER_CONCURRENCY: Type.Number({ minimum: 1, maximum: 10, default: 2 }),
   /** Knowledge store isolation mode (default: 'global' — one shared store across every directory) */
   KNOWLEDGE_STORE_MODE: Type.Union([Type.Literal('none'), Type.Literal('project'), Type.Literal('global')], { default: 'global' }),
+  /** Knowledge store retrieval strategy (default: 'vector' — current hybrid dense+sparse behavior).
+   *  'vector' = hybrid search (embedding similarity + BM25/FTS fused via RRF; requires the
+   *  optional @huggingface/transformers dependency and a downloaded embedding model).
+   *  'bm25'   = pure lexical/BM25 retrieval over the same stored findings — NO embedding model:
+   *  never initialized, downloaded, or invoked. Uses a separate lexical table in the same
+   *  LanceDB database, so existing vector stores are untouched (no migration). */
+  KNOWLEDGE_STORE_RETRIEVAL: Type.Union([Type.Literal('vector'), Type.Literal('bm25')], { default: 'vector' }),
   /** Embedding model to use for the knowledge store */
   EMBEDDING_MODEL: Type.String({ default: 'onnx-community/granite-embedding-small-english-r2-ONNX' }),
   /** Hardware backend for embeddings: 'auto' (probe WebGPU viability out-of-process, fall back to CPU), 'webgpu' (force), or 'cpu' (force).
@@ -211,6 +218,7 @@ export const DEFAULTS: Config = Value.Create(ConfigSchema);
 const LOCAL_SCOPE_KEYS = new Set([
   'PI_RESEARCH_DEFAULT_RESEARCH_DEPTH',
   'PI_RESEARCH_KNOWLEDGE_STORE_MODE',
+  'PI_RESEARCH_KNOWLEDGE_STORE_RETRIEVAL',
 ]);
 
 /**
@@ -600,6 +608,10 @@ export interface KnowledgeStoreModeInfo {
   mode: 'none' | 'project' | 'global';
   /** Human-readable source of the EFFECTIVE value (highest-precedence source that set it). */
   origin: string;
+  /** Knowledge store retrieval strategy ('vector' hybrid — default, or 'bm25' lexical-only). */
+  retrieval: 'vector' | 'bm25';
+  /** Human-readable source of the EFFECTIVE retrieval value (same precedence walk as `origin`). */
+  retrievalOrigin: string;
   /** Physical LanceDB directory backing the store (shared across project/global modes). */
   dbDir: string;
   /**
@@ -627,34 +639,40 @@ export function describeKnowledgeStoreMode(
   iface?: ConfigInterface,
 ): KnowledgeStoreModeInfo {
   const cfg = getConfig(cwd, iface);
-  const KEY = 'PI_RESEARCH_KNOWLEDGE_STORE_MODE';
-  const fileHasKey = (p: string): boolean => {
+  const fileHasKey = (key: string, p: string): boolean => {
     try {
-      return fs.existsSync(p) && parseDotEnv(fs.readFileSync(p, 'utf-8'))[KEY] !== undefined;
+      return fs.existsSync(p) && parseDotEnv(fs.readFileSync(p, 'utf-8'))[key] !== undefined;
     } catch {
       return false;
     }
   };
 
-  let origin = 'built-in default';
-  if (process.env[KEY] !== undefined) {
-    origin = 'environment variable';
-  } else {
+  /**
+   * Walk the same precedence createConfig applies, highest first, for one env key:
+   *   env var  >  per-directory project registry  >  {iface}.env overlay  >  config.env  >  default.
+   */
+  const originFor = (KEY: string): string => {
+    if (process.env[KEY] !== undefined) {
+      return 'environment variable';
+    }
     let registryHasKey = false;
     try {
       const registry = loadProjectSettingsRegistry();
       registryHasKey = findRegistryEntry(registry, normalizeWorkspacePath(cwd))?.[KEY] !== undefined;
     } catch { /* unreadable registry → not the origin */ }
-    if (registryHasKey) origin = 'this directory (project settings)';
-    else if (iface && fileHasKey(getInterfaceEnvFilePath(iface))) origin = `${iface}.env overlay`;
-    else if (fileHasKey(getGlobalEnvFilePath())) origin = 'config.env (machine-wide default)';
-  }
+    if (registryHasKey) return 'this directory (project settings)';
+    if (iface && fileHasKey(KEY, getInterfaceEnvFilePath(iface))) return `${iface}.env overlay`;
+    if (fileHasKey(KEY, getGlobalEnvFilePath())) return 'config.env (machine-wide default)';
+    return 'built-in default';
+  };
 
   return {
     mode: cfg.KNOWLEDGE_STORE_MODE,
-    origin,
+    origin: originFor('PI_RESEARCH_KNOWLEDGE_STORE_MODE'),
+    retrieval: cfg.KNOWLEDGE_STORE_RETRIEVAL,
+    retrievalOrigin: originFor('PI_RESEARCH_KNOWLEDGE_STORE_RETRIEVAL'),
     dbDir: getDbDir(cfg, cwd),
-    ...availabilityFields(),
+    ...availabilityFields(cfg),
   };
 }
 
@@ -665,8 +683,8 @@ export function describeKnowledgeStoreMode(
  * throws: the probe catches resolution errors internally and reports them as
  * `available: false`.
  */
-function availabilityFields(): { available: boolean; unavailableReason: string } {
-  const availability = probeKnowledgeStoreAvailability();
+function availabilityFields(cfg?: Config): { available: boolean; unavailableReason: string } {
+  const availability = probeKnowledgeStoreAvailability(cfg?.KNOWLEDGE_STORE_RETRIEVAL ?? getConfig().KNOWLEDGE_STORE_RETRIEVAL);
   return {
     available: availability.available,
     unavailableReason: describeKnowledgeStoreUnavailability(availability),
@@ -924,6 +942,7 @@ export function saveConfig(config: Config, scope: 'local' | 'user' = 'local', cw
     PI_RESEARCH_WORKER_THREADS: String(config.WORKER_THREADS),
     PI_RESEARCH_WORKER_CONCURRENCY: String(config.WORKER_CONCURRENCY),
     PI_RESEARCH_KNOWLEDGE_STORE_MODE: config.KNOWLEDGE_STORE_MODE,
+    PI_RESEARCH_KNOWLEDGE_STORE_RETRIEVAL: config.KNOWLEDGE_STORE_RETRIEVAL,
     PI_RESEARCH_EMBEDDING_MODEL: config.EMBEDDING_MODEL,
     PI_RESEARCH_EMBEDDING_DEVICE: config.EMBEDDING_DEVICE,
     PI_RESEARCH_SCRAPE_TIMEOUT_MS: String(config.SCRAPE_TIMEOUT_MS),
@@ -1147,6 +1166,7 @@ export function createConfig(env: Record<string, string | undefined>, processEnv
     WORKER_THREADS: parseEnvNumber(e, 'PI_RESEARCH_WORKER_THREADS', DEFAULTS.WORKER_THREADS, 1, 10, true),
     WORKER_CONCURRENCY: parseEnvNumber(e, 'PI_RESEARCH_WORKER_CONCURRENCY', DEFAULTS.WORKER_CONCURRENCY, 1, 10, true),
     KNOWLEDGE_STORE_MODE: parseEnvEnum(e, 'PI_RESEARCH_KNOWLEDGE_STORE_MODE', ['none', 'project', 'global'] as const, 'global'),
+    KNOWLEDGE_STORE_RETRIEVAL: parseEnvEnum(e, 'PI_RESEARCH_KNOWLEDGE_STORE_RETRIEVAL', ['vector', 'bm25'] as const, 'vector'),
     EMBEDDING_MODEL: parseEnvString(e, 'PI_RESEARCH_EMBEDDING_MODEL', DEFAULTS.EMBEDDING_MODEL)!,
     EMBEDDING_DEVICE: parseEnvEnum(e, 'PI_RESEARCH_EMBEDDING_DEVICE', ['auto', 'webgpu', 'cpu'] as const, DEFAULTS.EMBEDDING_DEVICE),
     SCRAPE_TIMEOUT_MS: parseEnvNumber(e, 'PI_RESEARCH_SCRAPE_TIMEOUT_MS', DEFAULTS.SCRAPE_TIMEOUT_MS, 5000, 120000),

package/src/core/pi-version.ts

@@ -7,7 +7,7 @@
  *
  *   - As a pi EXTENSION, the host supplies `@earendil-works/*`. Our package.json
  *     range never constrains it, so an in-process check is the only enforcement.
- *   - As a standalone CLI/SDK, the range is `>=0.85.0 <1` and published tarballs
+ *   - As a standalone CLI/SDK, the range is `>=0.87.0 <1` and published tarballs
  *     carry no lockfile, so every fresh install resolves the newest 0.x at that
  *     instant. pi is pre-1.0: a minor bump may break anything under semver, and
  *     already has (0.83.0 extended the ResourceLoader contract).
@@ -74,8 +74,17 @@ export function compareVersions(a: SemverParts, b: SemverParts): number {
  * indefinite-hang-in-network-restricted-environments bug that explicit
  * option originally existed to prevent. The floor moved to close that gap,
  * not just because the type changed.
+ *
+ * 0.86.0 changed the pi-ai provider stream input from Context to normalized
+ * TranscriptContext values, restricted ToolCall.arguments / ToolResultMessage
+ * details to JSON-compatible values, and made user_bash fail closed; 0.87.0
+ * added ContextEditEntry to the SessionEntry union, made SessionManager the
+ * canonical provider-context source, and replaced shouldStopAfterTurn with the
+ * finishTurn boundary. The SDK paths (session service, model-registry factory)
+ * are written against that surface; an older host may resolve but is not a
+ * tested or supported target.
  */
-export const PI_MIN_VERSION: SemverParts = { major: 0, minor: 85, patch: 0 };
+export const PI_MIN_VERSION: SemverParts = { major: 0, minor: 87, patch: 0 };
 
 /**
  * Newest host line this release was actually exercised against (CI + a real run).
@@ -83,7 +92,7 @@ export const PI_MIN_VERSION: SemverParts = { major: 0, minor: 85, patch: 0 };
  * Compared on MAJOR.MINOR only: a patch bump within a tested line is not a new
  * surface, and warning on it would be noise.
  */
-export const PI_TESTED_MAX_VERSION: SemverParts = { major: 0, minor: 85, patch: 0 };
+export const PI_TESTED_MAX_VERSION: SemverParts = { major: 0, minor: 87, patch: 0 };
 
 export type PiCompatibilityLevel = 'ok' | 'unparseable' | 'too-old' | 'untested';
 

package/src/healthcheck/index.ts

@@ -196,8 +196,25 @@ export function registerHealthChecks(registry: IHealthRegistryService, container
       }
       const store = await service.getStore();
       const counts = store ? await store.countScoped() : { local: 0, global: 0, projects: 0 };
+      const retrieval = getConfig(service.getCwd()).KNOWLEDGE_STORE_RETRIEVAL;
       const embedder = await service.getEmbedder();
 
+      if (retrieval === 'bm25') {
+        // Lexical mode: no embedding model exists — null is the healthy state, not
+        // a failure. Report BM25-specific diagnostics instead of the embedder's.
+        return {
+            healthy: true,
+            diagnostic: {
+                status: 'initialized',
+                retrieval: 'bm25',
+                model: 'none (lexical BM25)',
+                localEntries: counts.local,
+                globalEntries: counts.global,
+                totalProjects: counts.projects
+            }
+        };
+      }
+
       if (!embedder) {
         return { healthy: false, error: 'Embedder service not available' };
       }
@@ -240,6 +257,7 @@ export function registerHealthChecks(registry: IHealthRegistryService, container
           healthy: true, 
           diagnostic: { 
               status: 'initialized',
+              retrieval,
               device,
               model: config.EMBEDDING_MODEL,
               localEntries: counts.local,

package/src/index.ts

@@ -91,10 +91,11 @@ function extractResultText(result: AgentToolResult<unknown>): string {
  * Pi Research Extension
  */
 export default async function (pi: ExtensionAPI) {
-  // Runtime version check — must match the @earendil-works/* dependency minimum (>=0.85.0).
+  // Runtime version check — must match the @earendil-works/* dependency minimum (>=0.87.0).
   // The floor was raised to 0.84.0 because setRuntimeApiKey() lost its `allowNetwork` option
   // there and only 0.84.0+ hardcodes the equivalent guard internally (see pi-version.ts), then
-  // to 0.85.0 to track the pi extension package line. The
+  // to 0.85.0 to track the pi extension package line, and to 0.87.0 for the 0.86
+  // TranscriptContext / 0.87 SessionEntry-union surface (see pi-version.ts). The
   // APIs it rests on arrived in 0.80.8, which introduced ModelRuntime and removed
   // AuthStorage/ModelRegistry.create(); buildModelRegistry (model-registry-factory.ts)
   // unconditionally calls ModelRuntime.create(), and createAgentSession() is invoked

package/src/infrastructure/browser/thread-worker.mjs

@@ -2699,6 +2699,13 @@ var ConfigSchema = Type.Object({
   WORKER_CONCURRENCY: Type.Number({ minimum: 1, maximum: 10, default: 2 }),
   /** Knowledge store isolation mode (default: 'global' — one shared store across every directory) */
   KNOWLEDGE_STORE_MODE: Type.Union([Type.Literal("none"), Type.Literal("project"), Type.Literal("global")], { default: "global" }),
+  /** Knowledge store retrieval strategy (default: 'vector' — current hybrid dense+sparse behavior).
+   *  'vector' = hybrid search (embedding similarity + BM25/FTS fused via RRF; requires the
+   *  optional @huggingface/transformers dependency and a downloaded embedding model).
+   *  'bm25'   = pure lexical/BM25 retrieval over the same stored findings — NO embedding model:
+   *  never initialized, downloaded, or invoked. Uses a separate lexical table in the same
+   *  LanceDB database, so existing vector stores are untouched (no migration). */
+  KNOWLEDGE_STORE_RETRIEVAL: Type.Union([Type.Literal("vector"), Type.Literal("bm25")], { default: "vector" }),
   /** Embedding model to use for the knowledge store */
   EMBEDDING_MODEL: Type.String({ default: "onnx-community/granite-embedding-small-english-r2-ONNX" }),
   /** Hardware backend for embeddings: 'auto' (probe WebGPU viability out-of-process, fall back to CPU), 'webgpu' (force), or 'cpu' (force).

package/src/infrastructure/knowledge-store-service.ts

@@ -50,6 +50,10 @@ export class KnowledgeStoreService implements IKnowledgeStoreService {
   // mode change (project↔global re-scope, or enabled→none) and re-initialize so a /research-config
   // change applies without a Pi restart — not just the DISABLED→enabled revival.
   private _initializedMode: string | undefined = undefined;
+  // The retrieval strategy the current build reflects ('vector' hybrid / 'bm25'
+  // lexical) — drives the embedder-optional invariants below and the live
+  // re-init detection on a /research-config retrieval change.
+  private _initializedRetrieval: 'vector' | 'bm25' | undefined = undefined;
 
   // Initialization promise to prevent concurrent initialization
   private _initializationPromise: Promise<void> | null = null;
@@ -88,7 +92,12 @@ export class KnowledgeStoreService implements IKnowledgeStoreService {
     //  - INITIALIZED and mode != the built mode        : project↔global re-scope, or enabled→'none'.
     // A native-unavailable DISABLED ('native') stays memoized — retrying is futile on that platform.
     if ((this.lifecycle === ServiceLifecycle.INITIALIZED || this.lifecycle === ServiceLifecycle.DISABLED) && this._cwd === newCwd) {
-      const liveMode: string = (ctx?.config || getConfig(this._cwd)).KNOWLEDGE_STORE_MODE;
+      const liveConfig = ctx?.config || getConfig(this._cwd);
+      const liveMode: string = liveConfig.KNOWLEDGE_STORE_MODE;
+      // Retrieval strategy ('vector' hybrid / 'bm25' lexical) participates in the same
+      // live-change detection: a /research-config switch must re-scope the store onto
+      // the OTHER table (lexical vs vector schema) without a Pi restart.
+      const liveRetrieval: string = liveConfig.KNOWLEDGE_STORE_RETRIEVAL;
       // Reviving a DISABLED store creates handles (no live state to tear down), so it is safe even
       // from a lazy call and uses the live config. Re-scoping/disabling a LIVE (INITIALIZED) store,
       // however, disposes handles — restrict that to an EXPLICIT ctx.config (mirrors the ctx.cwd
@@ -101,10 +110,15 @@ export class KnowledgeStoreService implements IKnowledgeStoreService {
         ctx?.config !== undefined &&
         this._initializedMode !== undefined &&
         this._initializedMode !== ctx.config.KNOWLEDGE_STORE_MODE;
-      if (!reviveFromMode && !modeChanged) {
+      const retrievalChanged =
+        this.lifecycle === ServiceLifecycle.INITIALIZED &&
+        ctx?.config !== undefined &&
+        this._initializedRetrieval !== undefined &&
+        this._initializedRetrieval !== ctx.config.KNOWLEDGE_STORE_RETRIEVAL;
+      if (!reviveFromMode && !modeChanged && !retrievalChanged) {
         return;
       }
-      logger.log(`[KnowledgeStoreService] Knowledge Mode changed (${this._initializedMode ?? this._disabledReason} → ${liveMode}); re-initializing store (no restart needed).`);
+      logger.log(`[KnowledgeStoreService] Knowledge config changed (${this._initializedMode ?? this._disabledReason} → ${liveMode}, retrieval ${this._initializedRetrieval ?? '?'} → ${liveRetrieval}); re-initializing store (no restart needed).`);
       // An INITIALIZED store holds live handles (embedder/LanceDB/writer) — dispose before rebuilding.
       if (this.lifecycle === ServiceLifecycle.INITIALIZED) {
         await this.dispose();
@@ -170,6 +184,7 @@ export class KnowledgeStoreService implements IKnowledgeStoreService {
         const config = ctx?.config || getConfig(this._cwd);
         // Record the mode this build reflects so a later runtime mode change is detected above.
         this._initializedMode = config.KNOWLEDGE_STORE_MODE;
+        this._initializedRetrieval = config.KNOWLEDGE_STORE_RETRIEVAL;
         const embedderFactory = () => getEmbedder(config);
         const reconnectFactory = async () => {
           // MUST await: clearEmbeddingInstance() only nulls the cached instance AFTER its
@@ -260,7 +275,7 @@ export class KnowledgeStoreService implements IKnowledgeStoreService {
           //    calls don't re-run init, and so the healthcheck/config surfaces
           //    report the package-level reason rather than a user choice the user
           //    never made.
-          const depsMissing = !probeKnowledgeStoreAvailability().available;
+          const depsMissing = !probeKnowledgeStoreAvailability(config.KNOWLEDGE_STORE_RETRIEVAL).available;
           logger.debug(`[KnowledgeStoreService] Knowledge store is disabled (${depsMissing ? 'dependencies missing' : 'mode = none'}). Setting lifecycle to DISABLED.`);
           this.lifecycle = ServiceLifecycle.DISABLED;
           this._disabledReason = depsMissing ? 'native' : 'mode';
@@ -431,6 +446,11 @@ export class KnowledgeStoreService implements IKnowledgeStoreService {
    * Check if the knowledge store is ready
    */
   isReady(): boolean {
+    // bm25 mode has no embedder by design — the store+writer pair is the readiness
+    // contract there. Vector mode keeps the original three-way check.
+    if (this._initializedRetrieval === 'bm25') {
+      return this._store !== null && this._writerQueue !== null;
+    }
     return this._embedder !== null && this._store !== null && this._writerQueue !== null;
   }
 
@@ -458,6 +478,11 @@ export class KnowledgeStoreService implements IKnowledgeStoreService {
     if (this.lifecycle === ServiceLifecycle.DISABLED) {
       return null;
     }
+    if (this._initializedRetrieval === 'bm25') {
+      // Lexical mode has no embedder — null is the CORRECT answer here, not an
+      // error. Callers must treat it as 'no embedding model configured'.
+      return null;
+    }
     if (!this._embedder) {
       throw new Error('[KnowledgeStoreService] Embedder not initialized');
     }