pi-hermes-memory 0.1.0 → 0.2.0

package/src/store/skill-store.ts

@@ -0,0 +1,292 @@
+/**
+ * SkillStore — procedural memory stored as SKILL.md files.
+ *
+ * Skills capture HOW to do something (procedural knowledge), as opposed
+ * to MemoryStore which captures WHAT (declarative knowledge).
+ *
+ * Storage: ~/.pi/agent/memory/skills/<slug>.md
+ * Format: YAML-like frontmatter + markdown body (no yaml dependency)
+ * Progressive disclosure: index (name+description) in system prompt,
+ *   full content loaded on demand via skill tool.
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+import { scanContent } from "./content-scanner.js";
+import type { SkillIndex, SkillDocument, SkillResult } from "../types.js";
+
+// ─── Frontmatter parsing ───
+
+function parseFrontmatter(raw: string): { meta: Record<string, string>; body: string } {
+  const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) return { meta: {}, body: raw };
+
+  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() };
+}
+
+function formatFrontmatter(doc: Omit<SkillDocument, "fileName">): string {
+  return [
+    "---",
+    `name: ${doc.name}`,
+    `description: ${doc.description}`,
+    `version: ${doc.version}`,
+    `created: ${doc.created}`,
+    `updated: ${doc.updated}`,
+    "---",
+    doc.body,
+  ].join("\n");
+}
+
+// ─── Slugify ───
+
+function slugify(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 64);
+}
+
+// ─── SkillStore ───
+
+export class SkillStore {
+  private skillsDir: string;
+
+  constructor(skillsDir?: string) {
+    this.skillsDir = skillsDir ?? path.join(os.homedir(), ".pi", "agent", "memory", "skills");
+  }
+
+  // ─── Read ───
+
+  async loadIndex(): Promise<SkillIndex[]> {
+    await fs.mkdir(this.skillsDir, { recursive: true });
+    const files = await fs.readdir(this.skillsDir);
+    const skills: SkillIndex[] = [];
+
+    for (const file of files) {
+      if (!file.endsWith(".md")) continue;
+      const doc = await this.loadSkill(file);
+      if (doc) {
+        skills.push({ fileName: doc.fileName, name: doc.name, description: doc.description });
+      }
+    }
+
+    return skills;
+  }
+
+  async loadSkill(fileName: string): Promise<SkillDocument | null> {
+    try {
+      const raw = await fs.readFile(path.join(this.skillsDir, fileName), "utf-8");
+      const { meta, body } = parseFrontmatter(raw);
+      if (!meta.name) return null;
+      return {
+        fileName,
+        name: meta.name,
+        description: meta.description || "",
+        version: parseInt(meta.version || "1", 10),
+        created: meta.created || new Date().toISOString().split("T")[0],
+        updated: meta.updated || new Date().toISOString().split("T")[0],
+        body,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  // ─── Write ───
+
+  async create(name: string, description: string, body: string): Promise<SkillResult> {
+    name = name.trim();
+    description = description.trim();
+    body = body.trim();
+
+    if (!name) return { success: false, error: "Skill name is required." };
+    if (!description) return { success: false, error: "Skill description is required." };
+    if (!body) return { success: false, error: "Skill body is required." };
+
+    // Scan content for security
+    const scanError = scanContent(name + " " + description + " " + body);
+    if (scanError) return { success: false, error: scanError };
+
+    const slug = slugify(name);
+    if (!slug) return { success: false, error: "Skill name produces empty slug." };
+
+    const fileName = `${slug}.md`;
+    const filePath = path.join(this.skillsDir, fileName);
+
+    // Check if file already exists
+    try {
+      await fs.access(filePath);
+      return {
+        success: false,
+        error: `Skill '${name}' already exists (file: ${fileName}). Use 'patch' or 'edit' to update it.`,
+      };
+    } catch {
+      // File doesn't exist — good
+    }
+
+    await fs.mkdir(this.skillsDir, { recursive: true });
+
+    const today = new Date().toISOString().split("T")[0];
+    const doc: Omit<SkillDocument, "fileName"> = {
+      name,
+      description,
+      version: 1,
+      created: today,
+      updated: today,
+      body,
+    };
+
+    await this.atomicWrite(fileName, formatFrontmatter(doc));
+
+    return { success: true, message: `Skill '${name}' created.`, fileName };
+  }
+
+  async patch(fileName: string, section: string, newContent: string): Promise<SkillResult> {
+    newContent = newContent.trim();
+    if (!newContent) return { success: false, error: "New content is required for patch." };
+
+    const scanError = scanContent(newContent);
+    if (scanError) return { success: false, error: scanError };
+
+    const doc = await this.loadSkill(fileName);
+    if (!doc) return { success: false, error: `Skill file '${fileName}' not found.` };
+
+    // Replace or append the section in the body
+    const sectionHeader = `## ${section}`;
+    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)) {
+        // Replace this section — skip old content until next section or end
+        result.push(sectionHeader);
+        result.push(newContent);
+        found = true;
+        // Skip lines until next ## header or end
+        i++;
+        while (i < lines.length && !lines[i].startsWith("## ")) {
+          i++;
+        }
+        // Don't skip the next ## header
+        if (i < lines.length) {
+          result.push(lines[i]);
+        }
+      } else {
+        result.push(lines[i]);
+      }
+    }
+
+    if (!found) {
+      // Append the section
+      result.push("", sectionHeader, newContent);
+    }
+
+    const today = new Date().toISOString().split("T")[0];
+    const updated: Omit<SkillDocument, "fileName"> = {
+      name: doc.name,
+      description: doc.description,
+      version: doc.version + 1,
+      created: doc.created,
+      updated: today,
+      body: result.join("\n").trim(),
+    };
+
+    await this.atomicWrite(fileName, formatFrontmatter(updated));
+
+    return { success: true, message: `Skill '${doc.name}' section '${section}' updated.`, fileName };
+  }
+
+  async edit(fileName: string, description: string, body: string): Promise<SkillResult> {
+    description = description.trim();
+    body = body.trim();
+
+    if (!description && !body) {
+      return { success: false, error: "At least one of description or body is required." };
+    }
+
+    const doc = await this.loadSkill(fileName);
+    if (!doc) return { success: false, error: `Skill file '${fileName}' not found.` };
+
+    const newDesc = description || doc.description;
+    const newBody = body || doc.body;
+
+    // Scan combined content
+    const scanError = scanContent(newDesc + " " + newBody);
+    if (scanError) return { success: false, error: scanError };
+
+    const today = new Date().toISOString().split("T")[0];
+    const updated: Omit<SkillDocument, "fileName"> = {
+      name: doc.name,
+      description: newDesc,
+      version: doc.version + 1,
+      created: doc.created,
+      updated: today,
+      body: newBody,
+    };
+
+    await this.atomicWrite(fileName, formatFrontmatter(updated));
+
+    return { success: true, message: `Skill '${doc.name}' updated.`, fileName };
+  }
+
+  async delete(fileName: string): Promise<SkillResult> {
+    const doc = await this.loadSkill(fileName);
+    if (!doc) return { success: false, error: `Skill file '${fileName}' not found.` };
+
+    await fs.unlink(path.join(this.skillsDir, fileName));
+
+    return { success: true, message: `Skill '${doc.name}' deleted.`, fileName };
+  }
+
+  // ─── System prompt injection (progressive disclosure) ───
+
+  async formatIndexForSystemPrompt(): Promise<string> {
+    const skills = await this.loadIndex();
+    if (skills.length === 0) return "";
+
+    const lines: string[] = [
+      "═".repeat(46),
+      `SKILLS (procedural memory) [${skills.length} skills]`,
+      "═".repeat(46),
+      "Use the 'skill' tool with action 'view' to load full content on demand.",
+      "",
+    ];
+
+    for (const skill of skills) {
+      lines.push(`• ${skill.name}: ${skill.description}`);
+    }
+
+    return lines.join("\n");
+  }
+
+  // ─── Internal helpers ───
+
+  /** Atomic write: temp file + rename (same crash-safety as MemoryStore) */
+  private async atomicWrite(fileName: string, content: string): Promise<void> {
+    const filePath = path.join(this.skillsDir, fileName);
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "pi-skill-"));
+    const tmpPath = path.join(tmpDir, "write.tmp");
+
+    try {
+      await fs.writeFile(tmpPath, content, "utf-8");
+      await fs.rename(tmpPath, filePath);
+    } catch (err) {
+      try { await fs.unlink(tmpPath); } catch { /* ignore */ }
+      throw err;
+    } finally {
+      try { await fs.rmdir(tmpDir); } catch { /* ignore */ }
+    }
+  }
+}

package/src/tools/memory-tool.ts

@@ -55,7 +55,7 @@ export function registerMemoryTool(pi: ExtensionAPI, store: MemoryStore): void {
               details: {},
             };
           }
-          result = store.add(target, content);
+          result = await store.add(target, content);
           break;
 
         case "replace":

package/src/tools/skill-tool.ts

@@ -0,0 +1,142 @@
+/**
+ * Skill tool — registers the LLM-callable `skill` tool for procedural memory.
+ * Complements the `memory` tool (declarative knowledge) with procedural knowledge.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "typebox";
+import { StringEnum } from "@mariozechner/pi-ai";
+import { SkillStore } from "../store/skill-store.js";
+import { SKILL_TOOL_DESCRIPTION } from "../constants.js";
+
+export function registerSkillTool(pi: ExtensionAPI, store: SkillStore): void {
+  pi.registerTool({
+    name: "skill",
+    label: "Skill",
+    description: SKILL_TOOL_DESCRIPTION,
+    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.",
+      "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'" })
+      ),
+      file_name: Type.Optional(
+        Type.String({ description: "Skill file name (for view/patch/edit/delete). e.g., 'debug-typescript-errors.md'" })
+      ),
+      description: Type.Optional(
+        Type.String({ description: "One-line description of when to use this skill (for create/edit)" })
+      ),
+      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" })
+      ),
+    }),
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const { action, name, file_name, description, section, content } = params;
+
+      let result;
+      switch (action) {
+        case "create":
+          if (!name) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: "name is required for 'create' action." }) }],
+              details: {},
+            };
+          }
+          if (!description) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: "description is required for 'create' action." }) }],
+              details: {},
+            };
+          }
+          if (!content) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: "content (skill body) is required for 'create' action." }) }],
+              details: {},
+            };
+          }
+          result = await store.create(name, description, content);
+          break;
+
+        case "view":
+          if (!file_name) {
+            // List all skills
+            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);
+          if (!doc) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: `Skill '${file_name}' not found.` }) }],
+              details: {},
+            };
+          }
+          result = { success: true, ...doc };
+          break;
+
+        case "patch":
+          if (!file_name) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: "file_name is required for 'patch' action." }) }],
+              details: {},
+            };
+          }
+          if (!section) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: "section is required for 'patch' action." }) }],
+              details: {},
+            };
+          }
+          if (!content) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: "content is required for 'patch' action." }) }],
+              details: {},
+            };
+          }
+          result = await store.patch(file_name, section, content);
+          break;
+
+        case "edit":
+          if (!file_name) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: "file_name is required for 'edit' action." }) }],
+              details: {},
+            };
+          }
+          result = await store.edit(file_name, description || "", content || "");
+          break;
+
+        case "delete":
+          if (!file_name) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ success: false, error: "file_name is required for 'delete' action." }) }],
+              details: {},
+            };
+          }
+          result = await store.delete(file_name);
+          break;
+
+        default:
+          result = {
+            success: false,
+            error: `Unknown action '${action}'. Use: create, view, patch, edit, delete`,
+          };
+      }
+
+      return {
+        content: [{ type: "text", text: JSON.stringify(result) }],
+        details: result,
+      };
+    },
+  });
+}

package/src/types.ts

@@ -21,6 +21,12 @@ export interface MemoryConfig {
   flushMinTurns: number;
   /** Override memory directory. Default: ~/.pi/agent/memory */
   memoryDir?: string;
+  /** Auto-consolidate when memory is full instead of returning error. Default: true */
+  autoConsolidate: boolean;
+  /** Detect user corrections and trigger immediate memory save. Default: true */
+  correctionDetection: boolean;
+  /** Tool calls before triggering background review (in addition to turn count). Default: 15 */
+  nudgeToolCalls: number;
 }
 
 export interface MemoryResult {
@@ -39,6 +45,40 @@ export interface MemorySnapshot {
   user: string;
 }
 
+export interface ConsolidationResult {
+  /** Whether consolidation succeeded */
+  consolidated: boolean;
+  /** Error message if consolidation failed */
+  error?: string;
+}
+
+export interface SkillIndex {
+  /** File name (slug.md) */
+  fileName: string;
+  /** Human-readable name */
+  name: string;
+  /** Short description for system prompt index */
+  description: string;
+}
+
+export interface SkillDocument extends SkillIndex {
+  /** Full markdown body (after frontmatter) */
+  body: string;
+  /** Version number */
+  version: number;
+  /** ISO date created */
+  created: string;
+  /** ISO date last updated */
+  updated: string;
+}
+
+export interface SkillResult {
+  success: boolean;
+  error?: string;
+  message?: string;
+  fileName?: string;
+}
+
 /**
  * Extract displayable text from a Pi session entry message.
  *