recallnest 1.4.1 → 2.2.0

package/src/auto-gc.ts

@@ -5,10 +5,20 @@
  * AND enough time has passed since last GC. Inspired by NREM triple-coupling:
  * multiple conditions must be satisfied before consolidation fires.
  *
- * Wraps existing cleanup scripts into a programmatic API.
+ * B-2 upgrade: Uses evolution system's computeDecayScore + buildArchivedMetadata
+ * instead of raw age/importance heuristics. Archive-first, delete-never.
  */
 
 import type { MemoryStore } from "./store.js";
+import {
+  parseEvolution,
+  computeDecayScore,
+  buildArchivedMetadata,
+  isActiveMemory,
+} from "./memory-evolution.js";
+import { loadRetentionPolicy, shouldArchiveByPolicy } from "./retention-policy.js";
+import type { RetentionPolicy } from "./retention-policy.js";
+import type { AuditLogger } from "./audit-log.js";
 
 // ---------------------------------------------------------------------------
 // Config
@@ -19,17 +29,20 @@ export interface AutoGcConfig {
   minMemoryCount: number;
   /** Minimum hours since last GC (default: 24) */
   minHoursSinceLastGc: number;
-  /** Score below which memories are candidates for archival (default: 0.2) */
-  staleScoreThreshold: number;
+  /** Decay score below which memories are archive candidates (default: 0.15) */
+  decayScoreThreshold: number;
   /** Max entries to archive per run (default: 100) */
   maxArchivePerRun: number;
+  /** Minimum age in days before a memory can be archived (default: 30) */
+  minAgeDays: number;
 }
 
 export const DEFAULT_AUTO_GC_CONFIG: AutoGcConfig = {
   minMemoryCount: 1000,
   minHoursSinceLastGc: 24,
-  staleScoreThreshold: 0.2,
+  decayScoreThreshold: 0.15,
   maxArchivePerRun: 100,
+  minAgeDays: 30,
 };
 
 // ---------------------------------------------------------------------------
@@ -52,10 +65,18 @@ export interface GcResult {
 /**
  * Check conditions and run GC if all thresholds are met.
  * Returns immediately if conditions not met (no-op).
+ *
+ * Archive criteria (B-2 evolution-aware):
+ * - Memory must be "active" (not already superseded/archived/consolidated)
+ * - Composite decay_score < threshold (default 0.15)
+ * - Age > minAgeDays (default 30 days)
+ * - Not pinned (importance >= 0.95 is considered pinned)
  */
 export async function maybeRunGc(
   store: MemoryStore,
   config: AutoGcConfig = DEFAULT_AUTO_GC_CONFIG,
+  retentionConfigDir?: string,
+  auditLogger?: AuditLogger,
 ): Promise<GcResult> {
   const stats = await store.stats();
   const totalMemories = stats.total ?? 0;
@@ -74,8 +95,7 @@ export async function maybeRunGc(
   // All conditions met — run GC
   lastGcTimestamp = Date.now();
 
-  // Find stale peripheral memories with low importance and no recent access
-  const cutoffMs = Date.now() - 60 * 86_400_000; // 60 days ago
+  const now = Date.now();
   let archivedCount = 0;
   let totalChecked = 0;
 
@@ -83,33 +103,82 @@ export async function maybeRunGc(
   const entries = await store.list({ limit: 5000 });
   totalChecked = entries.length;
 
+  // Pre-compute per-scope active memory counts and cache retention policies.
+  // This avoids repeated file reads inside the loop.
+  const activeCounts = new Map<string, number>();
+  const policyCache = new Map<string, RetentionPolicy>();
+  const scopesSeen = new Set<string>();
+
+  for (const entry of entries) {
+    const scope = entry.scope ?? "";
+    scopesSeen.add(scope);
+    if (isActiveMemory(entry.metadata)) {
+      activeCounts.set(scope, (activeCounts.get(scope) ?? 0) + 1);
+    }
+  }
+
+  // Batch-load retention policies for all scopes (one file read per scope)
+  for (const scope of scopesSeen) {
+    policyCache.set(scope, loadRetentionPolicy(scope, retentionConfigDir));
+  }
+
   for (const entry of entries) {
     if (archivedCount >= config.maxArchivePerRun) break;
 
-    let meta: Record<string, any> = {};
-    try { meta = JSON.parse(entry.metadata || "{}"); } catch { /* skip */ }
-
-    const isArchived = meta.archived === true;
-    if (isArchived) continue;
-
-    const tier = meta.tier || "peripheral";
-    const accessCount = meta.accessCount || 0;
-    const importance = entry.importance ?? 0;
-    const age = Date.now() - entry.timestamp;
-    const ageDays = age / 86_400_000;
-
-    // Archive criteria: peripheral + old + low importance + rarely accessed
-    if (
-      tier === "peripheral" &&
-      ageDays > 60 &&
-      importance < config.staleScoreThreshold &&
-      accessCount < 2
-    ) {
-      meta.archived = true;
-      meta.archivedAt = new Date().toISOString();
-      meta.archivedReason = "auto-gc:stale-peripheral";
-      await store.update(entry.id, { metadata: JSON.stringify(meta) });
+    // Only archive active memories
+    if (!isActiveMemory(entry.metadata)) continue;
+
+    // Never archive pinned memories (importance >= 0.95)
+    const importance = entry.importance ?? 0.5;
+    if (importance >= 0.95) continue;
+
+    // Check minimum age
+    const ageDays = (now - entry.timestamp) / 86_400_000;
+
+    // Decay-based archival (existing logic)
+    let shouldArchive = false;
+    if (ageDays >= config.minAgeDays) {
+      const evo = parseEvolution(entry.metadata, entry.timestamp);
+      let decayScore = computeDecayScore(evo, importance, now, entry.metadata);
+      // F3: Expired memories (validUntil < now) get 2x decay acceleration
+      if (evo.validUntil != null && evo.validUntil < now) {
+        decayScore *= 0.5; // Halve the score → archives faster
+      }
+      if (decayScore < config.decayScoreThreshold) {
+        shouldArchive = true;
+      }
+    }
+
+    // Retention-policy-based archival (F-2): OR with decay-based
+    if (!shouldArchive) {
+      const scope = entry.scope ?? "";
+      const policy = policyCache.get(scope) ?? loadRetentionPolicy(scope, retentionConfigDir);
+      const activeCount = activeCounts.get(scope) ?? 0;
+      const policyCheck = shouldArchiveByPolicy(policy, ageDays, activeCount);
+      if (policyCheck.archive) {
+        shouldArchive = true;
+      }
+    }
+
+    if (shouldArchive) {
+      const archivedMeta = buildArchivedMetadata(entry.metadata);
+      await store.update(entry.id, { metadata: archivedMeta });
       archivedCount++;
+      // F-1: Audit log — record archive operation (silent on failure)
+      try {
+        auditLogger?.log({
+          operation: "archive",
+          memoryId: entry.id,
+          actor: "system",
+          details: `auto-gc: age=${Math.floor(ageDays)}d`,
+        });
+      } catch { /* Audit must never block GC */ }
+      // Decrement active count for the scope (memory is no longer active)
+      const scope = entry.scope ?? "";
+      const prev = activeCounts.get(scope) ?? 0;
+      if (prev > 0) {
+        activeCounts.set(scope, prev - 1);
+      }
     }
   }
 

package/src/auto-recall.ts

@@ -1,5 +1,7 @@
 import { composeResumeContext, type ResumeContextDeps } from "./context-composer.js";
+import { resolveTier } from "./decay-engine.js";
 import type { DurableMemoryCategory } from "./memory-schema.js";
+import { governResults, truncateQuery, type GovernorConfig, type GovernorSession } from "./recall-governor.js";
 import type { RetrievalResult } from "./retriever.js";
 import { buildRetrievalContext, resolveScopeSelection } from "./scope-policy.js";
 import type { RetrievalProfileName, ResumeContextResponse } from "./session-schema.js";
@@ -17,6 +19,10 @@ export interface AutoRecallRequest {
   profile?: RetrievalProfileName;
   env?: NodeJS.ProcessEnv;
   operation?: string;
+  /** Governor config overrides (charBudget, maxItems, maxQueryChars) */
+  governor?: Partial<GovernorConfig>;
+  /** Governor session for cross-call dedup within a single conversation turn */
+  governorSession?: GovernorSession;
 }
 
 export interface AutoRecallResponse {
@@ -31,8 +37,10 @@ export async function runAutoRecall(
   deps: ResumeContextDeps,
   request: AutoRecallRequest,
 ): Promise<AutoRecallResponse> {
-  const message = request.message.replace(/\s+/g, " ").trim();
-  const task = (request.task || message).replace(/\s+/g, " ").trim();
+  const govCfg = request.governor;
+  const maxQ = govCfg?.maxQueryChars ?? 1000;
+  const message = truncateQuery(request.message.replace(/\s+/g, " ").trim(), maxQ);
+  const task = truncateQuery((request.task || message).replace(/\s+/g, " ").trim(), maxQ);
 
   if (!message) {
     throw new Error("message is required");
@@ -72,9 +80,11 @@ export async function runAutoRecall(
     };
   }
 
-  const results = await deps.retriever.retrieve(buildRetrievalContext({
+  const effectiveLimit = request.limit || 5;
+  // Fetch extra candidates so tier filtering still yields enough results
+  const rawResults = await deps.retriever.retrieve(buildRetrievalContext({
     query: message,
-    limit: request.limit || 5,
+    limit: effectiveLimit * 3,
     category: request.category,
     scope: resolvedScope,
     sessionId: request.sessionId,
@@ -86,6 +96,25 @@ export async function runAutoRecall(
     allowUnscoped: request.allScopes === true,
   }));
 
+  // Tier-aware filtering: prefer core/working memories, backfill with peripheral.
+  // Peripheral memories get a 15% score discount to reduce noise injection.
+  const promoted: RetrievalResult[] = [];
+  const demoted: RetrievalResult[] = [];
+  for (const r of rawResults) {
+    const tier = resolveTier(r.entry.metadata);
+    if (tier === "core" || tier === "working") {
+      promoted.push(r);
+    } else {
+      demoted.push({ ...r, score: r.score * 0.85 });
+    }
+  }
+  const tierFiltered = [...promoted, ...demoted]
+    .sort((a, b) => b.score - a.score)
+    .slice(0, effectiveLimit);
+
+  // LME-7: Recall Governor — evolution filter, budget control, session dedup
+  const results = governResults(tierFiltered, request.governorSession, govCfg);
+
   return {
     mode: "resume+search",
     resolvedScope,