pi-hermes-memory 0.1.0 → 0.2.1

package/src/constants.ts

@@ -12,8 +12,12 @@ export const DEFAULT_MEMORY_CHAR_LIMIT = 2200;
 export const DEFAULT_USER_CHAR_LIMIT = 1375;
 
 // ─── Learning loop defaults ───
+export const DEFAULT_PROJECT_CHAR_LIMIT = 2200;
+
 export const DEFAULT_NUDGE_INTERVAL = 10;
 export const DEFAULT_FLUSH_MIN_TURNS = 6;
+export const DEFAULT_NUDGE_TOOL_CALLS = 15;
+export const DEFAULT_SKILL_TRIGGER_TOOL_CALLS = 8;
 
 // ─── File names ───
 export const MEMORY_FILE = "MEMORY.md";
@@ -33,9 +37,10 @@ PRIORITY: User preferences and corrections > environment facts > procedural know
 
 Do NOT save task progress, session outcomes, completed-work logs, or temporary TODO state.
 
-TWO TARGETS:
+THREE TARGETS:
 - 'user': who the user is -- name, role, preferences, communication style, pet peeves
-- 'memory': your notes -- environment facts, project conventions, tool quirks, lessons learned
+- 'memory': your global notes -- environment facts, tool quirks, lessons learned (shared across all projects)
+- 'project': project-specific notes -- architecture decisions, API quirks, team norms, codebase conventions (scoped to current project)
 
 ACTIONS: add (new entry), replace (update existing -- old_text identifies it), remove (delete -- old_text identifies it).`;
 
@@ -44,9 +49,79 @@ export const COMBINED_REVIEW_PROMPT = `Review the conversation above and conside
 
 **Memory**: Has the user revealed things about themselves — their persona, desires, preferences, or personal details? Has the user expressed expectations about how you should behave, their work style, or ways they want you to operate? If so, save using the memory tool.
 
-**Skills**: Was a non-trivial approach used to complete a task that required trial and error, or changing course due to experiential findings along the way, or did the user expect or desire a different method or outcome?
+**Skills**: Was a complex, non-trivial approach used to complete a task — one that required trial and error, multiple tool calls, or changing course? If so, save a reusable procedure using the skill tool with action 'create'. Include: when to use it, step-by-step procedure, pitfalls to avoid, and how to verify success. If a related skill already exists, use action 'patch' to update it instead of creating a duplicate.
 
 Only act if there's something genuinely worth saving. If nothing stands out, just say 'Nothing to save.' and stop.`;
 
 // ─── Flush prompt (ported from flush_memories() in run_agent.py ~L7379) ───
 export const FLUSH_PROMPT = `[System: The session is being compressed. Save anything worth remembering — prioritize user preferences, corrections, and recurring patterns over task-specific details.]`;
+
+// ─── Auto-consolidation prompt ───
+export const CONSOLIDATION_PROMPT = `The memory is at capacity. Review the current entries and consolidate them:
+- Merge related entries into a single, concise entry
+- Remove outdated or superseded entries
+- Keep the most important and frequently-referenced facts
+- Preserve user preferences and corrections (highest priority)
+
+Use the memory tool to make changes. Be aggressive about merging — less is more.`;
+
+// ─── Correction detection patterns (two-pass filter) ───
+
+/** Strong patterns — always trigger (high confidence these are corrections) */
+export const CORRECTION_STRONG_PATTERNS: RegExp[] = [
+  /don'?t do that/i,
+  /not like that/i,
+  /^I said\b/i,
+  /^I told you\b/i,
+  /we already discussed/i,
+  /^please don'?t/i,
+  /^that'?s not what I/i,
+];
+
+/** Weak patterns — only trigger if followed by a directive (verb or "the/that/this") */
+export const CORRECTION_WEAK_PATTERNS: RegExp[] = [
+  /^no[,\.\s!]/i,
+  /^wrong[,\.\s!]/i,
+  /^actually[,\.\s]/i,
+  /^stop[,\.\s!]/i,
+];
+
+/** Negative patterns — suppress trigger even if a positive pattern matches */
+export const CORRECTION_NEGATIVE_PATTERNS: RegExp[] = [
+  /^no worries/i,
+  /^no problem/i,
+  /^no thanks/i,
+  /^no need/i,
+  /^actually.{0,10}(looks? great|perfect|good|correct|right)/i,
+  /^stop.{0,5}(there|here|for now)/i,
+];
+
+// ─── Correction save prompt ───
+export const CORRECTION_SAVE_PROMPT = `The user just corrected you. Review what went wrong and save the correction to persistent memory.
+
+Priority:
+1. User preference ("don't do X", "always use Y instead")
+2. Wrong assumption you made
+3. Environment fact you got wrong
+
+Use the memory tool to save. If this contradicts an existing entry, use 'replace' to update it.`;
+
+// ─── Skill tool description ───
+export const SKILL_TOOL_DESCRIPTION = `Save reusable procedures and patterns as skills that survive across sessions. Skills are procedural memory — they capture HOW to do something, not just what happened.
+
+WHEN TO CREATE A SKILL:
+- After completing a complex task that required trial and error or multiple tool calls
+- When you discover a non-obvious approach that could be reused
+- When the user teaches you a specific workflow or procedure
+
+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
+
+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
+
+ACTIONS: create (new skill), view (read full content), patch (update a section), edit (replace description + body), delete (remove skill).`;

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

@@ -16,9 +16,11 @@ import { getMessageText } from "../types.js";
 export function setupBackgroundReview(
   pi: ExtensionAPI,
   store: MemoryStore,
+  projectStore: MemoryStore | null,
   config: MemoryConfig,
 ): void {
   let turnsSinceReview = 0;
+  let toolCallsSinceReview = 0;
   let userTurnCount = 0;
   let reviewInProgress = false;
 
@@ -33,10 +35,35 @@ export function setupBackgroundReview(
 
     if (!config.reviewEnabled) return;
     if (reviewInProgress) return;
-    if (turnsSinceReview < config.nudgeInterval) return;
+
+    // Count tool calls from this turn's message only (not cumulative branch scan —
+    // otherwise the counter resets to 0 at review, then immediately re-counts all
+    // historical tool calls and re-triggers on every subsequent turn).
+    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") {
+              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 {
@@ -56,6 +83,7 @@ export function setupBackgroundReview(
 
       const currentMemory = store.getMemoryEntries().join("\n§\n");
       const currentUser = store.getUserEntries().join("\n§\n");
+      const currentProject = projectStore ? projectStore.getMemoryEntries().join("\n§\n") : null;
 
       const reviewPrompt = [
         COMBINED_REVIEW_PROMPT,
@@ -65,12 +93,23 @@ export function setupBackgroundReview(
         "",
         "--- Current User Profile ---",
         currentUser || "(empty)",
+      ];
+
+      if (currentProject !== null) {
+        reviewPrompt.push(
+          "",
+          "--- Current Project Memory ---",
+          currentProject || "(empty)",
+        );
+      }
+
+      reviewPrompt.push(
         "",
         "--- Conversation to Review ---",
         parts.join("\n\n"),
-      ].join("\n");
+      );
 
-      const result = await pi.exec("pi", ["-p", "--no-session", reviewPrompt], {
+      const result = await pi.exec("pi", ["-p", "--no-session", reviewPrompt.join("\n")], {
         signal: ctx.signal,
         timeout: 60000,
       });

package/src/handlers/correction-detector.ts

@@ -0,0 +1,156 @@
+/**
+ * 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,
+  projectStore: MemoryStore | null,
+  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 currentProject = projectStore ? projectStore.getMemoryEntries().join(ENTRY_DELIMITER) : null;
+
+      const prompt = [
+        CORRECTION_SAVE_PROMPT,
+        "",
+        "--- Current Memory ---",
+        currentMemory || "(empty)",
+        "",
+        "--- Current User Profile ---",
+        currentUser || "(empty)",
+      ];
+
+      if (currentProject !== null) {
+        prompt.push(
+          "",
+          "--- Current Project Memory ---",
+          currentProject || "(empty)",
+        );
+      }
+
+      prompt.push(
+        "",
+        "--- Recent Conversation ---",
+        recentParts.join("\n\n"),
+      );
+
+      const result = await pi.exec("pi", ["-p", "--no-session", prompt.join("\n")], {
+        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/insights.ts

@@ -5,12 +5,13 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { MemoryStore } from "../store/memory-store.js";
 
-export function registerInsightsCommand(pi: ExtensionAPI, store: MemoryStore): void {
+export function registerInsightsCommand(pi: ExtensionAPI, store: MemoryStore, projectStore: MemoryStore | null, projectName: string): void {
   pi.registerCommand("memory-insights", {
     description: "Show what's stored in persistent memory",
     handler: async (_args, ctx) => {
       const memoryEntries = store.getMemoryEntries();
       const userEntries = store.getUserEntries();
+      const projectEntries = projectStore ? projectStore.getMemoryEntries() : null;
 
       const lines: string[] = [];
       lines.push("");
@@ -51,6 +52,24 @@ export function registerInsightsCommand(pi: ExtensionAPI, store: MemoryStore): v
       }
       lines.push("");
 
+      // Project section
+      if (projectEntries !== null) {
+        lines.push(`  📁 PROJECT MEMORY: ${projectName}`);
+        lines.push("  " + "─".repeat(44));
+        if (projectEntries.length === 0) {
+          lines.push("  (empty)");
+        } else {
+          for (let i = 0; i < projectEntries.length; i++) {
+            const preview =
+              projectEntries[i].length > 100
+                ? projectEntries[i].slice(0, 100) + "..."
+                : projectEntries[i];
+            lines.push(`  ${i + 1}. ${preview}`);
+          }
+        }
+        lines.push("");
+      }
+
       ctx.ui.notify(lines.join("\n"), "info");
     },
   });

package/src/handlers/session-flush.ts

@@ -13,6 +13,7 @@ import { getMessageText } from "../types.js";
 export function setupSessionFlush(
   pi: ExtensionAPI,
   store: MemoryStore,
+  projectStore: MemoryStore | null,
   config: MemoryConfig,
 ): void {
   let userTurnCount = 0;

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;
+
+  // 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((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");
+    },
+  });
+}