pi-hermes-memory 0.1.0

package/src/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Pi Hermes Memory Extension
+ *
+ * Brings Hermes-style persistent memory and a learning loop to any Pi user.
+ * After `pi install`, users get:
+ *
+ * 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
+ *
+ * See PLAN.md for full architecture and Hermes source references.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { MemoryStore } from "./store/memory-store.js";
+import { registerMemoryTool } from "./tools/memory-tool.js";
+import { setupBackgroundReview } from "./handlers/background-review.js";
+import { setupSessionFlush } from "./handlers/session-flush.js";
+import { registerInsightsCommand } from "./handlers/insights.js";
+import { loadConfig } from "./config.js";
+
+export default function (pi: ExtensionAPI) {
+  const config = loadConfig();
+
+  const store = new MemoryStore(config);
+
+  // ── 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 ──
+  pi.on("before_agent_start", async (event, _ctx) => {
+    const memoryBlock = store.formatForSystemPrompt();
+    if (memoryBlock) {
+      return {
+        systemPrompt: event.systemPrompt + "\n\n" + memoryBlock,
+      };
+    }
+  });
+
+  // ── 3. Register the memory tool ──
+  registerMemoryTool(pi, store);
+
+  // ── 4. Setup background learning loop ──
+  setupBackgroundReview(pi, store, config);
+
+  // ── 5. Setup session-end flush ──
+  setupSessionFlush(pi, store, config);
+
+  // ── 6. Register insights command ──
+  registerInsightsCommand(pi, store);
+}

package/src/store/content-scanner.ts

@@ -0,0 +1,46 @@
+/**
+ * Content scanner — blocks injection/exfiltration in memory writes.
+ * Ported from hermes-agent/tools/memory_tool.py (_MEMORY_THREAT_PATTERNS, _INVISIBLE_CHARS, _scan_memory_content).
+ * See PLAN.md → "Hermes Source File Reference Map" for source lines.
+ */
+
+const MEMORY_THREAT_PATTERNS: Array<{ pattern: RegExp; id: string }> = [
+  { pattern: /ignore\s+(previous|all|above|prior)\s+instructions/i, id: "prompt_injection" },
+  { pattern: /you\s+are\s+now\s+/i, id: "role_hijack" },
+  { pattern: /do\s+not\s+tell\s+the\s+user/i, id: "deception_hide" },
+  { pattern: /system\s+prompt\s+override/i, id: "sys_prompt_override" },
+  { pattern: /disregard\s+(your|all|any)\s+(instructions|rules|guidelines)/i, id: "disregard_rules" },
+  { pattern: /act\s+as\s+(if|though)\s+you\s+(have\s+no|don'?t\s+have)\s+(restrictions|limits|rules)/i, id: "bypass_restrictions" },
+  { pattern: /curl\s+[^\n]*\$\{?\w*(KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|API)/i, id: "exfil_curl" },
+  { pattern: /wget\s+[^\n]*\$\{?\w*(KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|API)/i, id: "exfil_wget" },
+  { pattern: /cat\s+[^\n]*(\.env|credentials|\.netrc|\.pgpass|\.npmrc|\.pypirc)/i, id: "read_secrets" },
+  { pattern: /authorized_keys/i, id: "ssh_backdoor" },
+  { pattern: /\$HOME\/\.ssh|~\/\.ssh/i, id: "ssh_access" },
+];
+
+const INVISIBLE_CHARS = new Set([
+  '\u200b', '\u200c', '\u200d', '\u2060', '\ufeff',
+  '\u202a', '\u202b', '\u202c', '\u202d', '\u202e',
+]);
+
+/**
+ * Scan memory content for injection/exfiltration patterns.
+ * Returns an error string if blocked, or null if content is safe.
+ */
+export function scanContent(content: string): string | null {
+  // Check invisible unicode
+  for (const char of content) {
+    if (INVISIBLE_CHARS.has(char)) {
+      return `Blocked: content contains invisible unicode character U+${char.charCodeAt(0).toString(16).toUpperCase().padStart(4, '0')} (possible injection).`;
+    }
+  }
+
+  // Check threat patterns
+  for (const { pattern, id } of MEMORY_THREAT_PATTERNS) {
+    if (pattern.test(content)) {
+      return `Blocked: content matches threat pattern '${id}'. Memory entries are injected into the system prompt and must not contain injection or exfiltration payloads.`;
+    }
+  }
+
+  return null;
+}

package/src/store/memory-store.ts

@@ -0,0 +1,257 @@
+/**
+ * MemoryStore — core persistent memory with file-backed storage.
+ * Ported from hermes-agent/tools/memory_tool.py (MemoryStore class).
+ * See PLAN.md → "Hermes Source File Reference Map" for source lines.
+ *
+ * Design:
+ * - Two stores: MEMORY.md (agent notes) and USER.md (user profile)
+ * - §-delimited entries with character limits
+ * - Frozen snapshot at load time for system prompt (preserves Pi's prompt cache)
+ * - Atomic writes via temp file + fs.rename()
+ * - Content scanning before any write
+ */
+
+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 {
+  ENTRY_DELIMITER,
+  DEFAULT_MEMORY_CHAR_LIMIT,
+  DEFAULT_USER_CHAR_LIMIT,
+  MEMORY_FILE,
+  USER_FILE,
+} from "../constants.js";
+import type { MemoryConfig, MemoryResult, MemorySnapshot } from "../types.js";
+
+export class MemoryStore {
+  private memoryEntries: string[] = [];
+  private userEntries: string[] = [];
+  private snapshot: MemorySnapshot = { memory: "", user: "" };
+
+  constructor(private config: MemoryConfig) {}
+
+  // ─── Path helpers ───
+
+  private get memoryDir(): string {
+    return this.config.memoryDir ?? path.join(os.homedir(), ".pi", "agent", "memory");
+  }
+
+  private pathFor(target: "memory" | "user"): string {
+    return path.join(this.memoryDir, target === "user" ? USER_FILE : MEMORY_FILE);
+  }
+
+  private entriesFor(target: "memory" | "user"): string[] {
+    return target === "user" ? this.userEntries : this.memoryEntries;
+  }
+
+  private setEntries(target: "memory" | "user", entries: string[]): void {
+    if (target === "user") this.userEntries = entries;
+    else this.memoryEntries = entries;
+  }
+
+  private charLimit(target: "memory" | "user"): number {
+    return target === "user" ? this.config.userCharLimit : this.config.memoryCharLimit;
+  }
+
+  private charCount(target: "memory" | "user"): number {
+    const entries = this.entriesFor(target);
+    return entries.length ? entries.join(ENTRY_DELIMITER).length : 0;
+  }
+
+  // ─── Load from disk ───
+
+  async loadFromDisk(): Promise<void> {
+    await fs.mkdir(this.memoryDir, { recursive: true });
+    this.memoryEntries = await this.readFile(this.pathFor("memory"));
+    this.userEntries = await this.readFile(this.pathFor("user"));
+
+    // Deduplicate preserving order
+    this.memoryEntries = [...new Set(this.memoryEntries)];
+    this.userEntries = [...new Set(this.userEntries)];
+
+    // Capture frozen snapshot for system prompt injection
+    this.snapshot = {
+      memory: this.renderBlock("memory", this.memoryEntries),
+      user: this.renderBlock("user", this.userEntries),
+    };
+  }
+
+  // ─── CRUD ───
+
+  add(target: "memory" | "user", content: string): MemoryResult {
+    content = content.trim();
+    if (!content) return { success: false, error: "Content cannot be empty." };
+
+    const scanError = scanContent(content);
+    if (scanError) return { success: false, error: scanError };
+
+    const entries = this.entriesFor(target);
+    const limit = this.charLimit(target);
+
+    if (entries.includes(content)) {
+      return this.successResponse(target, "Entry already exists (no duplicate added).");
+    }
+
+    const newTotal = [...entries, content].join(ENTRY_DELIMITER).length;
+    if (newTotal > limit) {
+      const current = this.charCount(target);
+      return {
+        success: false,
+        error: `Memory at ${current}/${limit} chars. Adding this entry (${content.length} chars) would exceed the limit. Replace or remove existing entries first.`,
+      };
+    }
+
+    entries.push(content);
+    this.setEntries(target, entries);
+    this.saveToDisk(target);
+
+    return this.successResponse(target, "Entry added.");
+  }
+
+  replace(target: "memory" | "user", oldText: string, newContent: string): MemoryResult {
+    oldText = oldText.trim();
+    newContent = newContent.trim();
+    if (!oldText) return { success: false, error: "old_text cannot be empty." };
+    if (!newContent) return { success: false, error: "new_content cannot be empty. Use 'remove' to delete entries." };
+
+    const scanError = scanContent(newContent);
+    if (scanError) return { success: false, error: scanError };
+
+    const entries = this.entriesFor(target);
+    const matches = entries.filter((e) => e.includes(oldText));
+
+    if (matches.length === 0) return { success: false, error: `No entry matched '${oldText}'.` };
+    if (matches.length > 1 && new Set(matches).size > 1) {
+      return {
+        success: false,
+        error: `Multiple entries matched '${oldText}'. Be more specific.`,
+        matches: matches.map((e) => e.slice(0, 80) + (e.length > 80 ? "..." : "")),
+      };
+    }
+
+    const idx = entries.indexOf(matches[0]);
+    const testEntries = [...entries];
+    testEntries[idx] = newContent;
+    const newTotal = testEntries.join(ENTRY_DELIMITER).length;
+
+    if (newTotal > this.charLimit(target)) {
+      return {
+        success: false,
+        error: `Replacement would put memory at ${newTotal}/${this.charLimit(target)} chars. Shorten or remove other entries first.`,
+      };
+    }
+
+    entries[idx] = newContent;
+    this.setEntries(target, entries);
+    this.saveToDisk(target);
+
+    return this.successResponse(target, "Entry replaced.");
+  }
+
+  remove(target: "memory" | "user", oldText: string): MemoryResult {
+    oldText = oldText.trim();
+    if (!oldText) return { success: false, error: "old_text cannot be empty." };
+
+    const entries = this.entriesFor(target);
+    const matches = entries.filter((e) => e.includes(oldText));
+
+    if (matches.length === 0) return { success: false, error: `No entry matched '${oldText}'.` };
+    if (matches.length > 1 && new Set(matches).size > 1) {
+      return {
+        success: false,
+        error: `Multiple entries matched '${oldText}'. Be more specific.`,
+        matches: matches.map((e) => e.slice(0, 80) + (e.length > 80 ? "..." : "")),
+      };
+    }
+
+    const idx = entries.indexOf(matches[0]);
+    entries.splice(idx, 1);
+    this.setEntries(target, entries);
+    this.saveToDisk(target);
+
+    return this.successResponse(target, "Entry removed.");
+  }
+
+  // ─── System prompt injection (frozen snapshot) ───
+
+  formatForSystemPrompt(): string {
+    const parts: string[] = [];
+    if (this.snapshot.memory) parts.push(this.snapshot.memory);
+    if (this.snapshot.user) parts.push(this.snapshot.user);
+    return parts.join("\n\n");
+  }
+
+  getMemoryEntries(): string[] {
+    return [...this.memoryEntries];
+  }
+
+  getUserEntries(): string[] {
+    return [...this.userEntries];
+  }
+
+  // ─── Internal helpers ───
+
+  private successResponse(target: "memory" | "user", message?: string): MemoryResult {
+    const entries = this.entriesFor(target);
+    const current = this.charCount(target);
+    const limit = this.charLimit(target);
+    const pct = limit > 0 ? Math.min(100, Math.floor((current / limit) * 100)) : 0;
+
+    const resp: MemoryResult = {
+      success: true,
+      target,
+      entries,
+      usage: `${pct}% — ${current}/${limit} chars`,
+      entry_count: entries.length,
+    };
+    if (message) resp.message = message;
+    return resp;
+  }
+
+  private renderBlock(target: "memory" | "user", entries: string[]): string {
+    if (!entries.length) return "";
+    const limit = this.charLimit(target);
+    const content = entries.join(ENTRY_DELIMITER);
+    const current = content.length;
+    const pct = limit > 0 ? Math.min(100, Math.floor((current / limit) * 100)) : 0;
+
+    const header = target === "user"
+      ? `USER PROFILE (who the user is) [${pct}% — ${current}/${limit} chars]`
+      : `MEMORY (your personal notes) [${pct}% — ${current}/${limit} chars]`;
+
+    const separator = "═".repeat(46);
+    return `${separator}\n${header}\n${separator}\n${content}`;
+  }
+
+  private async readFile(filePath: string): Promise<string[]> {
+    try {
+      const raw = await fs.readFile(filePath, "utf-8");
+      if (!raw.trim()) return [];
+      return raw.split(ENTRY_DELIMITER).map((e) => e.trim()).filter(Boolean);
+    } catch {
+      return [];
+    }
+  }
+
+  /** Atomic write: temp file + fs.rename() — same crash-safety as Hermes. */
+  private saveToDisk(target: "memory" | "user"): void {
+    const filePath = this.pathFor(target);
+    const entries = this.entriesFor(target);
+    const content = entries.length ? entries.join(ENTRY_DELIMITER) : "";
+
+    // Fire-and-forget atomic write
+    fs.mkdtemp(path.join(os.tmpdir(), "pi-memory-")).then((tmpDir) => {
+      const tmpPath = path.join(tmpDir, "write.tmp");
+      return fs
+        .writeFile(tmpPath, content, "utf-8")
+        .then(() => fs.rename(tmpPath, filePath))
+        .catch(async () => {
+          try { await fs.unlink(tmpPath); } catch { /* ignore */ }
+        })
+        .finally(async () => {
+          try { await fs.rmdir(tmpDir); } catch { /* ignore */ }
+        });
+    });
+  }
+}

package/src/tools/memory-tool.ts

@@ -0,0 +1,124 @@
+/**
+ * Memory tool — registers the LLM-callable `memory` tool.
+ * Ported from hermes-agent/tools/memory_tool.py (MEMORY_SCHEMA + memory_tool dispatch).
+ * See PLAN.md → "Hermes Source File Reference Map" for source lines.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "typebox";
+import { StringEnum } from "@mariozechner/pi-ai";
+import { MemoryStore } from "../store/memory-store.js";
+import { MEMORY_TOOL_DESCRIPTION } from "../constants.js";
+
+export function registerMemoryTool(pi: ExtensionAPI, store: MemoryStore): void {
+  pi.registerTool({
+    name: "memory",
+    label: "Memory",
+    description: MEMORY_TOOL_DESCRIPTION,
+    promptSnippet:
+      "Save or manage persistent memory that survives across sessions",
+    promptGuidelines: [
+      "Use the memory tool proactively when the user corrects you, shares a preference, or reveals personal details worth remembering.",
+      "Use the memory tool when you discover environment facts, project conventions, or reusable patterns useful in future sessions.",
+      "Do NOT use memory for temporary task state, TODO items, or session progress — only for durable, cross-session facts.",
+    ],
+    parameters: Type.Object({
+      action: StringEnum(["add", "replace", "remove"] as const),
+      target: StringEnum(["memory", "user"] as const),
+      content: Type.Optional(
+        Type.String({ description: "Entry content for add/replace" })
+      ),
+      old_text: Type.Optional(
+        Type.String({
+          description:
+            "Substring identifying entry for replace/remove",
+        })
+      ),
+    }),
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const { action, target, content, old_text } = params;
+
+      let result;
+      switch (action) {
+        case "add":
+          if (!content) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify({
+                    success: false,
+                    error: "Content is required for 'add' action.",
+                  }),
+                },
+              ],
+              details: {},
+            };
+          }
+          result = store.add(target, content);
+          break;
+
+        case "replace":
+          if (!old_text) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify({
+                    success: false,
+                    error: "old_text is required for 'replace' action.",
+                  }),
+                },
+              ],
+              details: {},
+            };
+          }
+          if (!content) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify({
+                    success: false,
+                    error: "content is required for 'replace' action.",
+                  }),
+                },
+              ],
+              details: {},
+            };
+          }
+          result = store.replace(target, old_text, content);
+          break;
+
+        case "remove":
+          if (!old_text) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify({
+                    success: false,
+                    error: "old_text is required for 'remove' action.",
+                  }),
+                },
+              ],
+              details: {},
+            };
+          }
+          result = store.remove(target, old_text);
+          break;
+
+        default:
+          result = {
+            success: false,
+            error: `Unknown action '${action}'. Use: add, replace, remove`,
+          };
+      }
+
+      return {
+        content: [{ type: "text", text: JSON.stringify(result) }],
+        details: result,
+      };
+    },
+  });
+}

package/src/types.ts

@@ -0,0 +1,66 @@
+/**
+ * Shared TypeScript types for the Hermes Memory extension.
+ */
+
+import type { TextContent } from "@mariozechner/pi-ai";
+
+export interface MemoryConfig {
+  /** Max chars for MEMORY.md (agent notes). Default: 2200 */
+  memoryCharLimit: number;
+  /** Max chars for USER.md (user profile). Default: 1375 */
+  userCharLimit: number;
+  /** Turns between background auto-reviews. Default: 10 */
+  nudgeInterval: number;
+  /** Enable background learning loop. Default: true */
+  reviewEnabled: boolean;
+  /** Flush memories before compaction. Default: true */
+  flushOnCompact: boolean;
+  /** Flush memories on session shutdown. Default: true */
+  flushOnShutdown: boolean;
+  /** Minimum user turns before flush triggers. Default: 6 */
+  flushMinTurns: number;
+  /** Override memory directory. Default: ~/.pi/agent/memory */
+  memoryDir?: string;
+}
+
+export interface MemoryResult {
+  success: boolean;
+  error?: string;
+  message?: string;
+  target?: "memory" | "user";
+  entries?: string[];
+  usage?: string;
+  entry_count?: number;
+  matches?: string[];
+}
+
+export interface MemorySnapshot {
+  memory: string;
+  user: string;
+}
+
+/**
+ * Extract displayable text from a Pi session entry message.
+ *
+ * Accepts any value — returns null for non-message entries (BashExecutionMessage,
+ * NotificationMessage, etc.) that lack a `content` property.
+ *
+ * Returns the concatenated text, truncated to `maxLength` chars.
+ */
+export function getMessageText(msg: unknown, maxLength = 500): string | null {
+  if (typeof msg !== "object" || msg === null) return null;
+  const { role, content } = msg as Record<string, unknown>;
+  if (typeof role !== "string") return null;
+
+  if (typeof content === "string") {
+    return content.slice(0, maxLength);
+  }
+  if (Array.isArray(content)) {
+    const text = (content as TextContent[])
+      .filter((block): block is TextContent => block.type === "text" && typeof block.text === "string")
+      .map((block) => block.text)
+      .join("\n");
+    return text.length > 0 ? text.slice(0, maxLength) : null;
+  }
+  return null;
+}