pi-hermes-memory 0.7.5 → 0.7.7

package/src/store/skill-utils.ts

@@ -0,0 +1,116 @@
+import * as fs from "node:fs/promises";
+import type { SkillDocument, SkillScope } from "../types.js";
+
+export interface ParsedSkillFile {
+  meta: Record<string, string>;
+  body: string;
+}
+
+export function parseFrontmatter(raw: string): ParsedSkillFile {
+  const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) return { meta: {}, body: raw.trim() };
+
+  const meta: Record<string, string> = {};
+  for (const line of match[1].split("\n")) {
+    const idx = line.indexOf(":");
+    if (idx > 0) {
+      const key = line.slice(0, idx).trim();
+      const value = line.slice(idx + 1).trim();
+      meta[key] = value;
+    }
+  }
+
+  return { meta, body: match[2].trim() };
+}
+
+export function formatFrontmatter(doc: Pick<SkillDocument, "name" | "displayName" | "description" | "version" | "created" | "updated" | "body">): string {
+  const lines = [
+    "---",
+    `name: ${doc.name}`,
+    `description: ${doc.description}`,
+    `version: ${doc.version}`,
+    `created: ${doc.created}`,
+    `updated: ${doc.updated}`,
+  ];
+
+  if (doc.displayName && doc.displayName.trim() && doc.displayName.trim() !== doc.name) {
+    lines.push(`display_name: ${doc.displayName.trim()}`);
+  }
+
+  lines.push("---", doc.body);
+  return lines.join("\n");
+}
+
+export function slugify(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .replace(/--+/g, "-")
+    .slice(0, 64);
+}
+
+export function today(): string {
+  return new Date().toISOString().split("T")[0];
+}
+
+const SKILL_SIMILARITY_STOP_WORDS = new Set([
+  "a", "an", "and", "are", "as", "at", "be", "by", "for", "from", "how", "in", "into", "is", "it",
+  "of", "on", "or", "that", "the", "this", "to", "use", "using", "with", "workflow", "procedure", "step",
+  "steps", "guide", "skill", "skills", "repo", "project",
+]);
+
+export function tokenizeForSimilarity(input: string): string[] {
+  return input
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .split(/\s+/)
+    .map((token) => token.trim())
+    .filter((token) => token.length > 1 && !SKILL_SIMILARITY_STOP_WORDS.has(token));
+}
+
+export function jaccardSimilarity(a: string[], b: string[]): number {
+  const aSet = new Set(a);
+  const bSet = new Set(b);
+  if (aSet.size === 0 || bSet.size === 0) return 0;
+
+  let intersection = 0;
+  for (const token of aSet) {
+    if (bSet.has(token)) intersection++;
+  }
+
+  const union = new Set([...aSet, ...bSet]).size;
+  return union === 0 ? 0 : intersection / union;
+}
+
+export function buildSkillId(scope: SkillScope, slug: string, projectName?: string | null): string {
+  return scope === "project" ? `project:${projectName ?? ""}:${slug}` : `global:${slug}`;
+}
+
+export function parseSkillId(skillId: string): { scope: SkillScope; projectName?: string; slug: string } | null {
+  if (skillId.startsWith("global:")) {
+    return { scope: "global", slug: skillId.slice("global:".length) };
+  }
+
+  if (skillId.startsWith("project:")) {
+    const rest = skillId.slice("project:".length);
+    const idx = rest.indexOf(":");
+    if (idx <= 0 || idx === rest.length - 1) return null;
+    return {
+      scope: "project",
+      projectName: rest.slice(0, idx),
+      slug: rest.slice(idx + 1),
+    };
+  }
+
+  return null;
+}
+
+export async function exists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}

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

@@ -67,6 +67,11 @@ export interface SqliteMemoryRemoveResult {
   removed: number;
 }
 
+export interface SqliteMemoryRemoveOptions {
+  target: 'memory' | 'user' | 'failure';
+  project?: string | null;
+}
+
 export interface ParsedMarkdownMemoryEntry extends SqliteMemorySyncInput {}
 
 function today(): string {
@@ -481,10 +486,7 @@ export function replaceSyncedMemories(
 export function removeSyncedMemories(
   dbManager: DatabaseManager,
   oldText: string,
-  options: {
-    target: 'memory' | 'user' | 'failure';
-    project?: string | null;
-  },
+  options: SqliteMemoryRemoveOptions,
 ): SqliteMemoryRemoveResult {
   const db = dbManager.getDb();
   const params: unknown[] = [];
@@ -512,6 +514,42 @@ export function removeSyncedMemories(
   };
 }
 
+/**
+ * Exact removal for Markdown entries whose full content is known.
+ * Used for FIFO eviction cleanup, where substring matching could remove
+ * unrelated SQLite mirror rows that merely contain the evicted text.
+ */
+export function removeExactSyncedMemories(
+  dbManager: DatabaseManager,
+  content: string,
+  options: SqliteMemoryRemoveOptions,
+): SqliteMemoryRemoveResult {
+  const db = dbManager.getDb();
+  const params: unknown[] = [];
+  const conditions = buildScopeConditions(params, options.target, options.project ?? undefined);
+  conditions.push('content = ?');
+  params.push(content.trim());
+
+  const matchingIds = db.prepare(`
+    SELECT id
+    FROM memories
+    WHERE ${conditions.join(' AND ')}
+  `).all(...params) as Array<{ id: number }>;
+
+  if (matchingIds.length === 0) {
+    return { matched: 0, removed: 0 };
+  }
+
+  const deleteParams = matchingIds.map((row) => row.id);
+  const placeholders = deleteParams.map(() => '?').join(', ');
+  const result = db.prepare(`DELETE FROM memories WHERE id IN (${placeholders})`).run(...deleteParams);
+
+  return {
+    matched: matchingIds.length,
+    removed: result.changes,
+  };
+}
+
 /**
  * Escape a string for FTS5 query syntax.
  * Wraps the query in double quotes to treat it as a literal phrase.

package/src/tools/memory-search-tool.ts

@@ -1,6 +1,6 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { StringEnum } from "@mariozechner/pi-ai";
+import { StringEnum } from "@earendil-works/pi-ai";
 import { DatabaseManager } from '../store/db.js';
 import { searchMemories, getMemoryStats } from '../store/sqlite-memory-store.js';
 import type { MemoryCategory } from '../types.js';

package/src/tools/memory-tool.ts

@@ -4,13 +4,14 @@
  * See PLAN.md → "Hermes Source File Reference Map" for source lines.
  */
 
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { StringEnum } from "@mariozechner/pi-ai";
+import { StringEnum } from "@earendil-works/pi-ai";
 import { MemoryStore } from "../store/memory-store.js";
 import { DatabaseManager } from "../store/db.js";
 import {
   formatFailureMemoryContent,
+  removeExactSyncedMemories,
   removeSyncedMemories,
   replaceSyncedMemories,
   syncMemoryEntry,
@@ -159,6 +160,31 @@ async function syncRemoveFromSqlite(
   }
 }
 
+async function syncEvictionsFromSqlite(
+  rawTarget: "memory" | "user" | "project" | "failure",
+  evictedEntries: string[] | undefined,
+  dbManager: DatabaseManager | null,
+  projectName?: string | null,
+): Promise<void> {
+  if (!dbManager) return;
+  if (!evictedEntries || evictedEntries.length === 0) return;
+
+  const sqliteTarget = sqliteTargetFor(rawTarget);
+  const sqliteProject = sqliteProjectFor(rawTarget, projectName);
+
+  for (const entry of evictedEntries) {
+    try {
+      removeExactSyncedMemories(dbManager, entry, {
+        target: sqliteTarget,
+        project: sqliteProject,
+      });
+    } catch {
+      // FIFO already updated the Markdown source of truth. SQLite is only a
+      // best-effort search mirror, so eviction cleanup must not fail the write.
+    }
+  }
+}
+
 export function registerMemoryTool(
   pi: ExtensionAPI,
   store: MemoryStore,
@@ -247,6 +273,7 @@ export function registerMemoryTool(
           } else {
             result = await store_.add(target, content);
             if (result.success) {
+              await syncEvictionsFromSqlite(rawTarget, result.evicted_entries, dbManager, projectName);
               syncWarning = await syncAddToSqlite(rawTarget, content, undefined, undefined, dbManager, projectName);
             }
           }

package/src/tools/session-search-tool.ts

@@ -1,6 +1,6 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { StringEnum } from "@mariozechner/pi-ai";
+import { StringEnum } from "@earendil-works/pi-ai";
 import { DatabaseManager } from '../store/db.js';
 import { searchSessions, getIndexedMessageCount } from '../store/session-search.js';
 

package/src/tools/skill-tool.ts

@@ -3,9 +3,9 @@
  * Complements the `memory` tool (declarative knowledge) with procedural knowledge.
  */
 
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { StringEnum } from "@mariozechner/pi-ai";
+import { StringEnum } from "@earendil-works/pi-ai";
 import { SkillStore } from "../store/skill-store.js";
 import { SKILL_TOOL_DESCRIPTION } from "../constants.js";
 
@@ -17,7 +17,8 @@ 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.",
+      "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.",
       "Do NOT use skills for temporary task state — only for durable, reusable procedures.",
     ],
     parameters: Type.Object({
@@ -25,12 +26,15 @@ export function registerSkillTool(pi: ExtensionAPI, store: SkillStore): void {
       name: Type.Optional(
         Type.String({ description: "Skill name (for create). e.g., 'debug-typescript-errors'" })
       ),
-      file_name: Type.Optional(
-        Type.String({ description: "Skill file name (for view/patch/edit/delete). e.g., 'debug-typescript-errors.md'" })
+      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'" })
       ),
@@ -39,7 +43,7 @@ export function registerSkillTool(pi: ExtensionAPI, store: SkillStore): void {
       ),
     }),
     async execute(toolCallId, params, signal, onUpdate, ctx) {
-      const { action, name, file_name, description, section, content } = params;
+      const { action, name, skill_id, description, scope, section, content } = params;
 
       let result;
       switch (action) {
@@ -62,22 +66,21 @@ export function registerSkillTool(pi: ExtensionAPI, store: SkillStore): void {
               details: {},
             };
           }
-          result = await store.create(name, description, content);
+          result = await store.create(name, description, content, scope);
           break;
 
         case "view":
-          if (!file_name) {
-            // List all skills
+          if (!skill_id) {
             const index = await store.loadIndex();
             return {
               content: [{ type: "text", text: JSON.stringify({ success: true, skills: index }) }],
               details: { skills: index },
             };
           }
-          const doc = await store.loadSkill(file_name);
+          const doc = await store.loadSkill(skill_id);
           if (!doc) {
             return {
-              content: [{ type: "text", text: JSON.stringify({ success: false, error: `Skill '${file_name}' not found.` }) }],
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: `Skill '${skill_id}' not found.` }) }],
               details: {},
             };
           }
@@ -85,9 +88,9 @@ export function registerSkillTool(pi: ExtensionAPI, store: SkillStore): void {
           break;
 
         case "patch":
-          if (!file_name) {
+          if (!skill_id) {
             return {
-              content: [{ type: "text", text: JSON.stringify({ success: false, error: "file_name is required for 'patch' action." }) }],
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: "skill_id is required for 'patch' action." }) }],
               details: {},
             };
           }
@@ -103,27 +106,27 @@ export function registerSkillTool(pi: ExtensionAPI, store: SkillStore): void {
               details: {},
             };
           }
-          result = await store.patch(file_name, section, content);
+          result = await store.patch(skill_id, section, content);
           break;
 
         case "edit":
-          if (!file_name) {
+          if (!skill_id) {
             return {
-              content: [{ type: "text", text: JSON.stringify({ success: false, error: "file_name is required for 'edit' action." }) }],
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: "skill_id is required for 'edit' action." }) }],
               details: {},
             };
           }
-          result = await store.edit(file_name, description || "", content || "");
+          result = await store.edit(skill_id, description || "", content || "");
           break;
 
         case "delete":
-          if (!file_name) {
+          if (!skill_id) {
             return {
-              content: [{ type: "text", text: JSON.stringify({ success: false, error: "file_name is required for 'delete' action." }) }],
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: "skill_id is required for 'delete' action." }) }],
               details: {},
             };
           }
-          result = await store.delete(file_name);
+          result = await store.delete(skill_id);
           break;
 
         default:

package/src/types.ts

@@ -2,7 +2,7 @@
  * Shared TypeScript types for the Hermes Memory extension.
  */
 
-import type { TextContent } from "@mariozechner/pi-ai";
+import type { TextContent } from "@earendil-works/pi-ai";
 
 export type MemoryOverflowStrategy = "auto-consolidate" | "reject" | "fifo-evict";
 
@@ -59,6 +59,8 @@ export interface MemoryConfig {
   failureInjectionMaxEntries: number;
   /** Tool calls before triggering background review (in addition to turn count). Default: 15 */
   nudgeToolCalls: number;
+  /** Maximum time in milliseconds for auto-consolidation to complete. Default: 60000 */
+  consolidationTimeoutMs: number;
   /** Enable session history search via SQLite FTS5. Default: true */
   sessionSearchEnabled?: boolean;
   /** Days to retain session history. Default: 90 */
@@ -100,12 +102,24 @@ export interface ConsolidationResult {
   error?: string;
 }
 
+export type SkillScope = "global" | "project";
+
 export interface SkillIndex {
-  /** File name (slug.md) */
+  /** Stable id for read/update/delete operations */
+  skillId: string;
+  /** Whether the skill is global or project-scoped */
+  scope: SkillScope;
+  /** File name on disk (usually SKILL.md) */
   fileName: string;
-  /** Human-readable name */
+  /** Absolute path to the skill file */
+  path: string;
+  /** Active project name for project-scoped skills */
+  projectName?: string;
+  /** Pi skill slug stored in frontmatter and folder name */
   name: string;
-  /** Short description for system prompt index */
+  /** Optional human-friendly title preserved for UI output */
+  displayName?: string;
+  /** Short description shown in skill listings */
   description: string;
 }
 
@@ -125,6 +139,12 @@ export interface SkillResult {
   error?: string;
   message?: string;
   fileName?: string;
+  skillId?: string;
+  scope?: SkillScope;
+  path?: string;
+  conflictType?: "duplicate" | "similar" | "name-collision";
+  similarSkillIds?: string[];
+  suggestedAction?: "patch" | "edit" | "rename";
 }
 
 /**