gnosys 5.13.1 → 5.14.0

package/dist/cli.js

@@ -1307,6 +1307,15 @@ program
     const { runRecallCommand } = await import("./lib/recallCommand.js");
     await runRecallCommand(query, opts);
 });
+// ─── gnosys recall-hook ──────────────────────────────────────────────────
+program
+    .command("recall-hook")
+    .description("Claude Code hook entry — reads the hook event JSON from stdin and prints a <gnosys-recall> context block. Wired automatically by gnosys init into UserPromptSubmit + SessionStart.")
+    .option("--limit <n>", "Max memories to inject (default from config)")
+    .action(async (opts) => {
+    const { runRecallHookCommand } = await import("./lib/recallHookCommand.js");
+    await runRecallHookCommand(opts);
+});
 // ─── gnosys audit ────────────────────────────────────────────────────────
 program
     .command("audit")
@@ -1855,10 +1864,13 @@ if (!isTestEnv()) {
             // console.log during boot corrupts the protocol and the host (Grok, Codex,
             // etc.) sees the server as [unavailable]. Suppress the nag in serve mode.
             const isServeCmd = process.argv.slice(2).some(a => a === "serve");
+            // v5.14.0: recall-hook runs on every Claude Code prompt — keep its
+            // stderr quiet too so hook error logs stay clean.
+            const isHookCmd = process.argv.slice(2).some(a => a === "recall-hook");
             // v5.9.3 Phase H: fire on any mismatch (upgrade OR downgrade).
             const mismatch = lastVersion !== null && lastVersion !== undefined &&
                 compareSemver(currentVersion, lastVersion) !== 0;
-            if (mismatch && !isUpgradeCmd && !isSetupSyncCmd && !isServeCmd) {
+            if (mismatch && !isUpgradeCmd && !isSetupSyncCmd && !isServeCmd && !isHookCmd) {
                 // v5.9.3 Phase H: emit on STDERR (was stdout). Safer invariant per
                 // deci-045 — stdout is reserved for command output.
                 const isMajorOrMinor = (() => {

package/dist/index.js

@@ -2246,7 +2246,7 @@ async function reindexAllStores() {
 //
 // Priority 1 + audience: assistant = hosts inject this before every message.
 regResource("gnosys_recall", "gnosys://recall", {
-    description: "Automatic memory injection. Hosts read this resource on every turn to inject the most relevant memories as context. Returns a <gnosys-recall> block with [[wikilinks]] and relevance scores. Priority 1 (highest) — designed for always-on context injection without any tool call. Configure aggressiveness in gnosys.json: recall.aggressive (default: true).",
+    description: "Top-memory injection block for hosts that read MCP resources. Returns a <gnosys-recall> block with [[wikilinks]] and relevance scores. NOTE: most hosts (Claude Code, Cursor) do NOT auto-read MCP resources per turn — for true automatic injection use the hooks `gnosys init` installs (UserPromptSubmit/SessionStart → `gnosys recall-hook`). Configure aggressiveness in gnosys.json: recall.aggressive (default: true).",
     mimeType: "text/markdown",
     annotations: {
         audience: ["assistant"],
@@ -2294,7 +2294,7 @@ regResource("gnosys_recall", "gnosys://recall", {
 // ─── Tool: gnosys_recall (query-specific fallback) ──────────────────────
 // For hosts that don't support MCP Resources, or when the agent wants to
 // recall memories for a specific query. The resource above is preferred.
-regTool("gnosys_recall", "Fast memory recall — inject relevant memories as context. Returns <gnosys-recall> block. In aggressive mode (default), always returns top memories even at medium relevance. Prefer the gnosys://recall MCP Resource for automatic injection (no tool call needed).", {
+regTool("gnosys_recall", "Fast memory recall — inject relevant memories as context. Returns <gnosys-recall> block. In aggressive mode (default), always returns top memories even at medium relevance. A wildcard query ('*') returns the top memories by reinforcement/confidence/recency. Hosts with gnosys hooks installed (via gnosys init) already get this automatically per prompt.", {
     query: z
         .string()
         .describe("What the agent is currently working on. Use keywords. Example: 'auth JWT middleware' or 'database migration schema'"),

package/dist/lib/projectIdentity.js

@@ -202,29 +202,61 @@ export async function configureClaudeCode(projectDir) {
     catch {
         // No settings yet
     }
-    // Build the Gnosys SessionStart hook
+    // v5.14.0: the hook command is `gnosys recall-hook` — it reads the hook
+    // event JSON from stdin (per the Claude Code hooks contract) and prints
+    // a <gnosys-recall> block, which Claude Code adds to the model context.
+    // Pre-5.14 installs wrote `gnosys recall --query ... --projectRoot ...`,
+    // options that never existed — the hook failed silently on every
+    // session start. Detect and heal that shape below.
+    const hookCommand = "gnosys recall-hook 2>/dev/null || true";
     const gnosysHook = {
         type: "command",
-        command: "gnosys recall --query \"session start\" --projectRoot \"$CLAUDE_PROJECT_DIR\" 2>/dev/null || true",
+        command: hookCommand,
         timeout: 10,
     };
-    // Merge into existing hooks without clobbering other SessionStart hooks
+    const isGnosysHookCmd = (h) => typeof h.command === "string" &&
+        (h.command.includes("gnosys recall-hook") ||
+            // the exact broken pre-5.14 shape only — a user's own `gnosys recall
+            // <topic>` hook must not count as "already configured"
+            h.command.includes("gnosys recall --query"));
+    const isBrokenLegacyCmd = (h) => typeof h.command === "string" && h.command.includes("gnosys recall --query");
+    // Merge into existing hooks without clobbering other entries
     const hooks = (settings.hooks || {});
+    let changed = false;
+    // Heal the broken legacy command wherever it appears
+    for (const eventName of Object.keys(hooks)) {
+        for (const entry of (hooks[eventName] || [])) {
+            const entryHooks = (entry.hooks || []);
+            for (const h of entryHooks) {
+                if (isBrokenLegacyCmd(h)) {
+                    h.command = hookCommand;
+                    changed = true;
+                }
+            }
+        }
+    }
+    // SessionStart: top memories at startup/resume/compact
     const sessionStartEntries = (hooks.SessionStart || []);
-    // Check if a Gnosys hook already exists
-    const hasGnosysHook = sessionStartEntries.some((entry) => {
-        const entryHooks = (entry.hooks || []);
-        return entryHooks.some((h) => typeof h.command === "string" && h.command.includes("gnosys recall"));
-    });
-    if (!hasGnosysHook) {
-        sessionStartEntries.push({
-            matcher: "startup|resume|compact",
-            hooks: [gnosysHook],
-        });
+    const hasSessionHook = sessionStartEntries.some((entry) => (entry.hooks || []).some(isGnosysHookCmd));
+    if (!hasSessionHook) {
+        sessionStartEntries.push({ matcher: "startup|resume|compact", hooks: [gnosysHook] });
         hooks.SessionStart = sessionStartEntries;
+        changed = true;
+    }
+    // UserPromptSubmit: per-prompt recall with the prompt text as the query —
+    // this is the "automatic memory injection" path (no matcher: always fires)
+    const promptEntries = (hooks.UserPromptSubmit || []);
+    const hasPromptHook = promptEntries.some((entry) => (entry.hooks || []).some(isGnosysHookCmd));
+    if (!hasPromptHook) {
+        promptEntries.push({ hooks: [gnosysHook] });
+        hooks.UserPromptSubmit = promptEntries;
+        changed = true;
+    }
+    if (changed) {
         settings.hooks = hooks;
         await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
     }
+    const hasGnosysHook = !changed;
     // v5.8.4: also register the MCP server itself (not just the recall hook),
     // so `gnosys init` is a one-stop shop. Previously the user had to ALSO
     // run `gnosys setup` for agents to actually call gnosys MCP tools.
@@ -234,7 +266,9 @@ export async function configureClaudeCode(projectDir) {
         configured: true,
         filePath: settingsPath,
         details: [
-            hasGnosysHook ? "SessionStart hook already configured" : "Added SessionStart hook",
+            hasGnosysHook
+                ? "Recall hooks already configured"
+                : "Recall hooks configured (SessionStart + UserPromptSubmit → gnosys recall-hook)",
             mcpResult.success ? mcpResult.message : `MCP register skipped: ${mcpResult.message}`,
         ].join("; "),
     };

package/dist/lib/recall.d.ts

@@ -62,9 +62,10 @@ interface RecallMemory {
  */
 export declare function recall(query: string, options: {
     limit?: number;
-    search: GnosysSearch;
-    resolver: GnosysResolver;
-    storePath: string;
+    /** Optional in v5.14: callers on the DB fast path (hooks) skip the file-store deps. */
+    search?: GnosysSearch;
+    resolver?: GnosysResolver;
+    storePath?: string;
     traceId?: string;
     recallConfig?: RecallConfig;
     /** v2.0: When provided, recall uses SQLite directly — no filesystem reads */

package/dist/lib/recall.js

@@ -72,6 +72,17 @@ export async function recall(query, options) {
         return recallFromDb(query, options.gnosysDb, limit, cfg, options.traceId, options.pendingOverlay);
     }
     // ─── v1.x legacy path (filesystem + search.db) ────────────────────
+    // v5.14: DB-only callers (recall-hook) pass no file-store deps; without
+    // them and without a central DB there is nothing to search.
+    if (!options.search || !options.resolver) {
+        return {
+            memories: [],
+            totalActive: 0,
+            totalArchived: 0,
+            recallTimeMs: Math.round((performance.now() - start) * 100) / 100,
+            aggressive: cfg.aggressive,
+        };
+    }
     const memories = [];
     // Step 1: Fast keyword search on active memories (FTS5 — sub-10ms)
     const fetchLimit = Math.max(limit * 2, 15);
@@ -96,7 +107,7 @@ export async function recall(query, options) {
     }
     // Step 2: Archive fallback if active results are thin
     let totalArchived = 0;
-    if (memories.length < limit) {
+    if (memories.length < limit && options.storePath) {
         try {
             const archive = new GnosysArchive(options.storePath);
             if (archive.isAvailable()) {

package/dist/lib/recallCommand.js

@@ -70,7 +70,7 @@ export async function runRecallCommand(query, opts) {
         }
         return;
     }
-    // Legacy file-based recall
+    // Default recall path
     const resolver = new GnosysResolver();
     await resolver.resolve();
     const stores = resolver.getStores();
@@ -91,14 +91,29 @@ export async function runRecallCommand(query, opts) {
     // Build search index
     const search = new GnosysSearch(storePath);
     await search.addStoreMemories(stores[0].store);
-    const result = await recall(query, {
-        limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
-        search,
-        resolver,
-        storePath,
-        traceId: opts.traceId,
-        recallConfig,
-    });
+    // v5.14.0: recall from the central DB (the brain) like the MCP tool
+    // does — the CLI previously only searched the project file store, so
+    // `gnosys recall` (and the SessionStart hook built on it) returned
+    // nothing on DB-only installs. Snapshot-aware via clientReadResolve;
+    // falls back to the file-store path when no central DB exists.
+    const { resolveClientRead } = await import("./clientReadResolve.js");
+    const clientRead = resolveClientRead();
+    let result;
+    try {
+        result = await recall(query, {
+            limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+            search,
+            resolver,
+            storePath,
+            traceId: opts.traceId,
+            recallConfig,
+            gnosysDb: clientRead?.db,
+            pendingOverlay: clientRead?.pendingOverlay,
+        });
+    }
+    finally {
+        clientRead?.release();
+    }
     if (opts.json) {
         console.log(JSON.stringify(result, null, 2));
     }

package/dist/lib/recallHookCommand.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `gnosys recall-hook` — Claude Code hook entry point (v5.14.0).
+ *
+ * This is what makes "automatic memory injection" real: Claude Code never
+ * auto-reads MCP resources, but its hooks contract
+ * (code.claude.com/docs/en/hooks.md) adds a hook's plain stdout to the
+ * model context on exit 0. `gnosys init` wires this command into
+ * UserPromptSubmit (every prompt, query = the prompt text) and
+ * SessionStart (startup/resume/compact, wildcard = top memories).
+ *
+ * Contract obligations:
+ *  - FAST: runs on every prompt. DB fast path only — no file stores, no
+ *    embeddings, no model loads. (~150ms cold including node startup.)
+ *  - NEVER breaks the prompt: always exit 0; every failure is silent.
+ *  - Empty stdout when there is nothing to inject (no noise strings).
+ *  - Output stays well under the 10,000-char hook cap.
+ */
+export type HookEvent = {
+    hook_event_name?: string;
+    prompt_text?: string;
+    /** Older docs name the field `prompt`; accept both. */
+    prompt?: string;
+    source?: string;
+    cwd?: string;
+};
+/** Parse the hook event JSON into a recall query ("*" = top memories). */
+export declare function hookQueryFromStdin(raw: string): string;
+export declare function runRecallHookCommand(opts?: {
+    limit?: string;
+}): Promise<void>;

package/dist/lib/recallHookCommand.js

@@ -0,0 +1,85 @@
+/**
+ * `gnosys recall-hook` — Claude Code hook entry point (v5.14.0).
+ *
+ * This is what makes "automatic memory injection" real: Claude Code never
+ * auto-reads MCP resources, but its hooks contract
+ * (code.claude.com/docs/en/hooks.md) adds a hook's plain stdout to the
+ * model context on exit 0. `gnosys init` wires this command into
+ * UserPromptSubmit (every prompt, query = the prompt text) and
+ * SessionStart (startup/resume/compact, wildcard = top memories).
+ *
+ * Contract obligations:
+ *  - FAST: runs on every prompt. DB fast path only — no file stores, no
+ *    embeddings, no model loads. (~150ms cold including node startup.)
+ *  - NEVER breaks the prompt: always exit 0; every failure is silent.
+ *  - Empty stdout when there is nothing to inject (no noise strings).
+ *  - Output stays well under the 10,000-char hook cap.
+ */
+/** Max chars of the user prompt used as the recall query. */
+const MAX_QUERY_CHARS = 400;
+/** Keep comfortably under Claude Code's 10k hook-output cap. */
+const MAX_OUTPUT_CHARS = 8_000;
+/** Parse the hook event JSON into a recall query ("*" = top memories). */
+export function hookQueryFromStdin(raw) {
+    try {
+        const evt = JSON.parse(raw);
+        const prompt = evt.prompt_text ?? evt.prompt;
+        if (typeof prompt === "string" && prompt.trim().length > 0) {
+            return prompt.trim().slice(0, MAX_QUERY_CHARS);
+        }
+    }
+    catch {
+        // Not JSON (manual invocation / future contract change) — wildcard.
+    }
+    return "*";
+}
+async function readStdin(timeoutMs) {
+    if (process.stdin.isTTY)
+        return "";
+    return new Promise((resolve) => {
+        let data = "";
+        const timer = setTimeout(() => resolve(data), timeoutMs);
+        timer.unref?.();
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on("end", () => {
+            clearTimeout(timer);
+            resolve(data);
+        });
+        process.stdin.on("error", () => {
+            clearTimeout(timer);
+            resolve(data);
+        });
+    });
+}
+export async function runRecallHookCommand(opts = {}) {
+    try {
+        const raw = await readStdin(1_000);
+        const query = hookQueryFromStdin(raw);
+        const { resolveClientRead } = await import("./clientReadResolve.js");
+        const clientRead = resolveClientRead();
+        if (!clientRead)
+            return; // no central DB — inject nothing, exit 0
+        try {
+            const { recall, formatRecall } = await import("./recall.js");
+            const result = await recall(query, {
+                limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+                gnosysDb: clientRead.db,
+                pendingOverlay: clientRead.pendingOverlay,
+                traceId: "claude-code-hook",
+            });
+            if (result.memories.length === 0)
+                return; // empty stdout = no injection
+            const block = formatRecall(result);
+            process.stdout.write(block.length > MAX_OUTPUT_CHARS ? `${block.slice(0, MAX_OUTPUT_CHARS)}\n</gnosys-recall>\n` : `${block}\n`);
+        }
+        finally {
+            clientRead.release();
+        }
+    }
+    catch {
+        // Never fail the user's prompt over memory recall.
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gnosys",
-  "version": "5.13.1",
+  "version": "5.14.0",
   "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",