pi-hermes-memory 0.7.10 → 0.7.12

package/src/store/session-search.ts

@@ -1,17 +1,5 @@
 import { DatabaseManager } from './db.js';
-
-/**
- * Escape a string for FTS5 query syntax.
- * Wraps the query in double quotes to treat it as a literal phrase.
- */
-function escapeFts5Query(query: string): string {
-  // If the query already contains FTS5 operators (OR, AND, NOT, NEAR), leave it as-is
-  if (/\b(OR|AND|NOT|NEAR)\b/.test(query)) {
-    return query;
-  }
-  // Otherwise, wrap in double quotes to treat as literal phrase
-  return `"${query.replace(/"/g, '""')}"`;
-}
+import { isFts5QueryError, normalizeFts5Query } from './fts-query.js';
 
 /**
  * Search result from session history.
@@ -52,6 +40,10 @@ export function searchSessions(
   query: string,
   options: SessionSearchOptions = {}
 ): SessionSearchResult[] {
+  if (query.trim().length === 0) {
+    return [];
+  }
+
   const db = dbManager.getDb();
   const { limit = 10, project, role, since } = options;
 
@@ -60,8 +52,12 @@ export function searchSessions(
   const params: unknown[] = [];
 
   // FTS5 match condition — use subquery for reliable rowid matching
+  const normalizedQuery = normalizeFts5Query(query);
+  if (normalizedQuery.length === 0) {
+    return [];
+  }
   conditions.push('m.rowid IN (SELECT rowid FROM message_fts WHERE message_fts MATCH ?)');
-  params.push(escapeFts5Query(query));
+  params.push(normalizedQuery);
 
   // Project filter
   if (project) {
@@ -119,8 +115,10 @@ export function searchSessions(
       snippet: row.snippet,
     }));
   } catch (err) {
-    // FTS5 can throw on malformed queries — return empty results
-    return [];
+    if (isFts5QueryError(err)) {
+      return [];
+    }
+    throw err;
   }
 }
 

package/src/store/skill-store.ts

@@ -253,6 +253,8 @@ export class SkillStore {
     }
 
     return skills.sort((a, b) => {
+      if (a.updated !== b.updated) return b.updated.localeCompare(a.updated);
+      if (a.created !== b.created) return b.created.localeCompare(a.created);
       if (a.scope !== b.scope) return a.scope.localeCompare(b.scope);
       return (a.displayName || a.name).localeCompare(b.displayName || b.name);
     });
@@ -290,7 +292,7 @@ export class SkillStore {
     if (existing) {
       return {
         success: false,
-        error: `Skill '${slug}' already exists (${skillId}). Use 'patch' or 'edit' to update it.`,
+        error: `Skill '${slug}' already exists (${skillId}). Use 'patch' or 'update' to update it.`,
         conflictType: "duplicate",
         similarSkillIds: [skillId],
         suggestedAction: "patch",
@@ -303,7 +305,7 @@ export class SkillStore {
         const targetId = similarSkillIds[0];
         return {
           success: false,
-          error: `A similar global skill already exists (${targetId}). Enhance the existing skill with new learnings/failures using 'patch' or 'edit' instead of creating a duplicate.`,
+          error: `A similar global skill already exists (${targetId}). Enhance the existing skill with new learnings/failures using 'patch' or 'update' instead of creating a duplicate.`,
           conflictType: "similar",
           similarSkillIds,
           suggestedAction: "patch",
@@ -315,7 +317,7 @@ export class SkillStore {
         const targetId = collidingNameSkillIds[0];
         return {
           success: false,
-          error: `A near-name global skill already exists (${targetId}) but with different intent. Use a clearer differentiated name for the new skill, or patch/edit the existing skill if the intent is actually the same.`,
+          error: `A near-name global skill already exists (${targetId}) but with different intent. Use a clearer differentiated name for the new skill, or patch/update the existing skill if the intent is actually the same.`,
           conflictType: "name-collision",
           similarSkillIds: collidingNameSkillIds,
           suggestedAction: "rename",
@@ -790,6 +792,8 @@ export class SkillStore {
       name: doc.name,
       displayName: doc.displayName,
       description: doc.description,
+      created: doc.created,
+      updated: doc.updated,
     };
   }
 

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

@@ -1,4 +1,5 @@
 import { DatabaseManager } from './db.js';
+import { isFts5QueryError, normalizeFts5Query } from './fts-query.js';
 import type { MemoryCategory } from '../types.js';
 
 const MEMORY_SELECT_COLUMNS = `
@@ -550,19 +551,6 @@ export function removeExactSyncedMemories(
   };
 }
 
-/**
- * Escape a string for FTS5 query syntax.
- * Wraps the query in double quotes to treat it as a literal phrase.
- */
-function escapeFts5Query(query: string): string {
-  // If the query already contains FTS5 operators (OR, AND, NOT, NEAR), leave it as-is
-  if (/\b(OR|AND|NOT|NEAR)\b/.test(query)) {
-    return query;
-  }
-  // Otherwise, wrap in double quotes to treat as literal phrase
-  return `"${query.replace(/"/g, '""')}"`;
-}
-
 /**
  * Search memories using FTS5.
  */
@@ -571,6 +559,10 @@ export function searchMemories(
   query: string,
   options: { project?: string; target?: string; category?: MemoryCategory; limit?: number } = {}
 ): SqliteMemoryEntry[] {
+  if (query.trim().length === 0) {
+    return [];
+  }
+
   const db = dbManager.getDb();
   const { project, target, category, limit = 10 } = options;
 
@@ -578,8 +570,12 @@ export function searchMemories(
   const params: unknown[] = [];
 
   // FTS5 match via subquery with escaped query
+  const normalizedQuery = normalizeFts5Query(query);
+  if (normalizedQuery.length === 0) {
+    return [];
+  }
   conditions.push('m.id IN (SELECT rowid FROM memory_fts WHERE memory_fts MATCH ?)');
-  params.push(escapeFts5Query(query));
+  params.push(normalizedQuery);
 
   if (project !== undefined) {
     if (project === null) {
@@ -611,20 +607,27 @@ export function searchMemories(
   `;
   params.push(limit);
 
-  const rows = db.prepare(sql).all(...params) as Array<{
-    id: number;
-    project: string | null;
-    target: string;
-    category: string | null;
-    content: string;
-    failure_reason: string | null;
-    tool_state: string | null;
-    corrected_to: string | null;
-    created: string;
-    last_referenced: string;
-  }>;
-
-  return rows.map(mapRow);
+  try {
+    const rows = db.prepare(sql).all(...params) as Array<{
+      id: number;
+      project: string | null;
+      target: string;
+      category: string | null;
+      content: string;
+      failure_reason: string | null;
+      tool_state: string | null;
+      corrected_to: string | null;
+      created: string;
+      last_referenced: string;
+    }>;
+
+    return rows.map(mapRow);
+  } catch (err) {
+    if (isFts5QueryError(err)) {
+      return [];
+    }
+    throw err;
+  }
 }
 
 /**

package/src/tools/skill-tool.ts

@@ -9,6 +9,82 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import { SkillStore } from "../store/skill-store.js";
 import { SKILL_TOOL_DESCRIPTION } from "../constants.js";
 
+function normalizeTextList(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .filter((item): item is string => typeof item === "string")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function formatOrderedList(items: string[]): string {
+  return items.map((item, index) => `${index + 1}. ${item}`).join("\n");
+}
+
+function formatBulletList(items: string[], fallback: string): string {
+  if (items.length === 0) return `- ${fallback}`;
+  return items.map((item) => `- ${item}`).join("\n");
+}
+
+function buildStructuredSkillBody(
+  whenToUse: string,
+  procedureSteps: string[],
+  pitfalls: string[],
+  verificationSteps: string[],
+): string {
+  return [
+    "## When to Use",
+    whenToUse,
+    "",
+    "## Procedure",
+    formatOrderedList(procedureSteps),
+    "",
+    "## Pitfalls",
+    formatBulletList(pitfalls, "No notable pitfalls recorded yet."),
+    "",
+    "## Verification",
+    formatOrderedList(verificationSteps),
+  ].join("\n");
+}
+
+const SKILL_ID_PARAM = Type.String({
+  description: "Stable skill id for view/patch/update/delete. e.g., 'global:debug-typescript-errors' or 'project:my-repo:release-app'. Legacy alias 'edit' also accepts this field.",
+});
+
+const SKILL_TOOL_PARAMETERS = Type.Object({
+  action: StringEnum(["create", "view", "patch", "update", "edit", "delete"] as const, {
+    description: "The skill action to perform.",
+  }),
+  name: Type.Optional(Type.String({
+    description: "Skill name for create. e.g., 'debug-typescript-errors'.",
+  })),
+  skill_id: Type.Optional(SKILL_ID_PARAM),
+  description: Type.Optional(Type.String({
+    description: "One-line description of when to use this skill. Required for create; optional for update/edit.",
+  })),
+  scope: Type.Optional(StringEnum(["global", "project"] as const, {
+    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'.",
+  })),
+  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.",
+  })),
+  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.",
+  })),
+  procedure_steps: Type.Optional(Type.Array(Type.String(), {
+    description: "Structured create/update/edit field. Ordered concrete steps for the workflow.",
+  })),
+  pitfalls: Type.Optional(Type.Array(Type.String(), {
+    description: "Structured create/update/edit field. Optional common mistakes, caveats, or failure modes to avoid.",
+  })),
+  verification_steps: Type.Optional(Type.Array(Type.String(), {
+    description: "Structured create/update/edit field. Concrete checks that confirm the workflow succeeded.",
+  })),
+}, { additionalProperties: false });
+
 export function registerSkillTool(pi: ExtensionAPI, store: SkillStore): void {
   pi.registerTool({
     name: "skill",
@@ -17,33 +93,67 @@ export function registerSkillTool(pi: ExtensionAPI, store: SkillStore): void {
     promptSnippet: "Save or manage reusable procedures and patterns",
     promptGuidelines: [
       "Use the skill 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.",
-      "Choose scope='global' for transferable procedures and scope='project' when the workflow depends on this repo's paths, scripts, conventions, or deploy steps.",
+      "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.",
+      "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.",
     ],
-    parameters: Type.Object({
-      action: StringEnum(["create", "view", "patch", "edit", "delete"] as const),
-      name: Type.Optional(
-        Type.String({ description: "Skill name (for create). e.g., 'debug-typescript-errors'" })
-      ),
-      skill_id: Type.Optional(
-        Type.String({ description: "Stable skill id for view/patch/edit/delete. e.g., 'global:debug-typescript-errors' or 'project:my-repo:release-app'" })
-      ),
-      description: Type.Optional(
-        Type.String({ description: "One-line description of when to use this skill (for create/edit)" })
-      ),
-      scope: Type.Optional(
-        StringEnum(["global", "project"] as const, { description: "Optional creation scope. Omit to let the extension classify it automatically." })
-      ),
-      section: Type.Optional(
-        Type.String({ description: "Section header to patch (for patch action). e.g., 'Procedure', 'Pitfalls'" })
-      ),
-      content: Type.Optional(
-        Type.String({ description: "Body content for create, new section content for patch, or new body for edit" })
-      ),
-    }),
+    parameters: SKILL_TOOL_PARAMETERS,
     async execute(toolCallId, params, signal, onUpdate, ctx) {
-      const { action, name, skill_id, description, scope, section, content } = params;
+      const skillParams = params as {
+        action: "create" | "view" | "patch" | "update" | "edit" | "delete";
+        name?: string;
+        skill_id?: string;
+        description?: string;
+        scope?: "global" | "project";
+        section?: string;
+        content?: string;
+        when_to_use?: string;
+        procedure_steps?: unknown;
+        pitfalls?: unknown;
+        verification_steps?: unknown;
+      };
+      const {
+        action,
+        name,
+        skill_id,
+        description,
+        scope,
+        section,
+        content,
+        when_to_use,
+        procedure_steps,
+        pitfalls,
+        verification_steps,
+      } = skillParams;
+
+      const whenToUse = typeof when_to_use === "string" ? when_to_use.trim() : "";
+      const procedureSteps = normalizeTextList(procedure_steps);
+      const pitfallItems = normalizeTextList(pitfalls);
+      const verificationSteps = normalizeTextList(verification_steps);
+      const hasStructuredBody = Boolean(whenToUse) || procedureSteps.length > 0 || pitfallItems.length > 0 || verificationSteps.length > 0;
+
+      const buildBodyOrError = () => {
+        if (content?.trim()) return { body: content.trim() };
+        if (!hasStructuredBody) {
+          return {
+            error: "Either content or structured fields are required. Prefer when_to_use, procedure_steps, pitfalls, and verification_steps for create/update.",
+          };
+        }
+        if (!whenToUse) {
+          return { error: "when_to_use is required when content is omitted." };
+        }
+        if (procedureSteps.length === 0) {
+          return { error: "procedure_steps is required when content is omitted." };
+        }
+        if (verificationSteps.length === 0) {
+          return { error: "verification_steps is required when content is omitted." };
+        }
+        return {
+          body: buildStructuredSkillBody(whenToUse, procedureSteps, pitfallItems, verificationSteps),
+        };
+      };
 
       let result;
       switch (action) {
@@ -60,13 +170,20 @@ export function registerSkillTool(pi: ExtensionAPI, store: SkillStore): void {
               details: {},
             };
           }
-          if (!content) {
+          const createBodyResult = buildBodyOrError();
+          if (!createBodyResult.body) {
             return {
-              content: [{ type: "text", text: JSON.stringify({ success: false, error: "content (skill body) is required for 'create' action." }) }],
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: createBodyResult.error }) }],
               details: {},
             };
           }
-          result = await store.create(name, description, content, scope);
+          if (!scope) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: "scope is required for 'create' action. Use 'global' or 'project'." }) }],
+              details: {},
+            };
+          }
+          result = await store.create(name, description, createBodyResult.body, scope);
           break;
 
         case "view":
@@ -109,15 +226,33 @@ export function registerSkillTool(pi: ExtensionAPI, store: SkillStore): void {
           result = await store.patch(skill_id, section, content);
           break;
 
-        case "edit":
+        case "update":
+        case "edit": {
+          const updateActionLabel = action === "edit" ? "edit" : "update";
           if (!skill_id) {
             return {
-              content: [{ type: "text", text: JSON.stringify({ success: false, error: "skill_id is required for 'edit' action." }) }],
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: `skill_id is required for '${updateActionLabel}' action.` }) }],
+              details: {},
+            };
+          }
+          const updateBodyResult = buildBodyOrError();
+          const nextDescription = description?.trim() || "";
+          const nextBody = updateBodyResult.body ?? content?.trim() ?? "";
+          if (!nextDescription && !nextBody) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: `Provide description, content, or structured fields for '${updateActionLabel}'.` }) }],
+              details: {},
+            };
+          }
+          if (hasStructuredBody && !updateBodyResult.body) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: updateBodyResult.error }) }],
               details: {},
             };
           }
-          result = await store.edit(skill_id, description || "", content || "");
+          result = await store.edit(skill_id, nextDescription, nextBody);
           break;
+        }
 
         case "delete":
           if (!skill_id) {
@@ -132,7 +267,7 @@ export function registerSkillTool(pi: ExtensionAPI, store: SkillStore): void {
         default:
           result = {
             success: false,
-            error: `Unknown action '${action}'. Use: create, view, patch, edit, delete`,
+            error: `Unknown action '${action}'. Use: create, view, patch, update, delete`,
           };
       }
 

package/src/types.ts

@@ -126,6 +126,10 @@ export interface SkillIndex {
   displayName?: string;
   /** Short description shown in skill listings */
   description: string;
+  /** ISO date created */
+  created: string;
+  /** ISO date last updated */
+  updated: string;
 }
 
 export interface SkillDocument extends SkillIndex {
@@ -133,10 +137,6 @@ export interface SkillDocument extends SkillIndex {
   body: string;
   /** Version number */
   version: number;
-  /** ISO date created */
-  created: string;
-  /** ISO date last updated */
-  updated: string;
 }
 
 export interface SkillResult {
@@ -149,7 +149,7 @@ export interface SkillResult {
   path?: string;
   conflictType?: "duplicate" | "similar" | "name-collision" | "scope-conflict";
   similarSkillIds?: string[];
-  suggestedAction?: "patch" | "edit" | "rename";
+  suggestedAction?: "patch" | "update" | "rename";
 }
 
 /**

package/src/handlers/skill-auto-trigger.ts

@@ -1,128 +0,0 @@
-/**
- * Skill auto-trigger — after complex tasks (8+ tool calls, 2+ distinct tool types),
- * trigger automatic skill extraction via pi.exec().
- *
- * This implements Hermes' "self-evaluation checkpoint" pattern.
- */
-
-import * as path from "node:path";
-import { fileURLToPath } from "node:url";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { MemoryStore } from "../store/memory-store.js";
-import { SkillStore } from "../store/skill-store.js";
-import { COMBINED_REVIEW_PROMPT, DEFAULT_SKILL_TRIGGER_TOOL_CALLS, ENTRY_DELIMITER } from "../constants.js";
-import type { MemoryConfig } from "../types.js";
-import { getMessageText } from "../types.js";
-
-const proceduralSkillCreatorPath = path.join(
-  path.dirname(fileURLToPath(import.meta.url)),
-  "..",
-  "skills",
-  "procedural-skill-creator",
-);
-
-export function setupSkillAutoTrigger(
-  pi: ExtensionAPI,
-  store: MemoryStore,
-  skillStore: SkillStore,
-  config: MemoryConfig,
-): void {
-  let triggeredThisSession = false;
-
-  // Accumulate tool calls across turns (reset on trigger)
-  let toolCallCount = 0;
-  const toolTypes = new Set<string>();
-
-  pi.on("turn_end", async (event, ctx) => {
-    if (triggeredThisSession) return;
-
-    // Count tool calls from this turn's message only (not cumulative branch scan —
-    // otherwise the counter accumulates historical tool calls and fires prematurely).
-    try {
-      const msg = event.message;
-      if (msg?.role === "assistant") {
-        const content = msg?.content;
-        if (Array.isArray(content)) {
-          for (const block of content) {
-            if (block && typeof block === "object" && block.type === "toolCall") {
-              toolCallCount++;
-              if ((block as { name?: string }).name) toolTypes.add((block as { name: string }).name);
-            }
-          }
-        }
-      }
-    } catch {
-      return;
-    }
-
-    // Require 8+ tool calls AND 2+ distinct tool types
-    if (toolCallCount < DEFAULT_SKILL_TRIGGER_TOOL_CALLS) return;
-    if (toolTypes.size < 2) return;
-
-    triggeredThisSession = true;
-
-    try {
-      // Build conversation context
-      const branch = ctx.sessionManager.getBranch();
-      const parts: string[] = [];
-
-      for (const entry of branch) {
-        if (entry.type !== "message") continue;
-        const msg = entry.message;
-        const text = getMessageText(msg);
-        if (!text) continue;
-        const prefix = msg.role === "user" ? "[USER]" : "[ASSISTANT]";
-        parts.push(`${prefix}: ${text}`);
-      }
-
-      // Only include recent context
-      const recentParts = parts.slice(-10);
-
-      const currentMemory = store.getMemoryEntries().join(ENTRY_DELIMITER);
-      const skillIndex = await skillStore.loadIndex();
-      const skillSummary = skillIndex
-        .map((skill) => `${skill.skillId} [${skill.scope}]: ${skill.displayName || skill.name} - ${skill.description}`)
-        .join("\n");
-
-      const activeProjectName = skillStore.getProjectName();
-      const scopeLine = activeProjectName
-        ? `Active project context: '${activeProjectName}'. If workflow details depend on this project, use scope='project'; otherwise use scope='global'.`
-        : "No active project context detected. Use scope='global' unless the workflow is clearly project-specific.";
-
-      const prompt = [
-        "This was a complex task that required multiple tool calls. Extract any reusable procedures as skills.",
-        "A bundled skill named procedural-skill-creator is loaded for you. Read and follow it before deciding whether to create or patch a skill.",
-        "Always pass scope explicitly when creating a skill: scope='global' or scope='project'.",
-        "Choose scope='global' for transferable procedures and scope='project' when the workflow depends on this repo's paths, scripts, architecture, deploy steps, or conventions.",
-        scopeLine,
-        "",
-        "--- Existing Skills ---",
-        skillSummary || "(none)",
-        "",
-        "--- Current Memory ---",
-        currentMemory || "(empty)",
-        "",
-        "--- Recent Conversation ---",
-        recentParts.join("\n\n"),
-        "",
-        "If a skill should be created, use the skill tool with action 'create'.",
-        "If a related skill already exists, use 'patch' with its skill_id to update it.",
-        "If nothing reusable happened, say 'Nothing to extract.' and stop.",
-      ].join("\n");
-
-      const result = await pi.exec("pi", ["-p", "--no-session", "--skill", proceduralSkillCreatorPath, prompt], {
-        signal: ctx.signal,
-        timeout: 60000,
-      });
-
-      if (result.code === 0 && result.stdout) {
-        const output = result.stdout.trim();
-        if (output && !output.toLowerCase().includes("nothing to extract")) {
-          ctx.ui.notify("🧠 Complex task detected — skill extracted", "info");
-        }
-      }
-    } catch {
-      // Best-effort — don't block
-    }
-  });
-}