pi-hermes-memory 0.8.0 → 0.8.2

package/README.md

@@ -92,6 +92,18 @@ Every write — memory and skills — passes through a scanner before being acce
 
 ![Security: Content Scanning](docs/images/security-flow.svg)
 
+## Development
+
+`npm run check` and `npm test` only work from a **full git checkout** after `npm install`. The published npm package intentionally omits `tests/`, TypeScript, and `tsconfig.json` (production install for Pi). Validate from source or rely on CI before publish.
+
+```bash
+git clone https://github.com/chandra447/pi-hermes-memory.git
+cd pi-hermes-memory
+npm install
+npm run check
+npm test
+```
+
 ## Installation
 
 ```bash
@@ -110,6 +122,23 @@ Or test locally without installing:
 pi -e /path/to/pi-hermes-memory/src/index.ts
 ```
 
+### Homebrew / Node ABI mismatches
+
+`better-sqlite3` is a native addon. If Pi is installed via Homebrew and the extension was compiled for a different Node ABI, session search may warn:
+
+```text
+was compiled against a different Node.js version using NODE_MODULE_VERSION ...
+```
+
+The extension attempts one automatic `npm rebuild better-sqlite3` against the Node that is running Pi. If that still fails:
+
+```bash
+cd ~/.pi/agent/npm/node_modules/better-sqlite3
+npm rebuild better-sqlite3
+```
+
+Or install Pi with npm so the host runtime and extension install share one Node toolchain.
+
 ## Two-Tier Memory Architecture
 
 The extension stores memory at two levels:

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "pi-hermes-memory",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "🧠 Persistent memory + 🔍 session search + 🛡️ secret scanning for Pi. Token-aware policy-only memory by default, SQLite FTS5 search, auto-consolidation, procedural skills. 693 tests. Ported from Hermes agent.",
   "type": "module",
   "main": "src/index.ts",
   "files": [
     "src",
+    "scripts",
     "README.md",
     "LICENSE",
     "docs"
@@ -16,8 +17,8 @@
     ]
   },
   "scripts": {
-    "check": "tsc --noEmit",
-    "test": "tests/run-all.sh"
+    "check": "node scripts/ensure-dev.mjs check && tsc --noEmit",
+    "test": "node scripts/ensure-dev.mjs test && tests/run-all.sh"
   },
   "keywords": [
     "pi-package",

package/scripts/ensure-dev.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * Guard for check/test npm scripts.
+ *
+ * The published tarball intentionally omits tests/ and TypeScript (devDependency).
+ * When those scripts are run from an installed package (e.g. after `pi install`),
+ * fail with a clear message instead of `tsc: not found` / `tests/run-all.sh: not found`.
+ *
+ * @see https://github.com/chandra447/pi-hermes-memory/issues/108
+ */
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const mode = process.argv[2];
+const REPO = "https://github.com/chandra447/pi-hermes-memory";
+
+function fail(message) {
+  console.error(`\n[pi-hermes-memory] ${message}`);
+  console.error("");
+  console.error("These scripts only work from a full source checkout:");
+  console.error(`  git clone ${REPO}.git`);
+  console.error("  cd pi-hermes-memory && npm install");
+  console.error("  npm run check   # or: npm test");
+  console.error("");
+  console.error(
+    "The published package is for runtime use via Pi; CI validates check/test before publish.",
+  );
+  console.error("");
+  process.exit(1);
+}
+
+if (mode === "check") {
+  const require = createRequire(join(root, "package.json"));
+  try {
+    require.resolve("typescript/package.json");
+  } catch {
+    fail(
+      "`npm run check` requires TypeScript (a devDependency). The published npm package does not include it.",
+    );
+  }
+  if (!existsSync(join(root, "tsconfig.json"))) {
+    fail(
+      "`npm run check` requires tsconfig.json. The published npm package does not include it.",
+    );
+  }
+} else if (mode === "test") {
+  if (!existsSync(join(root, "tests", "run-all.sh"))) {
+    fail(
+      "`npm test` requires the tests/ directory. The published npm package intentionally omits it.",
+    );
+  }
+} else {
+  fail(`Unknown mode "${mode ?? ""}". Expected "check" or "test".`);
+}

package/src/constants.ts

@@ -70,7 +70,7 @@ If memory conflicts with current evidence, prefer current evidence and mention t
 Procedural skills:
 - Use the skill_manage tool during normal work when a task reveals a reusable how-to workflow, or when the user asks you to remember how to do something later.
 - Always pass scope explicitly on create: scope="global" for portable procedures, scope="project" for workflows tied to this repo's paths, scripts, architecture, deploy steps, or conventions.
-- Prefer structured fields for create/update: when_to_use, procedure_steps, pitfalls, verification_steps. Use patch to improve a specific section of an existing skill, update for a full rewrite, and view to inspect existing skills before changing them.
+- Prefer structured fields for create/update/patch: when_to_use, procedure_steps, pitfalls, verification_steps. Use patch with the matching structured field for one section, update for a full rewrite, and view before changing an existing skill.
 - Do not create skills for one-off task state, generic summaries, or overly file-specific notes that will create noisy future matches.
 
 Do not use memory_search for generic questions, one-off examples, or explanations where durable memory would not help.
@@ -92,7 +92,7 @@ Memory write targets: user for preferences/profile; memory for global notes and
 
 memory_search filters: target searches user/global/failure memories; project filters project-scoped memories; category filters categorized failure/lesson memories only.
 
-Use the skill_manage tool during normal work for reusable procedures. On create, scope is required: global for transferable workflows, project for repo-specific ones. Prefer structured fields for create/update, patch for focused changes, and update for full rewrites. Skip one-off or overly narrow skills.
+Use the skill_manage tool during normal work for reusable procedures. On create, scope is required: global for transferable workflows, project for repo-specific ones. Prefer structured fields for create/update/patch, patch for one section, and update for full rewrites. Skip one-off or overly narrow skills.
 
 Use category only for categorized failure/lesson searches. Do not use memory_search for generic questions, one-off examples, or explanations where durable memory would not help.
 
@@ -315,20 +315,21 @@ SCOPE:
 - 'global': transferable procedures that can be reused across repositories
 - 'project': procedures tied to this repo's paths, scripts, architecture, deploy flow, or conventions
 
-WHEN TO UPDATE A SKILL (use 'patch'):
-- You discover a better approach for an existing skill
-- A pitfall or edge case not covered by the skill
-- A step in the procedure changed
+WHEN TO UPDATE A SKILL:
+- Prefer 'patch' for one section when you can pass structured fields
+- Prefer 'update' for multi-section rewrites or when patch formatting would be unstable
+- Use patch when you discover a better approach, pitfall, or changed step in one section
 
 SKILL FORMAT:
 - name: short, descriptive (e.g., "debug-typescript-errors")
 - description: one-line summary of when to use it
 - body: structured with sections — ## When to Use, ## Procedure, ## Pitfalls, ## Verification
-- Prefer structured create/update fields over raw markdown when possible:
+- Prefer structured fields over raw markdown when possible:
   - when_to_use: trigger conditions and boundaries
   - procedure_steps: ordered concrete steps
   - pitfalls: caveats or failure modes
   - verification_steps: checks that prove success
+- For patch, pass section plus the matching structured field (section="Procedure" + procedure_steps, etc.). Do not pass JSON array/object strings as content.
 
 ONE-SHOT EXAMPLE:
 {

package/src/extension-root-migration.ts

@@ -2,10 +2,27 @@ import fs from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import path from "node:path";
-import Database from "better-sqlite3";
 import { AtomicLockCoordinator, type AtomicLockLease } from "./store/atomic-lock-coordinator.js";
 import { canonicalStoragePathSync } from "./store/canonical-storage-path.js";
-
+import { loadBetterSqlite3 } from "./store/sqlite-native.js";
+
+type MigrationDatabase = {
+  exec: (sql: string) => void;
+  prepare: (sql: string) => { get: (...args: unknown[]) => unknown; run: (...args: unknown[]) => unknown };
+  close: () => void;
+  pragma: (query: string, options?: { simple?: boolean }) => unknown;
+  backup: (
+    destination: string,
+    options?: { progress?: () => void },
+  ) => Promise<void> | void;
+};
+
+type MigrationDatabaseCtor = new (
+  dbPath: string,
+  options?: { readonly?: boolean; fileMustExist?: boolean; timeout?: number },
+) => MigrationDatabase;
+
+const Database = loadBetterSqlite3() as MigrationDatabaseCtor;
 const DATABASE_FILES = ["sessions.db", "sessions.db-wal", "sessions.db-shm"] as const;
 const DATABASE_MIGRATION_PENDING_FILE = ".sessions-db-migration-pending";
 

package/src/store/atomic-lock-coordinator.ts

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
+import { loadBetterSqlite3 } from './sqlite-native.js';
 
 type StatementLike = {
   run: (...args: unknown[]) => unknown;
@@ -39,8 +40,7 @@ function loadDatabaseCtor(): DatabaseCtor {
     const bunSqlite = require('bun:sqlite') as { Database: DatabaseCtor };
     return bunSqlite.Database;
   }
-  const mod = require('better-sqlite3') as { default?: DatabaseCtor } | DatabaseCtor;
-  return (mod as { default?: DatabaseCtor }).default ?? (mod as DatabaseCtor);
+  return loadBetterSqlite3({ requireImpl: require }) as DatabaseCtor;
 }
 
 const Database = loadDatabaseCtor();

package/src/store/db.ts

@@ -4,6 +4,7 @@ import { createRequire } from 'node:module';
 import { SCHEMA_SQL } from './schema.js';
 import { AtomicLockCoordinator } from './atomic-lock-coordinator.js';
 import { canonicalStoragePathSync } from './canonical-storage-path.js';
+import { loadBetterSqlite3 } from './sqlite-native.js';
 
 type StatementLike = {
   run: (...args: any[]) => any;
@@ -69,6 +70,7 @@ class DatabaseCorruptionError extends Error {
   }
 }
 
+export const SQLITE_BUSY_TIMEOUT_MS = 5000;
 export const SQLITE_WAL_AUTOCHECKPOINT_PAGES = 1000;
 
 const DATABASE_FILE_SUFFIXES: readonly DatabaseFileSuffix[] = ['', '-wal', '-shm'];
@@ -126,12 +128,7 @@ function loadDatabaseCtor(): DatabaseCtor {
     return createBunCompatDatabaseCtor(require);
   }
 
-  try {
-    const mod = require('better-sqlite3') as { default?: DatabaseCtor } | DatabaseCtor;
-    return (mod as { default?: DatabaseCtor }).default ?? (mod as DatabaseCtor);
-  } catch (err) {
-    throw err;
-  }
+  return loadBetterSqlite3({ requireImpl: require }) as DatabaseCtor;
 }
 
 const Database = loadDatabaseCtor();
@@ -294,6 +291,9 @@ export class DatabaseManager {
   }
 
   private configureConnection(db: DatabaseLike): void {
+    // Wait briefly for concurrent writers across Pi processes instead of failing
+    // immediately with SQLITE_BUSY. Connection-local; applies before WAL/schema.
+    db.exec(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`);
     // Enable WAL mode + FK enforcement for each connection. Keep SQLite's
     // default WAL autocheckpoint size; a very aggressive checkpoint cadence
     // increases the chance that abrupt VM/host shutdown catches a checkpoint.

package/src/store/memory-store.ts

@@ -587,6 +587,46 @@ export class MemoryStore {
     this.fileFingerprints[filePath] = state.fingerprint;
   }
 
+  /**
+   * Reload target state from disk (source of truth), refresh success metadata,
+   * and always notify the mutation observer so SQLite stays aligned even when
+   * the mutation itself failed or an external editor raced the write.
+   */
+  private async finalizeTargetMutation(
+    target: "memory" | "user" | "failure",
+    storagePath: string,
+    result: MemoryResult,
+  ): Promise<MemoryResult> {
+    const state = await this.readFileState(storagePath);
+    this.setEntries(target, [...new Set(state.entries)]);
+    this.fileFingerprints[storagePath] = state.fingerprint;
+
+    let finalized = result;
+    if (result.success) {
+      finalized = {
+        ...result,
+        ...this.successResponse(target, result.message),
+      };
+      if (result.evicted_entries) finalized.evicted_entries = result.evicted_entries;
+      if (result.evicted_count !== undefined) finalized.evicted_count = result.evicted_count;
+      if (result.matches) finalized.matches = result.matches;
+      if (result.entries) finalized.entries = result.entries;
+    }
+
+    if (!this.mutationObserver) return finalized;
+
+    const warning = await this.mutationObserver(target, [...state.entries]);
+    if (!warning || !finalized.success) return finalized;
+
+    const warnings = [...(finalized.warnings ?? []), warning];
+    return {
+      ...finalized,
+      message: finalized.message ? `${finalized.message} Warning: ${warning}` : warning,
+      warning,
+      warnings,
+    };
+  }
+
   private async runTargetMutation(
     target: "memory" | "user" | "failure",
     mutation: () => Promise<MemoryResult>,
@@ -596,35 +636,32 @@ export class MemoryStore {
       for (let attempt = 0; ; attempt++) {
         try {
           const result = await mutation();
-          if (result.success && this.mutationObserver) {
-            const filePath = storagePath;
-            const state = await this.readFileState(filePath);
-            this.setEntries(target, [...new Set(state.entries)]);
-            this.fileFingerprints[filePath] = state.fingerprint;
-            const warning = await this.mutationObserver(target, [...state.entries]);
-            if (warning) {
-              const warnings = [...(result.warnings ?? []), warning];
-              return {
-                ...result,
-                message: result.message ? `${result.message} Warning: ${warning}` : warning,
-                warning,
-                warnings,
-              };
+          if (result.success) {
+            // saveToDisk stamps fileFingerprints on success. If an editor
+            // truncates/replaces the file after publish returns, refuse the
+            // phantom success and retry against disk truth.
+            const expectedFingerprint = this.fileFingerprints[storagePath];
+            if (expectedFingerprint !== undefined) {
+              const state = await this.readFileState(storagePath);
+              if (state.fingerprint !== expectedFingerprint) {
+                this.setEntries(target, [...new Set(state.entries)]);
+                this.fileFingerprints[storagePath] = state.fingerprint;
+                throw new ExternalMemoryWriteConflict();
+              }
             }
           }
-          return result;
+          return await this.finalizeTargetMutation(target, storagePath, result);
         } catch (error) {
-          const filePath = storagePath;
-          delete this.fileFingerprints[filePath];
-          const state = await this.readFileState(filePath);
+          delete this.fileFingerprints[storagePath];
+          const state = await this.readFileState(storagePath);
           this.setEntries(target, [...new Set(state.entries)]);
-          this.fileFingerprints[filePath] = state.fingerprint;
+          this.fileFingerprints[storagePath] = state.fingerprint;
           if (!(error instanceof ExternalMemoryWriteConflict)) throw error;
           if (attempt >= MAX_EXTERNAL_WRITE_RETRIES) {
-            return {
+            return await this.finalizeTargetMutation(target, storagePath, {
               success: false,
-              error: "Memory file changed repeatedly during this update. No external changes were overwritten.",
-            };
+              error: "Memory file changed repeatedly during this update. No external changes were overwritten. If you edited the file manually, re-run the memory tool or /memory-sync-markdown after the file is stable.",
+            });
           }
         }
       }
@@ -718,7 +755,18 @@ export class MemoryStore {
       }
 
       try { await this.unlinkPublishedTempLink(tmpPath); } catch { /* ignore */ }
-      this.fileFingerprints[filePath] = this.fingerprint(content);
+
+      // Re-read after publish. An external truncate/cp can land between the
+      // link/rename and returning success; treat that as a write conflict so
+      // the caller retries against disk truth instead of reporting phantom state.
+      const publishedFingerprint = this.fingerprint(content);
+      this.fileFingerprints[filePath] = publishedFingerprint;
+      const publishedState = await this.readFileState(filePath);
+      if (publishedState.fingerprint !== publishedFingerprint) {
+        this.setEntries(target, [...new Set(publishedState.entries)]);
+        this.fileFingerprints[filePath] = publishedState.fingerprint;
+        throw new ExternalMemoryWriteConflict();
+      }
     } catch (err) {
       try { await fs.unlink(tmpPath); } catch { /* ignore */ }
       throw err;

package/src/store/skill-store.ts

@@ -46,6 +46,111 @@ export interface LegacySkillMigrationResult {
   warnings: string[];
 }
 
+const LIST_SECTIONS = new Set(["procedure", "pitfalls", "verification"]);
+
+function normalizeSectionName(section: string): string {
+  return section.replace(/^#+\s*/, "").trim();
+}
+
+function isExactSectionHeader(line: string, section: string): boolean {
+  const heading = line.trim().match(/^##\s+(.+?)\s*$/);
+  if (!heading) return false;
+  return heading[1].trim().toLowerCase() === section.trim().toLowerCase();
+}
+
+function looksLikeJsonArray(content: string): boolean {
+  const trimmed = content.trim();
+  return trimmed.startsWith("[") && trimmed.endsWith("]");
+}
+
+function looksLikeJsonObject(content: string): boolean {
+  const trimmed = content.trim();
+  return trimmed.startsWith("{") && trimmed.endsWith("}");
+}
+
+function formatPatchList(section: string, items: string[]): string {
+  const cleaned = items.map((item) => item.trim()).filter(Boolean);
+  if (cleaned.length === 0) return "";
+  const key = section.trim().toLowerCase();
+  if (key === "pitfalls") {
+    return cleaned.map((item) => `- ${item.replace(/^[-*]\s+/, "")}`).join("\n");
+  }
+  // Procedure / Verification default to ordered steps.
+  return cleaned
+    .map((item, index) => `${index + 1}. ${item.replace(/^\d+\.\s+/, "").replace(/^[-*]\s+/, "")}`)
+    .join("\n");
+}
+
+/**
+ * Normalize/validate free-form patch content so LLM format drift cannot wipe
+ * or splice skill sections. Coerces JSON string arrays into Markdown lists for
+ * list-shaped sections and rejects empty / object / header-injecting payloads.
+ */
+export function normalizeSkillPatchContent(
+  section: string,
+  rawContent: string,
+): { content: string } | { error: string } {
+  const sectionName = normalizeSectionName(section);
+  if (!sectionName) {
+    return { error: "section is required for patch." };
+  }
+
+  let content = typeof rawContent === "string" ? rawContent.trim() : "";
+  if (!content) {
+    return {
+      error: "New content is required for patch. Prefer structured fields (procedure_steps, pitfalls, verification_steps, when_to_use) over free-form content.",
+    };
+  }
+
+  if (looksLikeJsonObject(content)) {
+    return {
+      error: "Patch content looks like a JSON object. Provide Markdown section body or a string array via structured fields.",
+    };
+  }
+
+  if (looksLikeJsonArray(content)) {
+    try {
+      const parsed: unknown = JSON.parse(content);
+      if (!Array.isArray(parsed)) {
+        return { error: "Patch content looks like JSON but is not a string array." };
+      }
+      const items = parsed
+        .filter((item): item is string => typeof item === "string")
+        .map((item) => item.trim())
+        .filter(Boolean);
+      if (items.length === 0) {
+        return { error: "Patch content JSON array must contain non-empty strings." };
+      }
+      const key = sectionName.toLowerCase();
+      if (key === "when to use") {
+        content = items.join("\n\n");
+      } else if (LIST_SECTIONS.has(key)) {
+        content = formatPatchList(sectionName, items);
+      } else {
+        content = items.map((item) => `- ${item}`).join("\n");
+      }
+    } catch {
+      return {
+        error: "Patch content looks like a JSON array but could not be parsed. Use Markdown or structured string[] fields.",
+      };
+    }
+  }
+
+  // Reject payloads that would inject extra ## sections mid-body.
+  if (/^#{1,6}\s+\S/m.test(content)) {
+    return {
+      error: "Patch content must not include Markdown section headers (## ...). Patch only the body of the target section.",
+    };
+  }
+
+  if (!content.trim()) {
+    return { error: "New content is required for patch." };
+  }
+
+  return { content: content.trim() };
+}
+
+
 export class SkillStore {
   private globalSkillsDir: string;
   private projectSkillsDir: string | null;
@@ -352,34 +457,47 @@ export class SkillStore {
   }
 
   async patch(skillId: string, section: string, newContent: string): Promise<SkillResult> {
-    newContent = newContent.trim();
-    if (!newContent) return { success: false, error: "New content is required for patch." };
+    const sectionName = normalizeSectionName(section);
+    if (!sectionName) return { success: false, error: "section is required for patch." };
+
+    const normalized = normalizeSkillPatchContent(sectionName, newContent);
+    if ("error" in normalized) return { success: false, error: normalized.error };
+    const content = normalized.content;
 
-    const scanError = scanContent(newContent);
+    const scanError = scanContent(content);
     if (scanError) return { success: false, error: scanError };
 
     const doc = await this.loadSkill(skillId);
     if (!doc) return { success: false, error: `Skill '${skillId}' not found.` };
 
-    const sectionHeader = `## ${section}`;
+    const sectionHeader = `## ${sectionName}`;
     const lines = doc.body.split("\n");
     let found = false;
     const result: string[] = [];
 
     for (let i = 0; i < lines.length; i++) {
-      if (lines[i].startsWith(sectionHeader)) {
+      if (isExactSectionHeader(lines[i], sectionName)) {
         result.push(sectionHeader);
-        result.push(newContent);
+        // Preserve multi-line body as discrete lines so later headers stay exact.
+        for (const bodyLine of content.split("\n")) {
+          result.push(bodyLine);
+        }
         found = true;
         i++;
-        while (i < lines.length && !lines[i].startsWith("## ")) i++;
+        while (i < lines.length && !lines[i].trim().startsWith("## ")) i++;
         if (i < lines.length) result.push(lines[i]);
       } else {
         result.push(lines[i]);
       }
     }
 
-    if (!found) result.push("", sectionHeader, newContent);
+    if (!found) {
+      if (result.length > 0 && result[result.length - 1] !== "") result.push("");
+      result.push(sectionHeader);
+      for (const bodyLine of content.split("\n")) {
+        result.push(bodyLine);
+      }
+    }
 
     await this.atomicWrite(doc.path, formatFrontmatter({
       name: doc.name,
@@ -393,7 +511,7 @@ export class SkillStore {
 
     return {
       success: true,
-      message: `Skill '${doc.displayName || doc.name}' section '${section}' updated.`,
+      message: `Skill '${doc.displayName || doc.name}' section '${sectionName}' updated.`,
       fileName: doc.fileName,
       skillId: doc.skillId,
       scope: doc.scope,

package/src/store/sqlite-native.ts

@@ -0,0 +1,229 @@
+/**
+ * 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;
+
+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": {