pi-hermes-memory 0.1.0 → 0.2.0

package/src/handlers/auto-consolidate.ts

@@ -0,0 +1,94 @@
+/**
+ * Auto-consolidation — when memory hits capacity, trigger automatic
+ * consolidation instead of returning an error.
+ *
+ * Uses pi.exec() to spawn a one-shot consolidation process.
+ * The child process modifies files on disk, so the parent MUST reload
+ * from disk after consolidation completes.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { MemoryStore } from "../store/memory-store.js";
+import { CONSOLIDATION_PROMPT, ENTRY_DELIMITER } from "../constants.js";
+import type { ConsolidationResult } from "../types.js";
+
+export async function triggerConsolidation(
+  pi: ExtensionAPI,
+  store: MemoryStore,
+  target: "memory" | "user",
+  signal?: AbortSignal,
+): Promise<ConsolidationResult> {
+  const entries =
+    target === "memory" ? store.getMemoryEntries() : store.getUserEntries();
+  const currentContent = entries.join(ENTRY_DELIMITER);
+
+  const prompt = [
+    CONSOLIDATION_PROMPT,
+    "",
+    `--- Current ${target === "user" ? "User Profile" : "Memory"} Entries ---`,
+    currentContent || "(empty)",
+    "",
+    `Use the memory tool to consolidate. Target: '${target}'`,
+  ].join("\n");
+
+  try {
+    const result = await pi.exec("pi", ["-p", "--no-session", prompt], {
+      signal,
+      timeout: 60000,
+    });
+
+    if (result.code === 0) {
+      return { consolidated: true };
+    }
+    return {
+      consolidated: false,
+      error: `Consolidation process exited with code ${result.code}: ${result.stderr?.slice(0, 200) || "unknown error"}`,
+    };
+  } catch (err) {
+    return {
+      consolidated: false,
+      error: `Consolidation failed: ${String(err).slice(0, 200)}`,
+    };
+  }
+}
+
+/**
+ * Register the /memory-consolidate command for manual consolidation.
+ */
+export function registerConsolidateCommand(
+  pi: ExtensionAPI,
+  store: MemoryStore,
+): void {
+  pi.registerCommand("memory-consolidate", {
+    description: "Manually trigger memory consolidation to free up space",
+    handler: async (_args, ctx) => {
+      const results: string[] = [];
+
+      for (const target of ["memory", "user"] as const) {
+        const entries =
+          target === "memory"
+            ? store.getMemoryEntries()
+            : store.getUserEntries();
+
+        if (entries.length === 0) {
+          results.push(`${target}: (empty, nothing to consolidate)`);
+          continue;
+        }
+
+        const result = await triggerConsolidation(pi, store, target, ctx.signal);
+
+        if (result.consolidated) {
+          await store.loadFromDisk();
+          results.push(`${target}: ✅ consolidated`);
+        } else {
+          results.push(`${target}: ❌ ${result.error}`);
+        }
+      }
+
+      ctx.ui.notify(
+        `\n  🔄 Memory Consolidation\n  ${"─".repeat(30)}\n${results.map((r) => `  ${r}`).join("\n")}`,
+        "info",
+      );
+    },
+  });
+}

package/src/handlers/background-review.ts

@@ -19,6 +19,7 @@ export function setupBackgroundReview(
   config: MemoryConfig,
 ): void {
   let turnsSinceReview = 0;
+  let toolCallsSinceReview = 0;
   let userTurnCount = 0;
   let reviewInProgress = false;
 
@@ -33,10 +34,35 @@ export function setupBackgroundReview(
 
     if (!config.reviewEnabled) return;
     if (reviewInProgress) return;
-    if (turnsSinceReview < config.nudgeInterval) return;
+
+    // Count tool-use entries from the branch for tool-call-aware nudge
+    try {
+      const branch = ctx.sessionManager.getBranch();
+      for (const entry of branch) {
+        if (entry.type === "message" && entry.message?.role === "assistant") {
+          const content = entry.message?.content;
+          if (Array.isArray(content)) {
+            for (const block of content) {
+              if (block && typeof block === "object" && block.type === "toolCall") {
+                toolCallsSinceReview++;
+              }
+            }
+          }
+        }
+      }
+    } catch {
+      // If we can't count tool calls, fall back to turn-based only
+    }
+
+    // Trigger on EITHER turn count OR tool call count
+    const turnThresholdMet = turnsSinceReview >= config.nudgeInterval;
+    const toolCallThresholdMet = toolCallsSinceReview >= config.nudgeToolCalls;
+
+    if (!turnThresholdMet && !toolCallThresholdMet) return;
     if (userTurnCount < 3) return;
 
     turnsSinceReview = 0;
+    toolCallsSinceReview = 0;
     reviewInProgress = true;
 
     try {

package/src/handlers/correction-detector.ts

@@ -0,0 +1,143 @@
+/**
+ * Correction detection — detects user corrections in real-time and triggers
+ * an immediate memory save instead of waiting for the next nudge interval.
+ *
+ * Uses a two-pass filter:
+ * - Strong patterns: always trigger (high confidence)
+ * - Weak patterns: only trigger if followed by a directive clause
+ * - Negative patterns: suppress even if a positive pattern matched
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { MemoryStore } from "../store/memory-store.js";
+import {
+  CORRECTION_SAVE_PROMPT,
+  CORRECTION_STRONG_PATTERNS,
+  CORRECTION_WEAK_PATTERNS,
+  CORRECTION_NEGATIVE_PATTERNS,
+  ENTRY_DELIMITER,
+} from "../constants.js";
+import type { MemoryConfig } from "../types.js";
+import { getMessageText } from "../types.js";
+
+/**
+ * Check if a user message is a correction using the two-pass filter.
+ * Returns true if the message should trigger an immediate save.
+ */
+export function isCorrection(text: string): boolean {
+  // Check negative patterns first — suppress even if positive matches
+  for (const pattern of CORRECTION_NEGATIVE_PATTERNS) {
+    if (pattern.test(text)) return false;
+  }
+
+  // Check strong patterns — always trigger
+  for (const pattern of CORRECTION_STRONG_PATTERNS) {
+    if (pattern.test(text)) return true;
+  }
+
+  // Check weak patterns — only trigger if followed by a directive clause
+  for (const pattern of CORRECTION_WEAK_PATTERNS) {
+    if (pattern.test(text)) {
+      // Look for a directive after the weak pattern match
+      // Directive = a verb or "the/that/this" in the remainder of the text
+      const match = pattern.exec(text);
+      if (match && match.index === 0) {
+        const remainder = text.slice(match[0].length).trim();
+        // Simple heuristic: remainder contains something directive-ish
+        if (/\b(use|don'?t|do|try|make|run|install|add|remove|delete|change|fix|put|set|write|go|stop|start|the|that|this|it)\b/i.test(remainder)) {
+          return true;
+        }
+      }
+    }
+  }
+
+  return false;
+}
+
+export function setupCorrectionDetector(
+  pi: ExtensionAPI,
+  store: MemoryStore,
+  config: MemoryConfig,
+): void {
+  if (!config.correctionDetection) return;
+
+  let pendingCorrection = false;
+  let turnsSinceLastCorrection = 3; // Start at threshold so first correction can fire immediately
+  let correctionInProgress = false;
+
+  // Flag on message_end (user role)
+  pi.on("message_end", async (event, _ctx) => {
+    if (event.message.role !== "user") return;
+    const text = getMessageText(event.message);
+    if (!text) return;
+    if (isCorrection(text)) {
+      pendingCorrection = true;
+    }
+  });
+
+  // Trigger on turn_end (we need full context: user correction + what agent said)
+  pi.on("turn_end", async (event, ctx) => {
+    if (!pendingCorrection) {
+      turnsSinceLastCorrection++;
+      return;
+    }
+    pendingCorrection = false;
+
+    // Rate limit: max 1 correction save per 3 turns
+    if (turnsSinceLastCorrection < 3) return;
+    if (correctionInProgress) return;
+
+    turnsSinceLastCorrection = 0;
+    correctionInProgress = true;
+
+    try {
+      // Build conversation snapshot
+      const entries = ctx.sessionManager.getBranch();
+      const parts: string[] = [];
+
+      for (const entry of entries) {
+        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 last few exchanges (correction context is recent)
+      const recentParts = parts.slice(-6);
+
+      const currentMemory = store.getMemoryEntries().join(ENTRY_DELIMITER);
+      const currentUser = store.getUserEntries().join(ENTRY_DELIMITER);
+
+      const prompt = [
+        CORRECTION_SAVE_PROMPT,
+        "",
+        "--- Current Memory ---",
+        currentMemory || "(empty)",
+        "",
+        "--- Current User Profile ---",
+        currentUser || "(empty)",
+        "",
+        "--- Recent Conversation ---",
+        recentParts.join("\n\n"),
+      ].join("\n");
+
+      const result = await pi.exec("pi", ["-p", "--no-session", prompt], {
+        signal: ctx.signal,
+        timeout: 30000,
+      });
+
+      if (result.code === 0 && result.stdout) {
+        const output = result.stdout.trim();
+        if (output && !output.toLowerCase().includes("nothing to save")) {
+          ctx.ui.notify("🔧 Correction detected — memory updated", "info");
+        }
+      }
+    } catch {
+      // Best-effort — don't block the session
+    } finally {
+      correctionInProgress = false;
+    }
+  });
+}

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

@@ -0,0 +1,108 @@
+/**
+ * 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 type { ExtensionAPI } from "@mariozechner/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";
+
+export function setupSkillAutoTrigger(
+  pi: ExtensionAPI,
+  store: MemoryStore,
+  skillStore: SkillStore,
+  config: MemoryConfig,
+): void {
+  let triggeredThisSession = false;
+
+  pi.on("turn_end", async (event, ctx) => {
+    if (triggeredThisSession) return;
+
+    // Count tool-use entries from this turn's branch
+    let toolCallCount = 0;
+    const toolTypes = new Set<string>();
+
+    try {
+      const branch = ctx.sessionManager.getBranch();
+      for (const entry of branch) {
+        if (entry.type === "message" && entry.message?.role === "assistant") {
+          const content = entry.message?.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((s) => `${s.fileName}: ${s.name} - ${s.description}`).join("\n");
+
+      const prompt = [
+        "This was a complex task that required multiple tool calls. Extract any reusable procedures as skills.",
+        "",
+        "--- 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' to update it.",
+        "If nothing reusable happened, say 'Nothing to extract.' and stop.",
+      ].join("\n");
+
+      const result = await pi.exec("pi", ["-p", "--no-session", 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
+    }
+  });
+}

package/src/handlers/skills-command.ts

@@ -0,0 +1,38 @@
+/**
+ * Skills command — /memory-skills lists all agent-created skills.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { SkillStore } from "../store/skill-store.js";
+
+export function registerSkillsCommand(pi: ExtensionAPI, store: SkillStore): void {
+  pi.registerCommand("memory-skills", {
+    description: "List all agent-created skills (procedural memory)",
+    handler: async (_args, ctx) => {
+      const skills = await store.loadIndex();
+
+      const lines: string[] = [];
+      lines.push("");
+      lines.push("  ╔══════════════════════════════════════════════╗");
+      lines.push("  ║            🧠 Procedural Skills             ║");
+      lines.push("  ╚══════════════════════════════════════════════╝");
+      lines.push("");
+
+      if (skills.length === 0) {
+        lines.push("  (no skills created yet)");
+        lines.push("");
+        lines.push("  Skills are auto-created after complex tasks,");
+        lines.push("  or you can ask the agent to create one.");
+      } else {
+        for (const skill of skills) {
+          lines.push(`  📄 ${skill.name}`);
+          lines.push(`     ${skill.description}`);
+          lines.push(`     file: ${skill.fileName}`);
+          lines.push("");
+        }
+      }
+
+      ctx.ui.notify(lines.join("\n"), "info");
+    },
+  });
+}

package/src/index.ts

@@ -7,35 +7,57 @@
  * 1. Persistent Memory — MEMORY.md + USER.md that survive across sessions
  * 2. Background Learning Loop — auto-saves notable facts every N turns
  * 3. Session-End Flush — saves memories before compaction/shutdown
- * 4. /memory-insights — shows what's stored
+ * 4. Auto-Consolidation — merges memory when full instead of erroring
+ * 5. Correction Detection — immediate save on user corrections
+ * 6. Procedural Skills — SKILL.md files for reusable procedures
+ * 7. Tool-Call-Aware Nudge — review triggers on tool call count too
+ * 8. /memory-insights — shows what's stored
+ * 9. /memory-skills — lists procedural skills
+ * 10. /memory-consolidate — manual consolidation trigger
  *
- * See PLAN.md for full architecture and Hermes source references.
+ * See docs/ROADMAP.md for full roadmap and Hermes competitive analysis.
  */
 
+import * as path from "node:path";
+import * as os from "node:os";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { MemoryStore } from "./store/memory-store.js";
+import { SkillStore } from "./store/skill-store.js";
 import { registerMemoryTool } from "./tools/memory-tool.js";
+import { registerSkillTool } from "./tools/skill-tool.js";
 import { setupBackgroundReview } from "./handlers/background-review.js";
 import { setupSessionFlush } from "./handlers/session-flush.js";
 import { registerInsightsCommand } from "./handlers/insights.js";
+import { triggerConsolidation, registerConsolidateCommand } from "./handlers/auto-consolidate.js";
+import { setupCorrectionDetector } from "./handlers/correction-detector.js";
+import { setupSkillAutoTrigger } from "./handlers/skill-auto-trigger.js";
+import { registerSkillsCommand } from "./handlers/skills-command.js";
 import { loadConfig } from "./config.js";
 
 export default function (pi: ExtensionAPI) {
   const config = loadConfig();
 
+  const memoryDir = config.memoryDir ?? path.join(os.homedir(), ".pi", "agent", "memory");
   const store = new MemoryStore(config);
+  const skillStore = new SkillStore(path.join(memoryDir, "skills"));
 
   // ── 1. Load memory from disk on session start ──
   pi.on("session_start", async (_event, _ctx) => {
     await store.loadFromDisk();
   });
 
-  // ── 2. Inject frozen snapshot into system prompt ──
+  // ── 2. Inject frozen snapshot + skill index into system prompt ──
   pi.on("before_agent_start", async (event, _ctx) => {
     const memoryBlock = store.formatForSystemPrompt();
-    if (memoryBlock) {
+    const skillIndex = await skillStore.formatIndexForSystemPrompt();
+
+    const parts: string[] = [];
+    if (memoryBlock) parts.push(memoryBlock);
+    if (skillIndex) parts.push(skillIndex);
+
+    if (parts.length > 0) {
       return {
-        systemPrompt: event.systemPrompt + "\n\n" + memoryBlock,
+        systemPrompt: event.systemPrompt + "\n\n" + parts.join("\n\n"),
       };
     }
   });
@@ -43,12 +65,28 @@ export default function (pi: ExtensionAPI) {
   // ── 3. Register the memory tool ──
   registerMemoryTool(pi, store);
 
-  // ── 4. Setup background learning loop ──
+  // ── 4. Register the skill tool ──
+  registerSkillTool(pi, skillStore);
+
+  // ── 5. Setup background learning loop (with tool-call-aware nudge) ──
   setupBackgroundReview(pi, store, config);
 
-  // ── 5. Setup session-end flush ──
+  // ── 6. Setup session-end flush ──
   setupSessionFlush(pi, store, config);
 
-  // ── 6. Register insights command ──
+  // ── 7. Setup auto-consolidation (inject consolidator into store) ──
+  store.setConsolidator(async (target, signal) => {
+    return triggerConsolidation(pi, store, target, signal);
+  });
+  registerConsolidateCommand(pi, store);
+
+  // ── 8. Setup correction detection ──
+  setupCorrectionDetector(pi, store, config);
+
+  // ── 9. Setup skill auto-trigger ──
+  setupSkillAutoTrigger(pi, store, skillStore, config);
+
+  // ── 10. Register commands ──
   registerInsightsCommand(pi, store);
+  registerSkillsCommand(pi, skillStore);
 }

package/src/store/memory-store.ts

@@ -22,15 +22,24 @@ import {
   MEMORY_FILE,
   USER_FILE,
 } from "../constants.js";
-import type { MemoryConfig, MemoryResult, MemorySnapshot } from "../types.js";
+import type { MemoryConfig, MemoryResult, MemorySnapshot, ConsolidationResult } from "../types.js";
 
 export class MemoryStore {
   private memoryEntries: string[] = [];
   private userEntries: string[] = [];
   private snapshot: MemorySnapshot = { memory: "", user: "" };
+  private consolidator: ((target: "memory" | "user", signal?: AbortSignal) => Promise<ConsolidationResult>) | null = null;
 
   constructor(private config: MemoryConfig) {}
 
+  /**
+   * Inject a consolidation function (avoids circular imports).
+   * Called from index.ts after both store and pi are available.
+   */
+  setConsolidator(fn: (target: "memory" | "user", signal?: AbortSignal) => Promise<ConsolidationResult>): void {
+    this.consolidator = fn;
+  }
+
   // ─── Path helpers ───
 
   private get memoryDir(): string {
@@ -79,7 +88,7 @@ export class MemoryStore {
 
   // ─── CRUD ───
 
-  add(target: "memory" | "user", content: string): MemoryResult {
+  async add(target: "memory" | "user", content: string, signal?: AbortSignal): Promise<MemoryResult> {
     content = content.trim();
     if (!content) return { success: false, error: "Content cannot be empty." };
 
@@ -95,6 +104,20 @@ export class MemoryStore {
 
     const newTotal = [...entries, content].join(ENTRY_DELIMITER).length;
     if (newTotal > limit) {
+      // Auto-consolidate if configured and consolidator available
+      if (this.config.autoConsolidate && this.consolidator) {
+        try {
+          const result = await this.consolidator(target, signal);
+          if (result.consolidated) {
+            // CRITICAL: reload from disk — child process modified files, our arrays are stale
+            await this.loadFromDisk();
+            // Retry the add with fresh data
+            return this.add(target, content, signal);
+          }
+        } catch {
+          // Consolidation failed — fall through to error
+        }
+      }
       const current = this.charCount(target);
       return {
         success: false,