pi-hermes-memory 0.7.4 → 0.7.5

package/README.md

@@ -357,6 +357,7 @@ Create `~/.pi/agent/hermes-memory-config.json`:
   "nudgeToolCalls": 15,
   "reviewRecentMessages": 0,
   "reviewEnabled": true,
+  "memoryOverflowStrategy": "auto-consolidate",
   "autoConsolidate": true,
   "correctionDetection": true,
   "failureInjectionEnabled": true,
@@ -383,7 +384,8 @@ Create `~/.pi/agent/hermes-memory-config.json`:
 | `nudgeToolCalls` | `15` | Tool calls between auto-reviews (OR with turns) |
 | `reviewRecentMessages` | `0` | Recent messages included in background review (`0` = all) |
 | `reviewEnabled` | `true` | Enable/disable background learning loop |
-| `autoConsolidate` | `true` | Auto-merge when memory hits capacity |
+| `memoryOverflowStrategy` | `auto-consolidate` | Behavior when MEMORY.md, USER.md, or project-scoped memory reaches its character limit: `auto-consolidate` runs the existing consolidation flow; `reject` returns an error; `fifo-evict` rotates older entries in file order until the new entry fits |
+| `autoConsolidate` | `true` | Legacy alias for `memoryOverflowStrategy` when `memoryOverflowStrategy` is not set (`true` = `auto-consolidate`, `false` = `reject`) |
 | `correctionDetection` | `true` | Detect user corrections and save immediately |
 | `correctionStrongPatterns` | unset | Optional case-insensitive regex sources replacing strong correction patterns; omitted preserves defaults, invalid entries are ignored |
 | `correctionWeakPatterns` | unset | Optional case-insensitive regex sources replacing weak correction patterns; omitted preserves defaults, invalid entries are ignored |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hermes-memory",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "description": "🧠 Persistent memory + 🔍 session search + 🛡️ secret scanning for Pi. Token-aware policy-only memory by default, SQLite FTS5 search, auto-consolidation, procedural skills. 368 tests. Ported from Hermes agent.",
   "type": "module",
   "main": "src/index.ts",

package/src/config.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
-import type { MemoryConfig } from "./types.js";
+import type { MemoryConfig, MemoryOverflowStrategy } from "./types.js";
 import {
   DEFAULT_MEMORY_CHAR_LIMIT,
   DEFAULT_USER_CHAR_LIMIT,
@@ -16,6 +16,12 @@ import {
   DEFAULT_FAILURE_INJECTION_MAX_ENTRIES,
 } from "./constants.js";
 
+const MEMORY_OVERFLOW_STRATEGIES: readonly MemoryOverflowStrategy[] = ["auto-consolidate", "reject", "fifo-evict"];
+
+function isMemoryOverflowStrategy(value: unknown): value is MemoryOverflowStrategy {
+  return typeof value === "string" && MEMORY_OVERFLOW_STRATEGIES.includes(value as MemoryOverflowStrategy);
+}
+
 const DEFAULT_CONFIG: MemoryConfig = {
   memoryMode: "policy-only",
   memoryPolicyStyle: "full",
@@ -29,6 +35,7 @@ const DEFAULT_CONFIG: MemoryConfig = {
   flushOnShutdown: true,
   flushMinTurns: DEFAULT_FLUSH_MIN_TURNS,
   flushRecentMessages: DEFAULT_FLUSH_RECENT_MESSAGES,
+  memoryOverflowStrategy: "auto-consolidate",
   autoConsolidate: true,
   correctionDetection: true,
   failureInjectionEnabled: true,
@@ -58,6 +65,8 @@ export function loadConfig(configPath = DEFAULT_CONFIG_PATH): MemoryConfig {
       const isStringArray = (value: unknown): value is string[] => (
         Array.isArray(value) && value.every((item) => typeof item === "string")
       );
+      let hasLegacyAutoConsolidate = false;
+      let hasMemoryOverflowStrategy = false;
       if (parsed.memoryMode === "policy-only" || parsed.memoryMode === "legacy-inject") config.memoryMode = parsed.memoryMode;
       if (
         parsed.memoryPolicyStyle === "full" ||
@@ -75,7 +84,14 @@ export function loadConfig(configPath = DEFAULT_CONFIG_PATH): MemoryConfig {
       if (typeof parsed.flushOnShutdown === "boolean") config.flushOnShutdown = parsed.flushOnShutdown;
       if (typeof parsed.flushMinTurns === "number") config.flushMinTurns = parsed.flushMinTurns;
       if (isNonNegativeNumber(parsed.flushRecentMessages)) config.flushRecentMessages = parsed.flushRecentMessages;
-      if (typeof parsed.autoConsolidate === "boolean") config.autoConsolidate = parsed.autoConsolidate;
+      if (typeof parsed.autoConsolidate === "boolean") {
+        config.autoConsolidate = parsed.autoConsolidate;
+        hasLegacyAutoConsolidate = true;
+      }
+      if (isMemoryOverflowStrategy(parsed.memoryOverflowStrategy)) {
+        config.memoryOverflowStrategy = parsed.memoryOverflowStrategy;
+        hasMemoryOverflowStrategy = true;
+      }
       if (typeof parsed.correctionDetection === "boolean") config.correctionDetection = parsed.correctionDetection;
       if (isStringArray(parsed.correctionStrongPatterns)) config.correctionStrongPatterns = parsed.correctionStrongPatterns;
       if (isStringArray(parsed.correctionWeakPatterns)) config.correctionWeakPatterns = parsed.correctionWeakPatterns;
@@ -88,6 +104,11 @@ export function loadConfig(configPath = DEFAULT_CONFIG_PATH): MemoryConfig {
       if (typeof parsed.projectCharLimit === "number") config.projectCharLimit = parsed.projectCharLimit;
       if (typeof parsed.memoryDir === "string") config.memoryDir = parsed.memoryDir;
       if (typeof parsed.projectsMemoryDir === "string") config.projectsMemoryDir = parsed.projectsMemoryDir;
+      if (hasMemoryOverflowStrategy) {
+        config.autoConsolidate = config.memoryOverflowStrategy === "auto-consolidate";
+      } else if (hasLegacyAutoConsolidate) {
+        config.memoryOverflowStrategy = config.autoConsolidate ? "auto-consolidate" : "reject";
+      }
       return config;
     }
   } catch {

package/src/store/memory-store.ts

@@ -24,7 +24,7 @@ import {
   MEMORY_FILE,
   USER_FILE,
 } from "../constants.js";
-import type { MemoryConfig, MemoryResult, MemorySnapshot, ConsolidationResult, MemoryCategory } from "../types.js";
+import type { MemoryConfig, MemoryResult, MemorySnapshot, ConsolidationResult, MemoryCategory, MemoryOverflowStrategy } from "../types.js";
 
 export class MemoryStore {
   private memoryEntries: string[] = [];
@@ -77,6 +77,10 @@ export class MemoryStore {
     return entries.length ? entries.join(ENTRY_DELIMITER).length : 0;
   }
 
+  private memoryOverflowStrategy(): MemoryOverflowStrategy {
+    return this.config.memoryOverflowStrategy ?? (this.config.autoConsolidate ? "auto-consolidate" : "reject");
+  }
+
   // ─── Load from disk ───
 
   async loadFromDisk(): Promise<void> {
@@ -176,8 +180,14 @@ export class MemoryStore {
 
     const newTotal = [...entries, encoded].join(ENTRY_DELIMITER).length;
     if (newTotal > limit) {
+      const strategy = this.memoryOverflowStrategy();
+
+      if (strategy === "fifo-evict") {
+        return this.fifoEvictAndAdd(target, entries, encoded, content.length, limit);
+      }
+
       // Auto-consolidate once if configured — limit retries to prevent infinite loops
-      if (this.config.autoConsolidate && this.consolidator && _retriesLeft > 0) {
+      if (strategy === "auto-consolidate" && this.consolidator && _retriesLeft > 0) {
         try {
           const result = await this.consolidator(target, signal);
           if (result.consolidated) {
@@ -190,11 +200,7 @@ export class MemoryStore {
           // Consolidation failed — fall through to error
         }
       }
-      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.`,
-      };
+      return this.memoryFullError(target, content.length);
     }
 
     entries.push(encoded);
@@ -204,6 +210,48 @@ export class MemoryStore {
     return this.successResponse(target, "Entry added.");
   }
 
+  private async fifoEvictAndAdd(
+    target: "memory" | "user" | "failure",
+    entries: string[],
+    encoded: string,
+    contentLength: number,
+    limit: number,
+  ): Promise<MemoryResult> {
+    if (encoded.length > limit) {
+      return this.memoryFullError(target, contentLength);
+    }
+
+    const remaining = [...entries];
+    const evictedEntries: string[] = [];
+
+    while ([...remaining, encoded].join(ENTRY_DELIMITER).length > limit && remaining.length > 0) {
+      const evicted = remaining.shift()!;
+      evictedEntries.push(this.stripMetadata(evicted));
+    }
+
+    remaining.push(encoded);
+    this.setEntries(target, remaining);
+    await this.saveToDisk(target);
+
+    return {
+      ...this.successResponse(
+        target,
+        `Memory updated. Rotated ${evictedEntries.length} older ${evictedEntries.length === 1 ? "entry" : "entries"} to stay within the limit.`,
+      ),
+      evicted_entries: evictedEntries,
+      evicted_count: evictedEntries.length,
+    };
+  }
+
+  private memoryFullError(target: "memory" | "user" | "failure", contentLength: number): MemoryResult {
+    const current = this.charCount(target);
+    const limit = this.charLimit(target);
+    return {
+      success: false,
+      error: `Memory at ${current}/${limit} chars. Adding this entry (${contentLength} chars) would exceed the limit. Replace or remove existing entries first.`,
+    };
+  }
+
   async replace(target: "memory" | "user" | "failure", oldText: string, newContent: string): Promise<MemoryResult> {
     oldText = oldText.trim();
     newContent = newContent.trim();

package/src/tools/memory-tool.ts

@@ -29,6 +29,29 @@ function appendSyncWarning(result: MemoryResult, warning: string): MemoryResult
   } as MemoryResult;
 }
 
+function formatMemoryToolText(result: MemoryResult): string {
+  const evictedEntries = result.evicted_entries ?? [];
+  if (result.success && evictedEntries.length > 0) {
+    const lines = [
+      result.message ?? `Memory updated. Rotated ${evictedEntries.length} older ${evictedEntries.length === 1 ? "entry" : "entries"} to stay within the limit.`,
+      "",
+      "Rotated active memory entries:",
+      "",
+    ];
+
+    evictedEntries.forEach((entry, index) => {
+      lines.push(`${index + 1}. ${entry}`);
+      lines.push("");
+    });
+
+    lines.push("If one of these entries should stay active, add it again.");
+    if (result.usage) lines.push(`Usage: ${result.usage}`);
+    return lines.join("\n").trim();
+  }
+
+  return JSON.stringify(result);
+}
+
 function sqliteProjectFor(rawTarget: "memory" | "user" | "project" | "failure", projectName?: string | null): string | null | undefined {
   if (rawTarget === "project") return projectName?.trim() || null;
   if (rawTarget === "memory") return null;
@@ -305,7 +328,7 @@ export function registerMemoryTool(
       }
 
       return {
-        content: [{ type: "text", text: JSON.stringify(result) }],
+        content: [{ type: "text", text: formatMemoryToolText(result) }],
         details: result,
       };
     },

package/src/types.ts

@@ -4,6 +4,8 @@
 
 import type { TextContent } from "@mariozechner/pi-ai";
 
+export type MemoryOverflowStrategy = "auto-consolidate" | "reject" | "fifo-evict";
+
 export interface MemoryConfig {
   /** Prompt memory mode. Default: policy-only */
   memoryMode: "policy-only" | "legacy-inject";
@@ -35,7 +37,9 @@ export interface MemoryConfig {
   memoryDir?: string;
   /** Directory for project-scoped memory (relative to ~/.pi/agent). Default: "projects-memory" */
   projectsMemoryDir?: string;
-  /** Auto-consolidate when memory is full instead of returning error. Default: true */
+  /** Strategy when memory is full. Default: auto-consolidate */
+  memoryOverflowStrategy?: MemoryOverflowStrategy;
+  /** Legacy alias for memoryOverflowStrategy. Default: true */
   autoConsolidate: boolean;
   /** Detect user corrections and trigger immediate memory save. Default: true */
   correctionDetection: boolean;
@@ -79,6 +83,8 @@ export interface MemoryResult {
   entries?: string[];
   usage?: string;
   entry_count?: number;
+  evicted_entries?: string[];
+  evicted_count?: number;
   matches?: string[];
 }