gnosys 5.12.2 → 5.12.3

package/dist/index.js

@@ -1752,10 +1752,17 @@ regTool("gnosys_hybrid_search", "Search memories using hybrid keyword + semantic
         };
     }
     try {
-        const results = await hybridSearch.hybridSearch(query, limit || 15, mode || "hybrid");
+        const requestedMode = mode || "hybrid";
+        const results = await hybridSearch.hybridSearch(query, limit || 15, requestedMode);
+        // v5.12.3: hybrid used to degrade to keyword-only silently when the
+        // semantic leg can't run (embeddings are only built by gnosys_reindex,
+        // and DB mode also needs the store-local query embedder). Say so loudly.
+        const degradeWarning = requestedMode !== "keyword" && !hybridSearch.canRunSemantic()
+            ? `⚠️ Semantic embeddings unavailable — ${requestedMode} search ran keyword-only. Run gnosys_reindex to build embeddings and enable semantic recall.\n\n`
+            : "";
         if (results.length === 0) {
             return {
-                content: [{ type: "text", text: `No results for "${query}". Try gnosys_reindex to build embeddings, or different keywords.` }],
+                content: [{ type: "text", text: `${degradeWarning}No results for "${query}". Try different keywords.` }],
             };
         }
         const formatted = results
@@ -1774,7 +1781,7 @@ regTool("gnosys_hybrid_search", "Search memories using hybrid keyword + semantic
             content: [
                 {
                     type: "text",
-                    text: `Found ${results.length} results for "${query}" (${embCount} embeddings indexed):\n\n${formatted}`,
+                    text: `${degradeWarning}Found ${results.length} results for "${query}" (${embCount} embeddings indexed):\n\n${formatted}`,
                 },
             ],
         };
@@ -1802,10 +1809,19 @@ regTool("gnosys_semantic_search", "Search memories using semantic similarity onl
         };
     }
     try {
+        // v5.12.3: semantic search without a working semantic leg either
+        // returns nothing or (in DB mode) keyword hits mislabeled as semantic —
+        // refuse with the exact reason instead.
+        if (!hybridSearch.canRunSemantic()) {
+            return {
+                content: [{ type: "text", text: `⚠️ Semantic embeddings unavailable — semantic search cannot run. Run gnosys_reindex to build embeddings, then retry.` }],
+                isError: true,
+            };
+        }
         const results = await hybridSearch.hybridSearch(query, limit || 15, "semantic");
         if (results.length === 0) {
             return {
-                content: [{ type: "text", text: `No semantic results for "${query}". Run gnosys_reindex first to build embeddings.` }],
+                content: [{ type: "text", text: `No semantic results for "${query}". Try a broader query.` }],
             };
         }
         const formatted = results

package/dist/lib/archive.js

@@ -23,6 +23,7 @@ import { statSync } from "fs";
 import { syncMemoryToDb, syncDearchiveToDb } from "./dbWrite.js";
 import { enableWAL } from "./lock.js";
 import { auditLog } from "./audit.js";
+import { ftsTerms, ftsAndQuery, ftsOrQuery } from "./ftsQuery.js";
 // ─── Archive Manager ────────────────────────────────────────────────────
 export class GnosysArchive {
     db = null;
@@ -217,8 +218,8 @@ export class GnosysArchive {
     searchArchive(query, limit = 20) {
         if (!this.db)
             return [];
-        const safeQuery = query.replace(/['"]/g, "").trim();
-        if (!safeQuery)
+        const terms = ftsTerms(query);
+        if (terms.length === 0)
             return [];
         const stmt = this.db.prepare(`
       SELECT
@@ -235,7 +236,12 @@ export class GnosysArchive {
       LIMIT ?
     `);
         try {
-            return stmt.all(safeQuery, limit);
+            // v5.12.3: AND first (precision), OR retry when AND finds nothing —
+            // multi-word queries previously required every term to match.
+            const results = stmt.all(ftsAndQuery(terms), limit);
+            if (results.length > 0 || terms.length === 1)
+                return results;
+            return stmt.all(ftsOrQuery(terms), limit);
         }
         catch {
             // FTS5 query syntax failed — try LIKE fallback
@@ -251,7 +257,7 @@ export class GnosysArchive {
         WHERE content LIKE ? OR title LIKE ? OR tags LIKE ?
         LIMIT ?
       `);
-            const pattern = `%${safeQuery}%`;
+            const pattern = `%${terms.join(" ")}%`;
             return likeStmt.all(pattern, pattern, pattern, limit);
         }
     }

package/dist/lib/db.js

@@ -21,6 +21,7 @@ import { enableWAL } from "./lock.js";
 import { getGnosysHome as getGnosysHomeImpl, getCentralDbPath as getCentralDbPathImpl } from "./paths.js";
 import { readMachineConfig } from "./machineConfig.js";
 import { logError } from "./log.js";
+import { ftsTerms, ftsAndQuery, ftsOrQuery } from "./ftsQuery.js";
 import { ulid } from "ulidx";
 // ─── Schema ─────────────────────────────────────────────────────────────
 const SCHEMA_VERSION = 5;
@@ -1088,27 +1089,33 @@ export class GnosysDB {
     }
     // ─── FTS5 Search ────────────────────────────────────────────────────
     searchFts(query, limit = 20) {
-        const safeQuery = query.replace(/['"]/g, "").trim();
-        if (!safeQuery)
+        const terms = ftsTerms(query);
+        if (terms.length === 0)
             return [];
         // v5.8.0 (#7): join memories so callers can render project-prefixed IDs.
         return this.withRecovery(() => {
             try {
-                return this.prep(`
-        SELECT m.id AS id, m.title AS title,
-               snippet(memories_fts, 5, '>>>', '<<<', '...', 40) as snippet,
-               fts.rank AS rank,
-               m.project_id AS project_id
-        FROM memories_fts fts
-        JOIN memories m ON m.id = fts.id
-        WHERE memories_fts MATCH ?
-        ORDER BY fts.rank
-        LIMIT ?
-      `).all(safeQuery, limit);
+                const run = (match) => this.prep(`
+          SELECT m.id AS id, m.title AS title,
+                 snippet(memories_fts, 5, '>>>', '<<<', '...', 40) as snippet,
+                 fts.rank AS rank,
+                 m.project_id AS project_id
+          FROM memories_fts fts
+          JOIN memories m ON m.id = fts.id
+          WHERE memories_fts MATCH ?
+          ORDER BY fts.rank
+          LIMIT ?
+        `).all(match, limit);
+                // v5.12.3: AND first (precision), OR retry when AND finds nothing —
+                // multi-word queries previously required every term to match.
+                const results = run(ftsAndQuery(terms));
+                if (results.length > 0 || terms.length === 1)
+                    return results;
+                return run(ftsOrQuery(terms));
             }
             catch {
                 // FTS5 syntax error — fallback to LIKE
-                const pattern = `%${safeQuery}%`;
+                const pattern = `%${terms.join(" ")}%`;
                 return this.prep(`
         SELECT id, title, substr(content, 1, 200) as snippet, 0 as rank, project_id
         FROM memories WHERE content LIKE ? OR title LIKE ? OR tags LIKE ?
@@ -1118,8 +1125,8 @@ export class GnosysDB {
         });
     }
     discoverFts(query, limit = 20) {
-        const safeQuery = query.replace(/['"]/g, "").trim();
-        if (!safeQuery)
+        const terms = ftsTerms(query);
+        if (terms.length === 0)
             return [];
         // v5.7.1 (#14): join `memories` so callers can render project-prefixed IDs.
         const select = `
@@ -1130,26 +1137,37 @@ export class GnosysDB {
       ORDER BY fts.rank
       LIMIT ?
     `;
-        return this.withRecovery(() => {
+        // Let corruption escape to withRecovery (reopen + retry); plain FTS
+        // syntax failures still degrade gracefully to "no results".
+        const tryRun = (match) => {
             try {
-                const colQuery = `{relevance title tags} : ${safeQuery}`;
-                const results = this.prep(select).all(colQuery, limit);
-                if (results.length > 0)
-                    return results;
-                return this.prep(select).all(safeQuery, limit);
+                return this.prep(select).all(match, limit);
             }
-            catch {
-                try {
-                    return this.prep(select).all(safeQuery, limit);
-                }
-                catch (err) {
-                    // Let corruption escape to withRecovery (reopen + retry); plain FTS
-                    // syntax failures still degrade gracefully to "no results".
-                    if (GnosysDB.isCorruptionError(err))
-                        throw err;
-                    return [];
-                }
+            catch (err) {
+                if (GnosysDB.isCorruptionError(err))
+                    throw err;
+                return [];
             }
+        };
+        // v5.12.3: precision-to-recall ladder. AND on the metadata columns,
+        // AND anywhere, then OR retries — multi-word queries previously
+        // required every term to match, so long queries returned nothing.
+        // Parens scope the column filter to the whole expression (a bare
+        // `{cols} : a b` only filtered the first term).
+        const colScoped = (expr) => `{relevance title tags} : (${expr})`;
+        const andExpr = ftsAndQuery(terms);
+        return this.withRecovery(() => {
+            let results = tryRun(colScoped(andExpr));
+            if (results.length > 0)
+                return results;
+            results = tryRun(andExpr);
+            if (results.length > 0 || terms.length === 1)
+                return results;
+            const orExpr = ftsOrQuery(terms);
+            results = tryRun(colScoped(orExpr));
+            if (results.length > 0)
+                return results;
+            return tryRun(orExpr);
         });
     }
     // ─── Relationships ──────────────────────────────────────────────────

package/dist/lib/ftsQuery.d.ts

@@ -0,0 +1,25 @@
+/**
+ * FTS5 MATCH query construction — shared by the central-DB search (db.ts),
+ * the per-store search index (search.ts), and archive search (archive.ts).
+ *
+ * FTS5 treats space-separated bare terms as implicit AND, so the long
+ * descriptive queries the tool docs encourage ("auth JWT session tokens
+ * refresh") return zero results unless EVERY term matches. Callers use
+ * these helpers to try AND first (precision), then retry with OR
+ * (recall) when AND finds nothing — BM25 still ranks the best-covered
+ * memories first in the OR pass.
+ *
+ * Every term is emitted as a quoted phrase, which also makes previously
+ * syntax-error-prone input (hyphens, colons, FTS5 keywords like NOT)
+ * safe. A trailing `*` is preserved as an FTS5 prefix query (`"term"*`).
+ */
+/**
+ * Split a raw query into sanitized terms. Drops quote characters and any
+ * token with no letters or digits (pure punctuation can't match anything
+ * under the unicode61 tokenizer).
+ */
+export declare function ftsTerms(query: string): string[];
+/** Implicit-AND MATCH expression: all terms must match. */
+export declare function ftsAndQuery(terms: string[]): string;
+/** OR MATCH expression: any term may match; BM25 ranks fuller matches higher. */
+export declare function ftsOrQuery(terms: string[]): string;

package/dist/lib/ftsQuery.js

@@ -0,0 +1,42 @@
+/**
+ * FTS5 MATCH query construction — shared by the central-DB search (db.ts),
+ * the per-store search index (search.ts), and archive search (archive.ts).
+ *
+ * FTS5 treats space-separated bare terms as implicit AND, so the long
+ * descriptive queries the tool docs encourage ("auth JWT session tokens
+ * refresh") return zero results unless EVERY term matches. Callers use
+ * these helpers to try AND first (precision), then retry with OR
+ * (recall) when AND finds nothing — BM25 still ranks the best-covered
+ * memories first in the OR pass.
+ *
+ * Every term is emitted as a quoted phrase, which also makes previously
+ * syntax-error-prone input (hyphens, colons, FTS5 keywords like NOT)
+ * safe. A trailing `*` is preserved as an FTS5 prefix query (`"term"*`).
+ */
+/**
+ * Split a raw query into sanitized terms. Drops quote characters and any
+ * token with no letters or digits (pure punctuation can't match anything
+ * under the unicode61 tokenizer).
+ */
+export function ftsTerms(query) {
+    return query
+        .replace(/['"]/g, "")
+        .split(/\s+/)
+        .filter((t) => /[\p{L}\p{N}]/u.test(t));
+}
+/** Render one term as a safe FTS5 phrase, preserving trailing-`*` prefix queries. */
+function ftsPhrase(term) {
+    const prefixMatch = term.match(/^(.*?)\*+$/);
+    if (prefixMatch && /[\p{L}\p{N}]/u.test(prefixMatch[1])) {
+        return `"${prefixMatch[1]}"*`;
+    }
+    return `"${term}"`;
+}
+/** Implicit-AND MATCH expression: all terms must match. */
+export function ftsAndQuery(terms) {
+    return terms.map(ftsPhrase).join(" ");
+}
+/** OR MATCH expression: any term may match; BM25 ranks fuller matches higher. */
+export function ftsOrQuery(terms) {
+    return terms.map(ftsPhrase).join(" OR ");
+}

package/dist/lib/hybridSearch.d.ts

@@ -57,6 +57,15 @@ export declare class GnosysHybridSearch {
      * Check if embeddings are available.
      */
     hasEmbeddings(): boolean;
+    /**
+     * True when hybrid/semantic search can actually run its semantic leg.
+     * In DB mode this requires BOTH stored vectors in the central DB and the
+     * store-local embeddings.db used to embed the query text — the central
+     * count alone can be non-zero on a machine that only syncs gnosys.db,
+     * in which case hybridSearch() silently runs keyword-only (embedQuery
+     * is never constructed).
+     */
+    canRunSemantic(): boolean;
     /**
      * Get embedding count.
      */

package/dist/lib/hybridSearch.js

@@ -284,6 +284,20 @@ export class GnosysHybridSearch {
             return this.dbSearch.hasEmbeddings();
         return this.embeddings.hasEmbeddings();
     }
+    /**
+     * True when hybrid/semantic search can actually run its semantic leg.
+     * In DB mode this requires BOTH stored vectors in the central DB and the
+     * store-local embeddings.db used to embed the query text — the central
+     * count alone can be non-zero on a machine that only syncs gnosys.db,
+     * in which case hybridSearch() silently runs keyword-only (embedQuery
+     * is never constructed).
+     */
+    canRunSemantic() {
+        if (this.dbSearch) {
+            return this.dbSearch.hasEmbeddings() && this.embeddings.hasEmbeddings();
+        }
+        return this.embeddings.hasEmbeddings();
+    }
     /**
      * Get embedding count.
      */

package/dist/lib/hybridSearchCommand.js

@@ -67,6 +67,11 @@ export async function runHybridSearchCommand(getResolver, query, opts) {
     const embeddings = new GnosysEmbeddings(storePath);
     const hybridSearch = new GnosysHybridSearch(search, embeddings, resolver, storePath);
     const mode = opts.mode;
+    // v5.12.3: hybrid used to degrade to keyword-only silently when the
+    // semantic leg can't run. Warn on stderr so --json stdout stays clean.
+    if (mode !== "keyword" && !hybridSearch.canRunSemantic()) {
+        console.error(`⚠ Semantic embeddings unavailable — ${mode} search will run keyword-only. Run 'gnosys reindex' to build embeddings.`);
+    }
     const results = await hybridSearch.hybridSearch(query, parseInt(opts.limit, 10), mode);
     if (results.length === 0) {
         outputResult(!!opts.json, { query, mode, results: [] }, () => {

package/dist/lib/resolver.d.ts

@@ -46,6 +46,23 @@ export declare class GnosysResolver {
      * Discover and initialize all store layers.
      */
     resolve(): Promise<ResolvedStore[]>;
+    /**
+     * Load the env-configured store tiers (optional `GNOSYS_STORES`, personal
+     * `GNOSYS_PERSONAL`, global `GNOSYS_GLOBAL`) onto `this.stores`.
+     *
+     * Shared by {@link resolve} and {@link resolveForProject}: a per-tool
+     * `projectRoot` call must STILL see personal/global, otherwise cross-project
+     * and global memories are unreachable — you couldn't write `store: "global"`
+     * / `"personal"` nor read them back from another project. Since every tool
+     * is told to always pass `projectRoot`, omitting these here silently
+     * disabled the entire cross-project tier system.
+     *
+     * Global is loaded whenever `GNOSYS_GLOBAL` is set, creating its directory on
+     * demand (parity with personal) so a configured-but-empty global store still
+     * works. It remains write-only-when-explicitly-targeted: {@link getWriteTarget}
+     * never auto-selects it.
+     */
+    private loadEnvTiers;
     /**
      * Get all stores in precedence order.
      */

package/dist/lib/resolver.js

@@ -79,8 +79,13 @@ export class GnosysResolver {
             }
         }
         catch {
-            // Store doesn't exist at projectRoot — fall through to empty resolver
+            // No project store at projectRoot — still load the env tiers below.
         }
+        // Even when scoped to a projectRoot, load the personal/global/optional
+        // tiers so cross-project + global memories stay reachable (write store:
+        // "global"/"personal", and read them back from any project). Without this,
+        // the universal "always pass projectRoot" guidance silently disabled them.
+        await resolver.loadEnvTiers();
         return resolver;
     }
     /**
@@ -104,7 +109,30 @@ export class GnosysResolver {
                 path: projectPath,
             });
         }
-        // 2. Optional stores (GNOSYS_STORES — colon-separated)
+        // 2-4. Env-configured tiers (optional, personal, global). Shared with
+        //       resolveForProject so passing a projectRoot does NOT strip the
+        //       cross-project tiers.
+        await this.loadEnvTiers();
+        return this.stores;
+    }
+    /**
+     * Load the env-configured store tiers (optional `GNOSYS_STORES`, personal
+     * `GNOSYS_PERSONAL`, global `GNOSYS_GLOBAL`) onto `this.stores`.
+     *
+     * Shared by {@link resolve} and {@link resolveForProject}: a per-tool
+     * `projectRoot` call must STILL see personal/global, otherwise cross-project
+     * and global memories are unreachable — you couldn't write `store: "global"`
+     * / `"personal"` nor read them back from another project. Since every tool
+     * is told to always pass `projectRoot`, omitting these here silently
+     * disabled the entire cross-project tier system.
+     *
+     * Global is loaded whenever `GNOSYS_GLOBAL` is set, creating its directory on
+     * demand (parity with personal) so a configured-but-empty global store still
+     * works. It remains write-only-when-explicitly-targeted: {@link getWriteTarget}
+     * never auto-selects it.
+     */
+    async loadEnvTiers() {
+        // Optional stores (GNOSYS_STORES — colon-separated, read-only)
         const optionalPaths = process.env.GNOSYS_STORES;
         if (optionalPaths) {
             const paths = optionalPaths.split(":").filter(Boolean);
@@ -124,7 +152,7 @@ export class GnosysResolver {
                 }
             }
         }
-        // 3. Personal store (GNOSYS_PERSONAL)
+        // Personal store (GNOSYS_PERSONAL — writable fallback target)
         const personalPath = process.env.GNOSYS_PERSONAL;
         if (personalPath) {
             const p = path.resolve(personalPath);
@@ -138,24 +166,22 @@ export class GnosysResolver {
                 path: p,
             });
         }
-        // 4. Global store (GNOSYS_GLOBAL)
-        //    Writable, but only when explicitly targeted — never auto-selected.
+        // Global store (GNOSYS_GLOBAL — writable, but never auto-selected). Loaded
+        // whenever set; store.init() creates the dir on demand (parity with
+        // personal), so a configured-but-empty GNOSYS_GLOBAL still works.
         const globalPath = process.env.GNOSYS_GLOBAL;
         if (globalPath) {
             const p = path.resolve(globalPath);
-            if (await this.isValidStore(p)) {
-                const store = new GnosysStore(p);
-                await store.init();
-                this.stores.push({
-                    layer: "global",
-                    label: "global",
-                    store,
-                    writable: true,
-                    path: p,
-                });
-            }
+            const store = new GnosysStore(p);
+            await store.init();
+            this.stores.push({
+                layer: "global",
+                label: "global",
+                store,
+                writable: true,
+                path: p,
+            });
         }
-        return this.stores;
     }
     /**
      * Get all stores in precedence order.

package/dist/lib/search.js

@@ -11,6 +11,7 @@ catch {
     // better-sqlite3 native module not available — search degrades gracefully
 }
 import path from "path";
+import { ftsTerms, ftsAndQuery, ftsOrQuery } from "./ftsQuery.js";
 export class GnosysSearch {
     db = null;
     constructor(storePath) {
@@ -133,9 +134,8 @@ export class GnosysSearch {
     search(query, limit = 20) {
         if (!this.db)
             return [];
-        // FTS5 query — escape special characters
-        const safeQuery = query.replace(/['"]/g, "").trim();
-        if (!safeQuery)
+        const terms = ftsTerms(query);
+        if (terms.length === 0)
             return [];
         const stmt = this.db.prepare(`
       SELECT
@@ -149,7 +149,12 @@ export class GnosysSearch {
       LIMIT ?
     `);
         try {
-            return stmt.all(safeQuery, limit);
+            // v5.12.3: AND first (precision), OR retry when AND finds nothing —
+            // multi-word queries previously required every term to match.
+            const results = stmt.all(ftsAndQuery(terms), limit);
+            if (results.length > 0 || terms.length === 1)
+                return results;
+            return stmt.all(ftsOrQuery(terms), limit);
         }
         catch {
             // If FTS5 query fails, fall back to simple LIKE search
@@ -163,7 +168,7 @@ export class GnosysSearch {
         WHERE content LIKE ? OR title LIKE ? OR tags LIKE ?
         LIMIT ?
       `);
-            const pattern = `%${safeQuery}%`;
+            const pattern = `%${terms.join(" ")}%`;
             return likeStmt.all(pattern, pattern, pattern, limit);
         }
     }
@@ -175,8 +180,8 @@ export class GnosysSearch {
     discover(query, limit = 20) {
         if (!this.db)
             return [];
-        const safeQuery = query.replace(/['"]/g, "").trim();
-        if (!safeQuery)
+        const terms = ftsTerms(query);
+        if (terms.length === 0)
             return [];
         // Search primarily on relevance + title + tags (not content body)
         // FTS5 column filter: {relevance title tags}
@@ -191,24 +196,32 @@ export class GnosysSearch {
       ORDER BY rank
       LIMIT ?
     `);
-        try {
-            // Try column-filtered search on relevance/title/tags first
-            const colQuery = `{relevance title tags} : ${safeQuery}`;
-            const results = stmt.all(colQuery, limit);
-            if (results.length > 0)
-                return results;
-            // Fall back to full-text search if column filter finds nothing
-            return stmt.all(safeQuery, limit);
-        }
-        catch {
-            // If FTS5 column filter syntax fails, fall back to full search
+        const tryRun = (match) => {
             try {
-                return stmt.all(safeQuery, limit);
+                return stmt.all(match, limit);
             }
             catch {
                 return [];
             }
-        }
+        };
+        // v5.12.3: precision-to-recall ladder. AND on the metadata columns,
+        // AND anywhere, then OR retries — multi-word queries previously
+        // required every term to match, so long queries returned nothing.
+        // Parens scope the column filter to the whole expression (a bare
+        // `{cols} : a b` only filtered the first term).
+        const colScoped = (expr) => `{relevance title tags} : (${expr})`;
+        const andExpr = ftsAndQuery(terms);
+        let results = tryRun(colScoped(andExpr));
+        if (results.length > 0)
+            return results;
+        results = tryRun(andExpr);
+        if (results.length > 0 || terms.length === 1)
+            return results;
+        const orExpr = ftsOrQuery(terms);
+        results = tryRun(colScoped(orExpr));
+        if (results.length > 0)
+            return results;
+        return tryRun(orExpr);
     }
     close() {
         this.db?.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gnosys",
-  "version": "5.12.2",
+  "version": "5.12.3",
   "description": "Gnosys — Persistent Memory for AI Agents. Sandbox-first runtime, central SQLite brain, federated search, Dream Mode, Web Knowledge Base, Obsidian export.",
   "type": "module",
   "main": "dist/index.js",