gnosys 5.15.3 → 5.17.0

package/README.md

@@ -51,7 +51,7 @@ That's the 60-second tour. **Everything else lives on [gnosys.ai](https://gnosys
 - **Central brain** — one `~/.gnosys/gnosys.db` unifies every project (project / user / global scopes). Sub-10ms reads, SQLite as the sole source of truth.
 - **Federated search** — tier-boosted hybrid (FTS5 keyword + semantic) search across scopes, with recency and reinforcement.
 - **MCP server** — `gnosys serve` exposes 50+ memory tools to any MCP client. Sandbox-first runtime keeps context cost near zero.
-- **Web Knowledge Base** — `gnosys web build` turns any site into a searchable index for serverless chatbots. Zero runtime deps.
+- **Web Knowledge Base** — `gnosys web build` turns any site into a searchable index for serverless chatbots, with optional build-time vectors for serverless-safe hybrid semantic search. Zero runtime deps.
 - **Dream Mode** — idle-time consolidation: confidence decay, summaries, relationship discovery. Never deletes — only suggests.
 - **Multi-machine sync** — share your brain across machines; conflict detection with skip-and-flag resolution.
 - **Obsidian export** — `gnosys export` regenerates a full vault with frontmatter, `[[wikilinks]]`, and graph data.

package/dist/cli.js

@@ -1788,6 +1788,9 @@ webCmd
     .option("--input <dir>", "Override knowledge directory")
     .option("--output <path>", "Override output file path")
     .option("--no-stop-words", "Disable stop-word filtering")
+    .option("--embeddings <provider>", "Also build gnosys-vectors.json (openai|voyage|local)")
+    .option("--embed-model <id>", "Override the embedding model")
+    .option("--no-expansions", "Skip LLM concept-expansion generation")
     .option("--json", "Output index stats as JSON")
     .action(async (opts) => {
     const { runWebBuildIndexCommand } = await import("./lib/webBuildIndexCommand.js");
@@ -1801,6 +1804,9 @@ webCmd
     .option("--no-llm", "Force structured mode (no LLM)")
     .option("--concurrency <n>", "Parallel processing limit", "3")
     .option("--dry-run", "Show what would change without writing files")
+    .option("--embeddings <provider>", "Also build gnosys-vectors.json (openai|voyage|local)")
+    .option("--embed-model <id>", "Override the embedding model")
+    .option("--no-expansions", "Skip LLM concept-expansion generation")
     .option("--json", "Output results as JSON")
     .action(async (opts) => {
     const { runWebBuildCommand } = await import("./lib/webBuildCommand.js");

package/dist/index.js

@@ -624,7 +624,7 @@ regTool("gnosys_list", "List memories across all stores, optionally filtered by
     }
 });
 // ─── Tool: gnosys_add ────────────────────────────────────────────────────
-regTool("gnosys_add", "Add a new memory from raw text — the server's LLM structures it into an atomic memory. For non-agent callers (scripts, cron); if you are an LLM agent, use gnosys_add_structured instead to avoid a redundant server-side LLM call. Writes to the project store by default. Use store='personal' for cross-project knowledge, or store='global' to explicitly write to shared org knowledge.", {
+regTool("gnosys_add", "DO NOT USE if you are an LLM agent — call gnosys_add_structured instead (you structure the memory yourself; no redundant server-side LLM call). This freeform tool is REJECTED by default over MCP and only works when the operator sets GNOSYS_ALLOW_FREEFORM_ADD=1 for genuine non-agent callers (scripts, cron). Writes to the project store by default. Use store='personal' for cross-project knowledge, or store='global' to explicitly write to shared org knowledge.", {
     input: z
         .string()
         .describe("Raw text input. Can be a decision, concept, fact, observation, or any knowledge."),
@@ -642,6 +642,29 @@ regTool("gnosys_add", "Add a new memory from raw text — the server's LLM struc
         .describe("Epistemic trust level"),
     projectRoot: projectRootParam,
 }, async ({ input, store: targetStore, author, authority, projectRoot }) => {
+    // Hard gate (2026-07-04 decision): every MCP caller in practice is an
+    // LLM agent, and agents must use gnosys_add_structured — the freeform
+    // path burns a second server-side LLM call and silently fails without
+    // a provider key. Reject by default with a redirect the agent can act
+    // on immediately. Genuine non-agent MCP callers opt in via env.
+    if (process.env.GNOSYS_ALLOW_FREEFORM_ADD !== "1") {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "gnosys_add is disabled for LLM agents. Call gnosys_add_structured instead — " +
+                        "structure the memory yourself and pass: title (string), category " +
+                        "(architecture|decisions|requirements|concepts|roadmap|landscape|open-questions), " +
+                        "tags (object of string arrays, e.g. { domain: ['auth'], type: ['decision'] }), " +
+                        "content (markdown body), relevance (space-separated keyword cloud for discovery), " +
+                        "plus the same store/author/authority/projectRoot values you passed here. " +
+                        "Retry now with gnosys_add_structured using the same input. " +
+                        "(Non-agent scripts can re-enable this tool with GNOSYS_ALLOW_FREEFORM_ADD=1.)",
+                },
+            ],
+            isError: true,
+        };
+    }
     const ctx = await resolveToolContext(projectRoot);
     const writeTarget = ctx.resolver.getWriteTarget(targetStore || undefined);
     if (!writeTarget) {
@@ -972,7 +995,7 @@ regTool("gnosys_init", "Initialize Gnosys in a project directory. Creates .gnosy
         content: [
             {
                 type: "text",
-                text: `Gnosys store ${action} at ${storePath}\n\nProject Identity:\n- ID: ${identity.projectId}\n- Name: ${identity.projectName}\n- Directory: ${identity.workingDirectory}\n- Agent rules target: ${identity.agentRulesTarget || "none detected"}\n- Central DB: ${centralDb?.isAvailable() ? "registered ✓" : "not available"}\n\n${isResync ? "Identity re-synced." : "Created:\n- gnosys.json (project identity)\n- .config/ (internal config)\n- tags.json (tag registry)"}${hookInfo}\n\nThe store is ready. Use gnosys_discover to find existing memories or gnosys_add to create new ones.`,
+                text: `Gnosys store ${action} at ${storePath}\n\nProject Identity:\n- ID: ${identity.projectId}\n- Name: ${identity.projectName}\n- Directory: ${identity.workingDirectory}\n- Agent rules target: ${identity.agentRulesTarget || "none detected"}\n- Central DB: ${centralDb?.isAvailable() ? "registered ✓" : "not available"}\n\n${isResync ? "Identity re-synced." : "Created:\n- gnosys.json (project identity)\n- .config/ (internal config)\n- tags.json (tag registry)"}${hookInfo}\n\nThe store is ready. Use gnosys_discover to find existing memories or gnosys_add_structured to create new ones.`,
             },
         ],
     };
@@ -2216,7 +2239,7 @@ regTool("gnosys_stores", "Debug tool — lists all detected Gnosys stores across
         // Usage hint
         lines.push("USAGE:");
         lines.push("  Pass projectRoot to any tool to target a specific project:");
-        lines.push('  e.g. gnosys_add({ projectRoot: "/path/to/my-project", ... })');
+        lines.push('  e.g. gnosys_add_structured({ projectRoot: "/path/to/my-project", ... })');
         return { content: [{ type: "text", text: lines.join("\n") }] };
     }
     catch (err) {

package/dist/lib/cleanup.js

@@ -21,28 +21,13 @@
 import fs from "fs/promises";
 import fsSync from "fs";
 import path from "path";
-import os from "os";
 import { createInterface } from "readline/promises";
 import { stdin, stdout } from "process";
-import { getProjectRegistryPath } from "./paths.js";
+import { getProjectRegistryPath, isTempProjectPath } from "./paths.js";
 import { safeQuestion } from "./setup/ui/safePrompt.js";
 import { Header } from "./setup/ui/header.js";
 import { Status } from "./setup/ui/status.js";
 import { c, color, glyph } from "./setup/ui/tokens.js";
-const TEMP_PREFIXES = [
-    "/tmp/",
-    "/private/tmp/",
-    "/var/folders/",
-    "/private/var/folders/",
-];
-function isTempPath(p) {
-    const resolved = path.resolve(p);
-    if (TEMP_PREFIXES.some((prefix) => resolved.startsWith(prefix)))
-        return true;
-    // Honor the system tmpdir too (covers $TMPDIR overrides on CI etc.).
-    const sysTmp = path.resolve(os.tmpdir()) + path.sep;
-    return resolved.startsWith(sysTmp);
-}
 function isAlive(p) {
     try {
         const stat = fsSync.statSync(path.join(p, ".gnosys"));
@@ -74,7 +59,7 @@ export async function classifyRegistryEntries() {
     const dead = [];
     const temp = [];
     for (const e of entries) {
-        if (isTempPath(e)) {
+        if (isTempProjectPath(e)) {
             temp.push(e);
         }
         else if (isAlive(e)) {

package/dist/lib/paths.d.ts

@@ -40,3 +40,4 @@ export declare function getProjectRegistryPath(): string;
  * machine-local counterpart. See machineConfig.ts.
  */
 export declare function getMachineConfigPath(): string;
+export declare function isTempProjectPath(p: string): boolean;

package/dist/lib/paths.js

@@ -23,6 +23,7 @@
  * reproduce the `path.join(os.homedir(), ".gnosys")` pattern inline.
  */
 import path from "path";
+import os from "os";
 export function getGnosysHome() {
     if (process.env.GNOSYS_HOME)
         return process.env.GNOSYS_HOME;
@@ -45,6 +46,13 @@ export function getSandboxDir() {
 function getConfigDir() {
     if (process.env.GNOSYS_CONFIG_DIR)
         return process.env.GNOSYS_CONFIG_DIR;
+    // GNOSYS_HOME redirects "everything gnosys-owned" (see header comment).
+    // Before this, tests that set GNOSYS_HOME still wrote the project
+    // registry into the user's REAL ~/.config/gnosys/projects.json — every
+    // test run leaked hundreds of /var/folders/... temp entries into it.
+    if (process.env.GNOSYS_HOME) {
+        return path.join(process.env.GNOSYS_HOME, "config");
+    }
     const home = process.env.HOME || process.env.USERPROFILE || "/tmp";
     return path.join(home, ".config", "gnosys");
 }
@@ -65,3 +73,24 @@ export function getProjectRegistryPath() {
 export function getMachineConfigPath() {
     return path.join(getConfigDir(), "machine.json");
 }
+/**
+ * True when a project path lives under a system temp location (/tmp,
+ * /var/folders, or os.tmpdir()). Such paths are transient — test
+ * scaffolding, throwaway scratch dirs — and must never be treated as
+ * durable registered projects. Shared by cleanup, registration, and
+ * sync-projects so all three agree on what "temp" means.
+ */
+const TEMP_PATH_PREFIXES = [
+    "/tmp/",
+    "/private/tmp/",
+    "/var/folders/",
+    "/private/var/folders/",
+];
+export function isTempProjectPath(p) {
+    const resolved = path.resolve(p);
+    if (TEMP_PATH_PREFIXES.some((prefix) => resolved.startsWith(prefix))) {
+        return true;
+    }
+    const sysTmp = path.resolve(os.tmpdir()) + path.sep;
+    return resolved.startsWith(sysTmp);
+}

package/dist/lib/resolver.js

@@ -9,7 +9,7 @@
  */
 import fs from "fs/promises";
 import path from "path";
-import { getProjectRegistryPath } from "./paths.js";
+import { getProjectRegistryPath, isTempProjectPath } from "./paths.js";
 import { GnosysStore } from "./store.js";
 /**
  * v5.9.1 (#98): read just the projectId from a project's gnosys.json
@@ -273,6 +273,16 @@ export class GnosysResolver {
      */
     async registerProject(projectDir) {
         const configPath = this.getRegistryPath();
+        // Never register temp-dir projects (/tmp, /var/folders, os.tmpdir())
+        // in the user's REAL registry — those are test scaffolding or scratch
+        // dirs that vanish, then linger as stale entries `gnosys setup
+        // sync-projects` counts forever. When GNOSYS_HOME / GNOSYS_CONFIG_DIR
+        // redirects the registry (tests, sandboxes), temp paths are allowed,
+        // since the whole registry is itself transient.
+        const registryIsIsolated = Boolean(process.env.GNOSYS_HOME) || Boolean(process.env.GNOSYS_CONFIG_DIR);
+        if (!registryIsIsolated && isTempProjectPath(projectDir)) {
+            return;
+        }
         let projects = [];
         try {
             const raw = await fs.readFile(configPath, "utf-8");

package/dist/lib/rulesGen.js

@@ -35,7 +35,7 @@ This project uses **Gnosys** for persistent memory via MCP. Gnosys uses a centra
 
 ### Write automatically
 
-- **Always write with \`gnosys_add_structured\`** — you are an LLM, so structure the memory yourself (title, category, tags, content, relevance) and pass the explicit fields. Do NOT use the freeform \`gnosys_add\`: it makes the Gnosys server run a *second, redundant* LLM call to structure your text and adds an external provider-key dependency that can fail silently. \`gnosys_add_structured\` makes no server-side model call. (Freeform \`gnosys_add\` exists only for non-agent callers — cron jobs, scripts — that cannot structure text themselves.)
+- **Always write with \`gnosys_add_structured\`** — you are an LLM, so structure the memory yourself (title, category, tags, content, relevance) and pass the explicit fields. NEVER call the freeform \`gnosys_add\`: the server **rejects it with an error** for MCP callers (it would run a second, redundant LLM call and depends on a provider key that can fail silently). \`gnosys_add_structured\` makes no server-side model call. (Freeform \`gnosys_add\` exists only for non-agent scripts/cron, which must set GNOSYS_ALLOW_FREEFORM_ADD=1.)
 - When user says "remember", "memorize", "save this", "note this down", "don't forget" — call \`gnosys_add_structured\`
 - When user states a decision or preference (even casually) — commit to \`decisions\` category
 - When user provides a spec or plan — commit BEFORE starting work
@@ -48,7 +48,7 @@ This project uses **Gnosys** for persistent memory via MCP. Gnosys uses a centra
 |--------|------|
 | Find memories | \`gnosys_discover\` (metadata) → \`gnosys_read\` (content) |
 | Search | \`gnosys_hybrid_search\` (best), \`gnosys_federated_search\` (cross-project), \`gnosys_search\` (keyword), \`gnosys_ask\` (Q&A) |
-| Write | \`gnosys_add_structured\` (explicit fields — **always use this as an agent**; no server-side LLM call). \`gnosys_add\` (freeform) is for non-agent callers only. |
+| Write | \`gnosys_add_structured\` (explicit fields — **always use this as an agent**; no server-side LLM call). \`gnosys_add\` (freeform) is rejected for MCP callers — non-agent scripts only. |
 | Update | \`gnosys_update\`, \`gnosys_reinforce\` (useful/not_relevant/outdated) |
 | Browse | \`gnosys_list\`, \`gnosys_lens\` (filtered), \`gnosys_tags\`, \`gnosys_graph\` |
 | Maintain | \`gnosys_maintain\`, \`gnosys_stale\`, \`gnosys_history\`, \`gnosys_dashboard\` |

package/dist/lib/setupSyncProjectsCommand.js

@@ -22,7 +22,11 @@ export async function runSetupSyncProjectsCommand(opts) {
     console.log("");
     // 1. Read registered projects from file registry AND central DB
     const home = process.env.HOME || process.env.USERPROFILE || "/tmp";
-    const registryPath = path.join(home, ".config", "gnosys", "projects.json");
+    const { getProjectRegistryPath, isTempProjectPath } = await import("./paths.js");
+    // Registry lives at ~/.config/gnosys/projects.json (or under
+    // GNOSYS_HOME/GNOSYS_CONFIG_DIR when isolated) — always resolved via
+    // the shared helper, never hand-rolled from HOME.
+    const registryPath = getProjectRegistryPath();
     let fileProjects = [];
     try {
         fileProjects = JSON.parse(await fs.readFile(registryPath, "utf-8"));
@@ -39,24 +43,46 @@ export async function runSetupSyncProjectsCommand(opts) {
         const centralDb = GnosysDB.openCentral();
         if (centralDb.isAvailable()) {
             const allProjects = centralDb.getAllProjects();
-            dbProjects = allProjects.map((p) => p.working_directory);
-            for (const p of allProjects)
+            // Purge temp-dir ghosts (leaked by test runs) from the central DB
+            // so they stop resurfacing in every future sync.
+            for (const p of allProjects) {
+                if (isTempProjectPath(p.working_directory)) {
+                    try {
+                        centralDb.deleteProject(p.id);
+                    }
+                    catch {
+                        // non-critical
+                    }
+                    continue;
+                }
+                dbProjects.push(p.working_directory);
                 titleByDir.set(p.working_directory, p.name);
+            }
             centralDb.close();
         }
     }
     catch {
         // non-critical
     }
-    // Merge: deduplicate by resolved path
+    // Merge: deduplicate by resolved path. Temp-dir entries (/tmp,
+    // /var/folders — leaked by old versions' test runs) are dropped here,
+    // BEFORE the count and the registry write-back. Previously they were
+    // only skipped inside the upgrade loop, so "syncing N registered
+    // projects" reported hundreds of ghosts and the write-back on line
+    // below re-persisted them forever.
     const seen = new Set();
     const projects = [];
+    let droppedTemp = 0;
     for (const p of [...fileProjects, ...dbProjects]) {
         const resolved = path.resolve(p);
-        if (!seen.has(resolved)) {
-            seen.add(resolved);
-            projects.push(resolved);
+        if (seen.has(resolved))
+            continue;
+        seen.add(resolved);
+        if (isTempProjectPath(resolved)) {
+            droppedTemp++;
+            continue;
         }
+        projects.push(resolved);
     }
     if (projects.length === 0) {
         console.log(" no registered projects found");
@@ -79,10 +105,7 @@ export async function runSetupSyncProjectsCommand(opts) {
     const skipped = [];
     const failed = [];
     for (const projectDir of projects) {
-        // Skip test/temp directories
-        if (projectDir.startsWith("/tmp/") || projectDir.startsWith("/private/tmp/") || projectDir.startsWith("/var/folders/") || projectDir.startsWith("/private/var/folders/")) {
-            continue;
-        }
+        // Temp/test directories were already filtered out of `projects`.
         const storePath = path.join(projectDir, ".gnosys");
         try {
             await fs.stat(storePath);
@@ -131,7 +154,8 @@ export async function runSetupSyncProjectsCommand(opts) {
     }
     // Stop the lead-in spinner now that the iteration is done. Resolved
     // before any per-section output so the cursor is on a fresh line.
-    syncSpinner.ok(`synced ${projects.length} registered projects`, `${upgraded.length} upgraded · ${skipped.length} skipped · ${failed.length} failed`);
+    syncSpinner.ok(`synced ${projects.length} registered projects`, `${upgraded.length} upgraded · ${skipped.length} skipped · ${failed.length} failed` +
+        (droppedTemp > 0 ? ` · ${droppedTemp} temp entries pruned` : ""));
     // 3. Update global agent rules
     try {
         let centralDb = null;

package/dist/lib/staticSearch.d.ts

@@ -13,6 +13,17 @@ export interface GnosysWebIndex {
     documentCount: number;
     documents: DocumentManifest[];
     invertedIndex: Record<string, IndexEntry[]>;
+    expansions?: Record<string, string[]>;
+}
+export interface GnosysWebVectors {
+    version: number;
+    model: string;
+    dims: number;
+    quantization: "int8";
+    generated: string;
+    scale: number;
+    offset: number;
+    vectors: Record<string, number[]>;
 }
 export interface DocumentManifest {
     id: string;
@@ -36,21 +47,40 @@ export interface SearchOptions {
     category?: string;
     tags?: string[];
     boostRecent?: boolean;
+    queryVector?: number[];
+    vectors?: GnosysWebVectors;
+    expectedModel?: string;
+    expandQuery?: boolean;
 }
 export interface SearchResult {
     document: DocumentManifest;
     score: number;
     matchedTokens: string[];
+    semanticScore?: number;
 }
 /**
  * Load a pre-computed Gnosys web index from a file path or raw JSON string.
  * Caches the result for repeated calls with the same source.
  */
 export declare function loadIndex(pathOrJson: string): GnosysWebIndex;
+/**
+ * Load pre-computed Gnosys web vectors from a file path or raw JSON string.
+ * Caches the result for repeated calls with the same source.
+ */
+export declare function loadVectors(pathOrJson: string): GnosysWebVectors;
 /**
  * Clear the cached index (useful for testing).
  */
 export declare function clearIndexCache(): void;
+/**
+ * Clear the cached vectors file (useful for testing).
+ */
+export declare function clearVectorsCache(): void;
+/**
+ * Cosine similarity for equal-dimension vectors. Returns 0 for zero-magnitude
+ * vectors or dimension mismatches.
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
 /**
  * Search the pre-computed index and return ranked results.
  */