pi-hermes-memory 0.7.4 → 0.7.6

package/README.md

@@ -357,11 +357,13 @@ Create `~/.pi/agent/hermes-memory-config.json`:
   "nudgeToolCalls": 15,
   "reviewRecentMessages": 0,
   "reviewEnabled": true,
+  "memoryOverflowStrategy": "auto-consolidate",
   "autoConsolidate": true,
   "correctionDetection": true,
   "failureInjectionEnabled": true,
   "failureInjectionMaxAgeDays": 7,
   "failureInjectionMaxEntries": 5,
+  "consolidationTimeoutMs": 60000,
   "flushOnCompact": true,
   "flushOnShutdown": true,
   "flushMinTurns": 6,
@@ -383,7 +385,9 @@ 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`) |
+| `consolidationTimeoutMs` | `60000` | Maximum time in milliseconds for auto-consolidation to complete |
 | `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.6",
   "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,
@@ -12,10 +12,17 @@ import {
   DEFAULT_NUDGE_TOOL_CALLS,
   DEFAULT_REVIEW_RECENT_MESSAGES,
   DEFAULT_FLUSH_RECENT_MESSAGES,
+  DEFAULT_CONSOLIDATION_TIMEOUT_MS,
   DEFAULT_FAILURE_INJECTION_MAX_AGE_DAYS,
   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,11 +36,13 @@ 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,
   failureInjectionMaxAgeDays: DEFAULT_FAILURE_INJECTION_MAX_AGE_DAYS,
   failureInjectionMaxEntries: DEFAULT_FAILURE_INJECTION_MAX_ENTRIES,
+  consolidationTimeoutMs: DEFAULT_CONSOLIDATION_TIMEOUT_MS,
   nudgeToolCalls: DEFAULT_NUDGE_TOOL_CALLS,
   projectsMemoryDir: DEFAULT_PROJECTS_MEMORY_DIR,
 };
@@ -58,6 +67,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,12 +86,20 @@ 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;
       if (isStringArray(parsed.correctionNegativePatterns)) config.correctionNegativePatterns = parsed.correctionNegativePatterns;
       if (isStringArray(parsed.correctionDirectiveWords)) config.correctionDirectiveWords = parsed.correctionDirectiveWords;
+      if (typeof parsed.consolidationTimeoutMs === "number") config.consolidationTimeoutMs = parsed.consolidationTimeoutMs;
       if (typeof parsed.failureInjectionEnabled === "boolean") config.failureInjectionEnabled = parsed.failureInjectionEnabled;
       if (typeof parsed.failureInjectionMaxAgeDays === "number") config.failureInjectionMaxAgeDays = parsed.failureInjectionMaxAgeDays;
       if (typeof parsed.failureInjectionMaxEntries === "number") config.failureInjectionMaxEntries = parsed.failureInjectionMaxEntries;
@@ -88,6 +107,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/constants.ts

@@ -23,6 +23,7 @@ export const DEFAULT_NUDGE_TOOL_CALLS = 15;
 export const DEFAULT_REVIEW_RECENT_MESSAGES = 0;
 export const DEFAULT_FLUSH_RECENT_MESSAGES = 0;
 export const DEFAULT_SKILL_TRIGGER_TOOL_CALLS = 8;
+export const DEFAULT_CONSOLIDATION_TIMEOUT_MS = 60000;
 export const DEFAULT_FAILURE_INJECTION_MAX_AGE_DAYS = 7;
 export const DEFAULT_FAILURE_INJECTION_MAX_ENTRIES = 5;
 

package/src/handlers/auto-consolidate.ts

@@ -17,6 +17,7 @@ export async function triggerConsolidation(
   store: MemoryStore,
   target: "memory" | "user" | "failure",
   signal?: AbortSignal,
+  timeoutMs: number = 60000,
 ): Promise<ConsolidationResult> {
   const entries =
     target === "memory" ? store.getMemoryEntries() : store.getUserEntries();
@@ -34,7 +35,7 @@ export async function triggerConsolidation(
   try {
     const result = await pi.exec("pi", ["-p", "--no-session", prompt], {
       signal,
-      timeout: 60000,
+      timeout: timeoutMs,
     });
 
     if (result.code === 0) {
@@ -58,6 +59,7 @@ export async function triggerConsolidation(
 export function registerConsolidateCommand(
   pi: ExtensionAPI,
   store: MemoryStore,
+  timeoutMs: number = 60000,
 ): void {
   pi.registerCommand("memory-consolidate", {
     description: "Manually trigger memory consolidation to free up space",
@@ -75,7 +77,7 @@ export function registerConsolidateCommand(
           continue;
         }
 
-        const result = await triggerConsolidation(pi, store, target, ctx.signal);
+        const result = await triggerConsolidation(pi, store, target, ctx.signal, timeoutMs);
 
         if (result.consolidated) {
           await store.loadFromDisk();

package/src/index.ts

@@ -111,9 +111,9 @@ export default function (pi: ExtensionAPI) {
 
   // ── 7. Setup auto-consolidation (inject consolidator into store) ──
   store.setConsolidator(async (target, signal) => {
-    return triggerConsolidation(pi, store, target, signal);
+    return triggerConsolidation(pi, store, target, signal, config.consolidationTimeoutMs);
   });
-  registerConsolidateCommand(pi, store);
+  registerConsolidateCommand(pi, store, config.consolidationTimeoutMs);
 
   // ── 8. Setup correction detection ──
   setupCorrectionDetector(pi, store, projectStore, config, dbManager, projectName);

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/store/sqlite-memory-store.ts

@@ -67,6 +67,11 @@ export interface SqliteMemoryRemoveResult {
   removed: number;
 }
 
+export interface SqliteMemoryRemoveOptions {
+  target: 'memory' | 'user' | 'failure';
+  project?: string | null;
+}
+
 export interface ParsedMarkdownMemoryEntry extends SqliteMemorySyncInput {}
 
 function today(): string {
@@ -481,10 +486,7 @@ export function replaceSyncedMemories(
 export function removeSyncedMemories(
   dbManager: DatabaseManager,
   oldText: string,
-  options: {
-    target: 'memory' | 'user' | 'failure';
-    project?: string | null;
-  },
+  options: SqliteMemoryRemoveOptions,
 ): SqliteMemoryRemoveResult {
   const db = dbManager.getDb();
   const params: unknown[] = [];
@@ -512,6 +514,42 @@ export function removeSyncedMemories(
   };
 }
 
+/**
+ * Exact removal for Markdown entries whose full content is known.
+ * Used for FIFO eviction cleanup, where substring matching could remove
+ * unrelated SQLite mirror rows that merely contain the evicted text.
+ */
+export function removeExactSyncedMemories(
+  dbManager: DatabaseManager,
+  content: string,
+  options: SqliteMemoryRemoveOptions,
+): SqliteMemoryRemoveResult {
+  const db = dbManager.getDb();
+  const params: unknown[] = [];
+  const conditions = buildScopeConditions(params, options.target, options.project ?? undefined);
+  conditions.push('content = ?');
+  params.push(content.trim());
+
+  const matchingIds = db.prepare(`
+    SELECT id
+    FROM memories
+    WHERE ${conditions.join(' AND ')}
+  `).all(...params) as Array<{ id: number }>;
+
+  if (matchingIds.length === 0) {
+    return { matched: 0, removed: 0 };
+  }
+
+  const deleteParams = matchingIds.map((row) => row.id);
+  const placeholders = deleteParams.map(() => '?').join(', ');
+  const result = db.prepare(`DELETE FROM memories WHERE id IN (${placeholders})`).run(...deleteParams);
+
+  return {
+    matched: matchingIds.length,
+    removed: result.changes,
+  };
+}
+
 /**
  * Escape a string for FTS5 query syntax.
  * Wraps the query in double quotes to treat it as a literal phrase.

package/src/tools/memory-tool.ts

@@ -11,6 +11,7 @@ import { MemoryStore } from "../store/memory-store.js";
 import { DatabaseManager } from "../store/db.js";
 import {
   formatFailureMemoryContent,
+  removeExactSyncedMemories,
   removeSyncedMemories,
   replaceSyncedMemories,
   syncMemoryEntry,
@@ -29,6 +30,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;
@@ -136,6 +160,31 @@ async function syncRemoveFromSqlite(
   }
 }
 
+async function syncEvictionsFromSqlite(
+  rawTarget: "memory" | "user" | "project" | "failure",
+  evictedEntries: string[] | undefined,
+  dbManager: DatabaseManager | null,
+  projectName?: string | null,
+): Promise<void> {
+  if (!dbManager) return;
+  if (!evictedEntries || evictedEntries.length === 0) return;
+
+  const sqliteTarget = sqliteTargetFor(rawTarget);
+  const sqliteProject = sqliteProjectFor(rawTarget, projectName);
+
+  for (const entry of evictedEntries) {
+    try {
+      removeExactSyncedMemories(dbManager, entry, {
+        target: sqliteTarget,
+        project: sqliteProject,
+      });
+    } catch {
+      // FIFO already updated the Markdown source of truth. SQLite is only a
+      // best-effort search mirror, so eviction cleanup must not fail the write.
+    }
+  }
+}
+
 export function registerMemoryTool(
   pi: ExtensionAPI,
   store: MemoryStore,
@@ -224,6 +273,7 @@ export function registerMemoryTool(
           } else {
             result = await store_.add(target, content);
             if (result.success) {
+              await syncEvictionsFromSqlite(rawTarget, result.evicted_entries, dbManager, projectName);
               syncWarning = await syncAddToSqlite(rawTarget, content, undefined, undefined, dbManager, projectName);
             }
           }
@@ -305,7 +355,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;
@@ -55,6 +59,8 @@ export interface MemoryConfig {
   failureInjectionMaxEntries: number;
   /** Tool calls before triggering background review (in addition to turn count). Default: 15 */
   nudgeToolCalls: number;
+  /** Maximum time in milliseconds for auto-consolidation to complete. Default: 60000 */
+  consolidationTimeoutMs: number;
   /** Enable session history search via SQLite FTS5. Default: true */
   sessionSearchEnabled?: boolean;
   /** Days to retain session history. Default: 90 */
@@ -79,6 +85,8 @@ export interface MemoryResult {
   entries?: string[];
   usage?: string;
   entry_count?: number;
+  evicted_entries?: string[];
+  evicted_count?: number;
   matches?: string[];
 }