pi-hermes-memory 0.8.1 → 0.9.0

package/src/store/sqlite-memory-store.ts

@@ -1,5 +1,11 @@
 import { DatabaseManager } from './db.js';
-import { buildFallbackFts5Query, isFts5QueryError, normalizeFts5Query } from './fts-query.js';
+import {
+  buildFallbackFts5Query,
+  buildNaturalLanguageFallbackQuery,
+  isFts5QueryError,
+  normalizeFts5Query,
+  normalizeNaturalLanguageFts5Query,
+} from './fts-query.js';
 import { normalizeMemoryLookupText } from './memory-lookup.js';
 import type { MemoryCategory } from '../types.js';
 
@@ -697,6 +703,8 @@ export function searchMemories(
     return [];
   }
 
+  let ftsParseError = false;
+
   const runSearch = (matchQuery: string): SqliteMemoryEntry[] => {
     const conditions: string[] = [];
     const params: unknown[] = [];
@@ -750,6 +758,7 @@ export function searchMemories(
       return rows.map(mapRow);
     } catch (err) {
       if (isFts5QueryError(err)) {
+        ftsParseError = true;
         return [];
       }
       throw err;
@@ -761,6 +770,26 @@ export function searchMemories(
     return exactResults;
   }
 
+  // A query with uppercase operator words (e.g. "DO NOT USE FIND /") passes
+  // through as raw FTS5 syntax; when that fails to parse, retry it as natural
+  // language instead of silently returning nothing. Valid operator queries
+  // that legitimately match nothing keep their exact semantics.
+  if (ftsParseError) {
+    const nlQuery = normalizeNaturalLanguageFts5Query(query);
+    if (nlQuery.length === 0 || nlQuery === normalizedQuery) {
+      return [];
+    }
+    const nlResults = runSearch(nlQuery);
+    if (nlResults.length > 0) {
+      return nlResults;
+    }
+    const nlFallback = buildNaturalLanguageFallbackQuery(query);
+    if (nlFallback && nlFallback !== nlQuery) {
+      return runSearch(nlFallback);
+    }
+    return nlResults;
+  }
+
   const fallbackQuery = buildFallbackFts5Query(query);
   if (!fallbackQuery || fallbackQuery === normalizedQuery) {
     return exactResults;

package/src/store/sqlite-native.ts

@@ -0,0 +1,241 @@
+/**
+ * Shared better-sqlite3 loader with ABI mismatch recovery.
+ *
+ * Pi installs extension deps under ~/.pi/agent/npm. When the host Node that
+ * runs Pi (e.g. Homebrew) differs from the Node that compiled better-sqlite3,
+ * require() throws NODE_MODULE_VERSION errors. Detect that, attempt one
+ * npm rebuild against the current runtime, and surface a clear recovery path.
+ */
+
+import { createRequire } from "node:module";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+export type BetterSqlite3DatabaseCtor = new (
+  dbPath: string,
+  options?: { readonly?: boolean; fileMustExist?: boolean; timeout?: number },
+) => unknown;
+
+export interface SqliteNativeLoadOptions {
+  /** Override createRequire base URL (tests). */
+  requireFrom?: string | URL;
+  /** Inject require() for tests. */
+  requireImpl?: NodeRequire;
+  /** Inject rebuild runner for tests. */
+  rebuild?: (packageRoot: string) => { ok: boolean; detail: string };
+  /** Force treating the first load failure as rebuild-eligible (tests). */
+  allowRebuild?: boolean;
+}
+
+export class BetterSqlite3LoadError extends Error {
+  readonly code = "BETTER_SQLITE3_LOAD_FAILED";
+  readonly packageRoot: string | null;
+  readonly causeError: unknown;
+
+  constructor(message: string, options: { packageRoot?: string | null; cause?: unknown } = {}) {
+    super(message);
+    this.name = "BetterSqlite3LoadError";
+    this.packageRoot = options.packageRoot ?? null;
+    this.causeError = options.cause;
+  }
+}
+
+const ABI_MISMATCH_RE =
+  /NODE_MODULE_VERSION|was compiled against a different Node\.js version|ERR_DLOPEN_FAILED/i;
+
+/**
+ * True when running under Bun (including the compiled Pi binary).
+ *
+ * Compiled Pi cannot resolve `better-sqlite3` — neither the bare specifier nor
+ * the package's own transitive `require("bindings")` resolve from an on-disk
+ * extension file, so every code path that needs SQLite must route through
+ * `bun:sqlite` instead of loading the native module.
+ */
+export function isBunRuntime(): boolean {
+  return "Bun" in globalThis;
+}
+
+export function isNativeModuleAbiMismatch(error: unknown): boolean {
+  if (!error) return false;
+  const message = error instanceof Error ? error.message : String(error);
+  if (ABI_MISMATCH_RE.test(message)) return true;
+  if (typeof error === "object" && error !== null) {
+    const code = "code" in error ? String((error as { code?: unknown }).code ?? "") : "";
+    if (code === "ERR_DLOPEN_FAILED") return true;
+  }
+  return false;
+}
+
+export function resolveBetterSqlite3PackageRoot(requireImpl: NodeRequire): string | null {
+  try {
+    const entry = requireImpl.resolve("better-sqlite3");
+    let dir = path.dirname(entry);
+    while (true) {
+      const pkgPath = path.join(dir, "package.json");
+      if (fs.existsSync(pkgPath)) {
+        try {
+          const raw = fs.readFileSync(pkgPath, "utf-8");
+          const pkg = JSON.parse(raw) as { name?: unknown };
+          if (pkg && typeof pkg === "object" && pkg.name === "better-sqlite3") return dir;
+        } catch {
+          // keep walking
+        }
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+
+    // Classic layout fallback: .../node_modules/better-sqlite3/<...>
+    const parts = entry.split(path.sep);
+    const idx = parts.lastIndexOf("better-sqlite3");
+    if (idx >= 0) {
+      return parts.slice(0, idx + 1).join(path.sep) || null;
+    }
+    return path.dirname(entry);
+  } catch {
+    return null;
+  }
+}
+function defaultRebuild(packageRoot: string): { ok: boolean; detail: string } {
+  const npmExecPath = typeof process.env.npm_execpath === "string" && process.env.npm_execpath
+    ? process.env.npm_execpath
+    : null;
+
+  const attempts: Array<{ command: string; args: string[]; shell?: boolean }> = [];
+  if (npmExecPath) {
+    attempts.push({ command: process.execPath, args: [npmExecPath, "rebuild", "better-sqlite3"] });
+  }
+  attempts.push({ command: "npm", args: ["rebuild", "better-sqlite3"] });
+
+  const details: string[] = [];
+  for (const attempt of attempts) {
+    const result = spawnSync(attempt.command, attempt.args, {
+      cwd: packageRoot,
+      encoding: "utf-8",
+      env: process.env,
+      timeout: 120_000,
+      shell: attempt.shell ?? false,
+    });
+    if (result.error) {
+      details.push(`${attempt.command}: ${result.error.message}`);
+      continue;
+    }
+    if (result.status === 0) {
+      return { ok: true, detail: (result.stdout || result.stderr || "rebuild ok").trim() };
+    }
+    const output = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
+    details.push(`${attempt.command} exited ${result.status}${output ? `: ${output}` : ""}`);
+  }
+
+  return { ok: false, detail: details.join(" | ") || "rebuild failed" };
+}
+
+function unwrapModule(mod: { default?: BetterSqlite3DatabaseCtor } | BetterSqlite3DatabaseCtor): BetterSqlite3DatabaseCtor {
+  return (mod as { default?: BetterSqlite3DatabaseCtor }).default ?? (mod as BetterSqlite3DatabaseCtor);
+}
+
+function clearBetterSqlite3RequireCache(requireImpl: NodeRequire, packageRoot: string | null): void {
+  for (const key of Object.keys(requireImpl.cache)) {
+    if (!key.includes(`${path.sep}better-sqlite3${path.sep}`) && !key.endsWith(`${path.sep}better-sqlite3`)) {
+      continue;
+    }
+    if (packageRoot && !key.startsWith(packageRoot)) continue;
+    delete requireImpl.cache[key];
+  }
+}
+
+export function formatBetterSqlite3AbiError(options: {
+  originalError: unknown;
+  packageRoot: string | null;
+  rebuildAttempted: boolean;
+  rebuildDetail?: string;
+}): string {
+  const original = options.originalError instanceof Error
+    ? options.originalError.message
+    : String(options.originalError);
+  const runtime = `Node ${process.version} (NODE_MODULE_VERSION ${process.versions.modules}) via ${process.execPath}`;
+  const location = options.packageRoot ?? "(better-sqlite3 package root unknown)";
+  const rebuildLine = options.rebuildAttempted
+    ? (options.rebuildDetail
+      ? `Automatic rebuild was attempted and failed: ${options.rebuildDetail}`
+      : "Automatic rebuild was attempted and failed.")
+    : "Automatic rebuild was not attempted.";
+
+  return [
+    "pi-hermes-memory could not load the native better-sqlite3 module for this Node runtime.",
+    `Runtime: ${runtime}`,
+    `Module: ${location}`,
+    `Original error: ${original}`,
+    rebuildLine,
+    "Fix: rebuild the extension install against the same Node that runs Pi, then restart Pi:",
+    options.packageRoot
+      ? `  cd "${options.packageRoot}" && npm rebuild better-sqlite3`
+      : "  cd ~/.pi/agent/npm && npm rebuild better-sqlite3",
+    "If you installed Pi with Homebrew, either rebuild as above after brew Node upgrades, or install Pi with npm so the extension and host share one Node toolchain.",
+  ].join("\n");
+}
+
+/**
+ * Load better-sqlite3, attempting one rebuild on ABI/dlopen mismatch.
+ */
+export function loadBetterSqlite3(options: SqliteNativeLoadOptions = {}): BetterSqlite3DatabaseCtor {
+  const requireImpl = options.requireImpl
+    ?? createRequire(options.requireFrom ?? import.meta.url);
+
+  const loadOnce = (): BetterSqlite3DatabaseCtor => {
+    const mod = requireImpl("better-sqlite3") as { default?: BetterSqlite3DatabaseCtor } | BetterSqlite3DatabaseCtor;
+    return unwrapModule(mod);
+  };
+
+  try {
+    return loadOnce();
+  } catch (firstError) {
+    const packageRoot = resolveBetterSqlite3PackageRoot(requireImpl);
+    const canRebuild = options.allowRebuild ?? isNativeModuleAbiMismatch(firstError);
+    if (!canRebuild || !packageRoot) {
+      if (isNativeModuleAbiMismatch(firstError)) {
+        throw new BetterSqlite3LoadError(
+          formatBetterSqlite3AbiError({
+            originalError: firstError,
+            packageRoot,
+            rebuildAttempted: false,
+          }),
+          { packageRoot, cause: firstError },
+        );
+      }
+      throw firstError;
+    }
+
+    const rebuild = options.rebuild ?? defaultRebuild;
+    const rebuildResult = rebuild(packageRoot);
+    clearBetterSqlite3RequireCache(requireImpl, packageRoot);
+
+    if (rebuildResult.ok) {
+      try {
+        return loadOnce();
+      } catch (secondError) {
+        throw new BetterSqlite3LoadError(
+          formatBetterSqlite3AbiError({
+            originalError: secondError,
+            packageRoot,
+            rebuildAttempted: true,
+            rebuildDetail: rebuildResult.detail,
+          }),
+          { packageRoot, cause: secondError },
+        );
+      }
+    }
+
+    throw new BetterSqlite3LoadError(
+      formatBetterSqlite3AbiError({
+        originalError: firstError,
+        packageRoot,
+        rebuildAttempted: true,
+        rebuildDetail: rebuildResult.detail,
+      }),
+      { packageRoot, cause: firstError },
+    );
+  }
+}

package/src/tools/skill-tool.ts

@@ -66,22 +66,22 @@ const SKILL_TOOL_PARAMETERS = Type.Object({
     description: "Required for create. Use 'global' for portable procedures and 'project' for repo-specific workflows.",
   })),
   section: Type.Optional(Type.String({
-    description: "Required for patch. Section header to patch. e.g., 'Procedure', 'Pitfalls'.",
+    description: "Required for patch. Section header to patch. e.g., 'Procedure', 'Pitfalls', 'Verification', 'When to Use'.",
   })),
   content: Type.Optional(Type.String({
-    description: "Raw markdown body for create/update/edit, or new section content for patch. For create/update/edit you can provide this or the structured fields below.",
+    description: "Raw markdown body for create/update/edit, or Markdown section body for patch. Prefer structured fields over free-form content when possible. For patch, JSON arrays are auto-coerced for list sections; JSON objects are rejected.",
   })),
   when_to_use: Type.Optional(Type.String({
-    description: "Structured create/update/edit field. Explain when this skill should be used and where its boundaries are.",
+    description: "Structured create/update/edit field, or structured patch body when section is 'When to Use'.",
   })),
   procedure_steps: Type.Optional(Type.Array(Type.String(), {
-    description: "Structured create/update/edit field. Ordered concrete steps for the workflow.",
+    description: "Structured create/update/edit field, or structured patch body when section is 'Procedure'. Ordered concrete steps.",
   })),
   pitfalls: Type.Optional(Type.Array(Type.String(), {
-    description: "Structured create/update/edit field. Optional common mistakes, caveats, or failure modes to avoid.",
+    description: "Structured create/update/edit field, or structured patch body when section is 'Pitfalls'.",
   })),
   verification_steps: Type.Optional(Type.Array(Type.String(), {
-    description: "Structured create/update/edit field. Concrete checks that confirm the workflow succeeded.",
+    description: "Structured create/update/edit field, or structured patch body when section is 'Verification'.",
   })),
 }, { additionalProperties: false });
 
@@ -97,7 +97,9 @@ export function registerSkillTool(pi: ExtensionAPI, store: SkillStore): void {
       "Use the skill_manage tool after completing complex tasks that required trial and error or multiple tool calls.",
       "Use 'create' to save a new reusable procedure, 'patch' to update a section of an existing skill by skill_id, and 'update' for a full rewrite.",
       "Scope is required on create: choose scope='global' for transferable procedures and scope='project' when the workflow depends on this repo's paths, scripts, conventions, or deploy steps.",
-      "Prefer structured fields for create/update: when_to_use, procedure_steps, pitfalls, and verification_steps. The tool will render valid SKILL.md sections for you.",
+      "Prefer structured fields for create/update/patch: when_to_use, procedure_steps, pitfalls, and verification_steps. The tool renders valid SKILL.md sections for you.",
+      "For patch, pass section plus the matching structured field (e.g. section='Procedure' with procedure_steps). Avoid free-form content that is a JSON array/object string.",
+      "Prefer 'update' for multi-section rewrites when patch content would be large or format-unstable.",
       "Use 'view' before patching or updating when you need to inspect an existing skill.",
       "Do NOT use skills for temporary task state — only for durable, reusable procedures.",
     ],
@@ -206,7 +208,7 @@ export function registerSkillTool(pi: ExtensionAPI, store: SkillStore): void {
           result = { success: true, ...doc };
           break;
 
-        case "patch":
+        case "patch": {
           if (!skill_id) {
             return {
               content: [{ type: "text", text: JSON.stringify({ success: false, error: "skill_id is required for 'patch' action." }) }],
@@ -219,14 +221,60 @@ export function registerSkillTool(pi: ExtensionAPI, store: SkillStore): void {
               details: {},
             };
           }
-          if (!content) {
+
+          const sectionKey = section.replace(/^#+\s*/, "").trim().toLowerCase();
+          let patchContent = content?.trim() ?? "";
+
+          // Prefer structured fields matching the target section so the LLM
+          // does not have to invent Markdown list formatting.
+          if (sectionKey === "procedure" && procedureSteps.length > 0) {
+            patchContent = formatOrderedList(procedureSteps);
+          } else if (sectionKey === "pitfalls" && pitfallItems.length > 0) {
+            patchContent = formatBulletList(pitfallItems, "No notable pitfalls recorded yet.");
+          } else if (sectionKey === "verification" && verificationSteps.length > 0) {
+            patchContent = formatOrderedList(verificationSteps);
+          } else if ((sectionKey === "when to use" || sectionKey === "when_to_use") && whenToUse) {
+            patchContent = whenToUse;
+          } else if (!patchContent && hasStructuredBody) {
+            // Allow a single structured field even if section name is non-standard.
+            if (procedureSteps.length > 0 && pitfallItems.length === 0 && verificationSteps.length === 0 && !whenToUse) {
+              patchContent = formatOrderedList(procedureSteps);
+            } else if (pitfallItems.length > 0 && procedureSteps.length === 0 && verificationSteps.length === 0 && !whenToUse) {
+              patchContent = formatBulletList(pitfallItems, "No notable pitfalls recorded yet.");
+            } else if (verificationSteps.length > 0 && procedureSteps.length === 0 && pitfallItems.length === 0 && !whenToUse) {
+              patchContent = formatOrderedList(verificationSteps);
+            } else if (whenToUse && procedureSteps.length === 0 && pitfallItems.length === 0 && verificationSteps.length === 0) {
+              patchContent = whenToUse;
+            } else {
+              return {
+                content: [{
+                  type: "text",
+                  text: JSON.stringify({
+                    success: false,
+                    error: "For patch, provide content or exactly one structured field matching the target section (procedure_steps, pitfalls, verification_steps, or when_to_use). Use update for multi-section rewrites.",
+                  }),
+                }],
+                details: {},
+              };
+            }
+          }
+
+          if (!patchContent) {
             return {
-              content: [{ type: "text", text: JSON.stringify({ success: false, error: "content is required for 'patch' action." }) }],
+              content: [{
+                type: "text",
+                text: JSON.stringify({
+                  success: false,
+                  error: "content or a matching structured field is required for 'patch' action. Prefer procedure_steps/pitfalls/verification_steps/when_to_use.",
+                }),
+              }],
               details: {},
             };
           }
-          result = await store.patch(skill_id, section, content);
+
+          result = await store.patch(skill_id, section, patchContent);
           break;
+        }
 
         case "update":
         case "edit": {