recallnest 2.3.0 → 2.5.4

package/src/activity-counter.ts

@@ -11,6 +11,7 @@ import {
   mkdirSync,
 } from "node:fs";
 import { join, dirname } from "node:path";
+import * as envConfig from "./env-config.js";
 
 // ---------------------------------------------------------------------------
 // Config
@@ -29,7 +30,7 @@ export interface ActivityCounterConfig {
 
 export const DEFAULT_ACTIVITY_CONFIG: ActivityCounterConfig = {
   statsPath: join(
-    process.env.RECALLNEST_DATA_DIR || "data",
+    envConfig.dataDir(),
     "activity-stats.json",
   ),
   lightThreshold: 15,
@@ -44,8 +45,8 @@ export type DistillTier = "none" | "light" | "standard" | "deep";
 // ---------------------------------------------------------------------------
 
 interface ActivityStats {
-  writesSinceLastDistill: number;
-  lastResetAt: number;
+  /** Per-scope write counts since that scope's last dream/distill reset. */
+  scopes: Record<string, number>;
 }
 
 function resolveConfig(
@@ -56,12 +57,24 @@ function resolveConfig(
 
 function readStats(statsPath: string): ActivityStats {
   if (!existsSync(statsPath)) {
-    return { writesSinceLastDistill: 0, lastResetAt: Date.now() };
+    return { scopes: {} };
   }
   try {
-    return JSON.parse(readFileSync(statsPath, "utf-8"));
+    const parsed: unknown = JSON.parse(readFileSync(statsPath, "utf-8"));
+    // Robust against the legacy global format ({writesSinceLastDistill}) — no migration,
+    // just treat anything without a `scopes` map as empty (counts restart per scope).
+    if (
+      parsed !== null &&
+      typeof parsed === "object" &&
+      "scopes" in parsed &&
+      typeof (parsed as { scopes?: unknown }).scopes === "object" &&
+      (parsed as { scopes?: unknown }).scopes !== null
+    ) {
+      return { scopes: (parsed as { scopes: Record<string, number> }).scopes };
+    }
+    return { scopes: {} };
   } catch {
-    return { writesSinceLastDistill: 0, lastResetAt: Date.now() };
+    return { scopes: {} };
   }
 }
 
@@ -74,34 +87,49 @@ function writeStats(statsPath: string, stats: ActivityStats): void {
 // Public API
 // ---------------------------------------------------------------------------
 
-/** Increment write counter by n (default 1). Returns new count. */
+/** Increment a scope's write counter by n (default 1). Returns the scope's new count. */
 export function incrementWriteCount(
+  scope: string,
   n = 1,
   cfg?: Partial<ActivityCounterConfig>,
 ): number {
   const { statsPath } = resolveConfig(cfg);
   const stats = readStats(statsPath);
-  stats.writesSinceLastDistill += n;
+  stats.scopes[scope] = (stats.scopes[scope] ?? 0) + n;
   writeStats(statsPath, stats);
-  return stats.writesSinceLastDistill;
+  return stats.scopes[scope];
 }
 
-/** Read current write count without modifying. */
-export function getWriteCount(cfg?: Partial<ActivityCounterConfig>): number {
+/** Read a scope's current write count without modifying (0 if never written). */
+export function getWriteCount(scope: string, cfg?: Partial<ActivityCounterConfig>): number {
   const { statsPath } = resolveConfig(cfg);
-  return readStats(statsPath).writesSinceLastDistill;
+  return readStats(statsPath).scopes[scope] ?? 0;
 }
 
-/** Reset counter after successful distill. */
-export function resetWriteCount(cfg?: Partial<ActivityCounterConfig>): void {
+/** Reset one scope's counter after its successful dream/distill (leaves other scopes untouched). */
+export function resetWriteCount(scope: string, cfg?: Partial<ActivityCounterConfig>): void {
   const { statsPath } = resolveConfig(cfg);
-  writeStats(statsPath, { writesSinceLastDistill: 0, lastResetAt: Date.now() });
+  const stats = readStats(statsPath);
+  delete stats.scopes[scope];
+  writeStats(statsPath, stats);
+}
+
+/** Scopes whose write count is at or above `threshold` — the dream scheduler's work list. */
+export function listScopesAboveThreshold(
+  threshold: number,
+  cfg?: Partial<ActivityCounterConfig>,
+): string[] {
+  const { statsPath } = resolveConfig(cfg);
+  const stats = readStats(statsPath);
+  return Object.entries(stats.scopes)
+    .filter(([, count]) => count >= threshold)
+    .map(([scope]) => scope);
 }
 
-/** Determine which distill tier the current write count warrants. */
-export function getDistillTier(cfg?: Partial<ActivityCounterConfig>): DistillTier {
+/** Determine which distill tier a scope's write count warrants. */
+export function getDistillTier(scope: string, cfg?: Partial<ActivityCounterConfig>): DistillTier {
   const config = resolveConfig(cfg);
-  const count = getWriteCount(cfg);
+  const count = getWriteCount(scope, cfg);
   if (count >= config.deepThreshold) return "deep";
   if (count >= config.standardThreshold) return "standard";
   if (count >= config.lightThreshold) return "light";

package/src/aliases.ts

@@ -0,0 +1,133 @@
+/**
+ * Alias dictionary for query rewriting.
+ *
+ * Manually maintained — do NOT use LLM expansion (risks precision pollution).
+ * Each rule appends entity tokens to the query when the pattern matches,
+ * giving BM25/vector search more anchor points without losing the original wording.
+ *
+ * Why expand (append) rather than replace:
+ * - Preserves the user's exact wording for vector embedding fidelity.
+ * - BM25 gets extra keyword anchors to find the right entity.
+ * - Reversible via inspecting the expanded vs. original query.
+ *
+ * Add new rules sparingly. Each entry should solve a real failure
+ * documented in FAILURES.md, not a hypothetical.
+ */
+
+export interface AliasRule {
+  pattern: RegExp;
+  expansion: string;
+  comment?: string;
+}
+
+export const ALIAS_RULES: AliasRule[] = [
+  // Entity aliases — colloquial → canonical name
+  {
+    pattern: /(?:我的)?记忆项目/,
+    expansion: "recallnest",
+    comment: "FAILURES 2026-04-25: '我的记忆项目' → recallnest",
+  },
+  {
+    pattern: /我的桥/,
+    expansion: "telegram-ai-bridge",
+    comment: "Alice 用'我的桥'指 telegram-ai-bridge",
+  },
+
+  // Operations vocabulary — operator wording → canonical entities
+  {
+    pattern: /aws\s*(?:bot|ssh|podcast)/i,
+    expansion: "aws-bot hermes-aws aws-podcast-daily",
+    comment: "FAILURES 2026-03-06: aws bot/ssh/podcast → aws-bot hermes-aws entities",
+  },
+  {
+    pattern: /bot\s*(?:挂|崩|不能用|跑不起|失联|down)/i,
+    expansion: "bot-doctor hermes docker launchd 排查 重启",
+    comment: "Operator bot-crash debugging vocabulary",
+  },
+
+  // Cross-window / continuity hints — these strengthen recall of session state.
+  // Pattern 必须明确出现"隔壁/另一窗口/session"才扩；纯"之前说过"太宽会污染
+  // 普通话题（如 fuzzy_ai_feelings 的 "之前聊过 AI 感受" 被错误归类成 cross-window）。
+  {
+    pattern: /(?:刚刚|刚才|之前)(?:.{0,10})(?:隔壁|另一个|其他)(?:.{0,10})(?:窗口|session)/,
+    expansion: "checkpoint session resume_context 跨窗口",
+    comment: "FAILURES 2026-05-10: cross-window real-time sync hint",
+  },
+
+  // Tool provenance — common ambiguous tool references
+  {
+    pattern: /taobao.{0,5}(?:mcp|官方)/i,
+    expansion: "MCP server provenance source",
+    comment: "FAILURES 2026-05-01: taobao MCP official-vs-third-party",
+  },
+
+  // RecallNest self-introspection — capability queries
+  {
+    pattern: /recallnest.{0,15}(?:有哪些|工具|能做|功能|tool)/i,
+    expansion: "search_memory store_memory resume_context checkpoint_session MCP",
+    comment: "FAILURES 2026-04-20: RN self-introspection capability digest",
+  },
+  {
+    pattern: /recallnest.{0,10}(?:ingest|跑了|跑过|状态|telemetry)/i,
+    expansion: "import_conversations weekly-distill ingest telemetry 成功 失败",
+    comment: "FAILURES 2026-04-20: RN ingest telemetry queries",
+  },
+
+  // Personal-life recall — subscription / friends provenance
+  {
+    pattern: /(?:chatgpt|订阅).{0,10}(?:谁|怎么|哪里|帮|顶)/i,
+    expansion: "ChatGPT Plus 群友 加拿大 堂姐 澳洲 代订 aliceljyalice",
+    comment: "FAILURES 2026-05-12: ChatGPT subscription provenance chain",
+  },
+];
+
+/** 超过此长度的 query 不做别名扩展——长 query 是粘贴文档场景,扩展只添噪声 (P1-B)。 */
+export const ALIAS_QUERY_MAX_LENGTH = 100;
+
+/**
+ * Expand a query by appending alias tokens for matching patterns.
+ * Returns the original query unchanged if no rules match.
+ *
+ * 注意分工:本模块只承载**静态 builtin 规则**,作用于 retrieve() 全通道
+ * (vector + BM25)。**用户级** alias(data/alias-map.json)由
+ * query-expander.ts 加载,只作用于 BM25 通道(hybridRetrieval 内部)——
+ * 用户别名不进 vector embedding,避免随手加的别名造成语义向量漂移。
+ *
+ * Example:
+ *   expandQueryWithAliases("帮我看我的记忆项目")
+ *     → "帮我看我的记忆项目 recallnest"
+ *   expandQueryWithAliases("aws ssh 怎么连")
+ *     → "aws ssh 怎么连 aws-bot hermes-aws aws-podcast-daily"
+ */
+export function expandQueryWithAliases(query: string): string {
+  if (!query || typeof query !== "string") return query;
+  if (query.length > ALIAS_QUERY_MAX_LENGTH) return query;
+
+  const additions: string[] = [];
+  const seen = new Set<string>();
+
+  for (const rule of ALIAS_RULES) {
+    if (rule.pattern.test(query)) {
+      for (const token of rule.expansion.split(/\s+/)) {
+        if (token && !seen.has(token) && !query.includes(token)) {
+          additions.push(token);
+          seen.add(token);
+        }
+      }
+    }
+  }
+
+  return additions.length > 0 ? `${query} ${additions.join(" ")}` : query;
+}
+
+/**
+ * Inspection helper — return which builtin rules matched a query, for debugging.
+ * 用户级规则(BM25-only)的检视走 query-expander.ts 的 explainUserAliases。
+ */
+export function explainAliasExpansion(query: string): Array<{ pattern: string; expansion: string; comment?: string }> {
+  return ALIAS_RULES.filter((rule) => rule.pattern.test(query)).map((rule) => ({
+    pattern: rule.pattern.source,
+    expansion: rule.expansion,
+    comment: rule.comment,
+  }));
+}

package/src/api-server.ts

@@ -17,19 +17,23 @@ import { ConflictStatusSchema } from "./conflict-schema.js";
 import { resolveConflictCandidate } from "./conflict-engine.js";
 import { escalateConflicts } from "./conflict-escalation.js";
 import { ConflictCandidateStore } from "./conflict-store.js";
+import { createAuditLogger } from "./audit-log.js";
 import { parseConflictAttention, summarizeConflictLifecycle } from "./conflict-lifecycle.js";
 import { buildConflictAuditSummary, clusterConflicts, summarizeConflictAdvice } from "./conflict-advisor.js";
 import { buildWorkflowEvidence, buildWorkflowObservationRecord, inspectWorkflowDashboard, inspectWorkflowHealth } from "./workflow-observation-engine.js";
+import { recordSkillOutcome } from "./skill-engine.js";
 import { WorkflowObservationStore } from "./workflow-observation-store.js";
 import { buildManagedCheckpointObservation, buildManagedResumeObservation } from "./workflow-observation-managed.js";
 import { runAutoRecall } from "./auto-recall.js";
 import { buildRetrievalContext, resolveScopeSelection } from "./scope-policy.js";
 import { runMemoryLint } from "./memory-lint.js";
+import * as envConfig from "./env-config.js";
 
 const config = (loadDotEnv(), loadConfig());
 const getComponents = createComponentResolver(config);
 const checkpointStore = new SessionCheckpointStore();
 const conflictStore = new ConflictCandidateStore();
+const auditLogger = createAuditLogger();
 const workflowObservationStore = new WorkflowObservationStore();
 
 // ============================================================================
@@ -235,7 +239,7 @@ async function handleStore(request: Request): Promise<Response> {
   const body = await readJson(request);
   try {
     const { store, embedder } = getComponents();
-    const stored = await persistMemory({ store, embedder, conflictStore }, body);
+    const stored = await persistMemory({ store, embedder, conflictStore, auditLogger }, body);
 
     return jsonResponse({
       id: stored.id,
@@ -284,7 +288,7 @@ async function handlePattern(request: Request): Promise<Response> {
   const body = await readJson(request);
   try {
     const { store, embedder } = getComponents();
-    const stored = await persistWorkflowPattern({ store, embedder, conflictStore }, body);
+    const stored = await persistWorkflowPattern({ store, embedder, conflictStore, auditLogger }, body);
     return jsonResponse({
       id: stored.id,
       stored: stored.disposition !== "conflict",
@@ -308,7 +312,7 @@ async function handleCase(request: Request): Promise<Response> {
   const body = await readJson(request);
   try {
     const { store, embedder } = getComponents();
-    const stored = await persistCaseMemory({ store, embedder, conflictStore }, body);
+    const stored = await persistCaseMemory({ store, embedder, conflictStore, auditLogger }, body);
     return jsonResponse({
       id: stored.id,
       stored: stored.disposition !== "conflict",
@@ -332,7 +336,7 @@ async function handlePromote(request: Request): Promise<Response> {
   const body = await readJson(request);
   try {
     const { store, embedder } = getComponents();
-    const stored = await promoteMemory({ store, embedder, conflictStore }, body);
+    const stored = await promoteMemory({ store, embedder, conflictStore, auditLogger }, body);
     return jsonResponse({
       id: stored.id,
       stored: stored.disposition !== "conflict",
@@ -455,13 +459,29 @@ async function handleCheckpoint(request: Request): Promise<Response> {
   }
 }
 
-/** POST /v1/workflow-observe — persist a workflow observation outside durable memory */
+/** POST /v1/workflow-observe — persist a workflow observation outside durable memory; bumps skill counters when `skillId` is present */
 async function handleWorkflowObserve(request: Request): Promise<Response> {
   const body = await readJson(request);
   try {
     const record = buildWorkflowObservationRecord(body);
     const stored = await workflowObservationStore.save(record);
-    return jsonResponse(stored, 201);
+
+    let skillOutcome: unknown = undefined;
+    if (record.skillId) {
+      try {
+        const { store } = getComponents();
+        const result = await recordSkillOutcome(store, record.skillId, record.outcome);
+        skillOutcome = result;
+        if (!result.updated) {
+          console.warn(`[api /v1/workflow-observe] skillId=${record.skillId} update skipped: ${result.reason}`);
+        }
+      } catch (err) {
+        console.warn(`[api /v1/workflow-observe] recordSkillOutcome threw for skillId=${record.skillId}:`, err);
+        skillOutcome = { updated: false, reason: "exception" };
+      }
+    }
+
+    return jsonResponse({ observation: stored, ...(skillOutcome !== undefined ? { skillOutcome } : {}) }, 201);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     return errorResponse(400, message);
@@ -625,7 +645,7 @@ async function handleHealth(): Promise<Response> {
 // Server
 // ============================================================================
 
-const port = clampInt(process.env.RECALLNEST_API_PORT, 4318, 1, 65535);
+const port = clampInt(envConfig.apiPortRaw(), 4318, 1, 65535);
 
 const server = Bun.serve({
   port,

package/src/audit-log.ts

@@ -7,6 +7,7 @@
 
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import * as envConfig from "./env-config.js";
 
 export type AuditOperation =
   | "store"
@@ -17,7 +18,8 @@ export type AuditOperation =
   | "supersede"
   | "consolidate"
   | "forget"
-  | "cascade_forget";
+  | "cascade_forget"
+  | "reject";
 
 export interface AuditEntry {
   timestamp: string; // ISO 8601
@@ -59,7 +61,7 @@ function parseLines(raw: string): AuditEntry[] {
 export function createAuditLogger(logPath?: string): AuditLogger {
   const resolvedPath =
     logPath ??
-    join(process.env.RECALLNEST_DATA_DIR || "data", "audit.jsonl");
+    join(envConfig.dataDir(), "audit.jsonl");
 
   // Ensure directory exists (silent on failure)
   try {

package/src/auto-consolidation.ts

@@ -10,7 +10,8 @@
  * reason is operational hygiene.
  */
 
-import type { MemoryStore } from "./store.js";
+import type { MemoryEntry } from "./store.js";
+import type { MemoryStorePort } from "./memory-store-port.js";
 import { ConsolidationEngine, type ConsolidationConfig, type ConsolidationResult, DEFAULT_CONSOLIDATION_CONFIG } from "./consolidation-engine.js";
 import type { LLMClient } from "./llm-client.js";
 import { isLLMConsolidationEnabled, evaluateCluster, executeMergeDecisions } from "./llm-consolidation.js";
@@ -54,16 +55,20 @@ export interface AutoConsolidationResult {
 /**
  * Check conditions and run consolidation if thresholds are met.
  * Returns immediately if conditions not met (no-op).
+ *
+ * @deprecated Prefer dream-pipeline.ts for full maintenance. This module is
+ * kept for compatibility with callers that only need count/time-gated
+ * consolidation.
  */
 export async function maybeConsolidate(
-  store: MemoryStore,
+  store: MemoryStorePort,
   scope: string,
   config: AutoConsolidationConfig = DEFAULT_AUTO_CONSOLIDATION_CONFIG,
   /** Tier 3.7: Optional LLM client for semantic consolidation decisions */
   llm?: LLMClient | null,
 ): Promise<AutoConsolidationResult> {
   const stats = await store.stats([scope]);
-  const currentCount = stats.total ?? 0;
+  const currentCount = stats.totalCount ?? 0;
 
   // Condition 1: enough new memories since last run
   const newSinceLastRun = currentCount - lastRunMemoryCount;

package/src/auto-gc.ts

@@ -9,16 +9,20 @@
  * instead of raw age/importance heuristics. Archive-first, delete-never.
  */
 
-import type { MemoryStore } from "./store.js";
+import type { MemoryStorePort } from "./memory-store-port.js";
 import {
   parseEvolution,
   computeDecayScore,
+  computeUsageAdjustedDecayScore,
   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";
+import * as envConfig from "./env-config.js";
+import { isUsageSignalActive } from "./usage-tracker.js";
+import { acquireLock, releaseLock, getLastDistillTime, stampLock, lockPathForKey } from "./distill-lock.js";
 
 // ---------------------------------------------------------------------------
 // Config
@@ -73,48 +77,89 @@ export interface GcResult {
  * - Not pinned (importance >= 0.95 is considered pinned)
  */
 export async function maybeRunGc(
-  store: MemoryStore,
+  store: MemoryStorePort,
   config: AutoGcConfig = DEFAULT_AUTO_GC_CONFIG,
   retentionConfigDir?: string,
   auditLogger?: AuditLogger,
 ): Promise<GcResult> {
   const stats = await store.stats();
-  const totalMemories = stats.total ?? 0;
+  const totalMemories = stats.totalCount ?? 0;
 
   // Condition 1: enough memories to warrant GC
   if (totalMemories < config.minMemoryCount) {
     return { triggered: false, reason: "below_memory_threshold", archivedCount: 0, totalChecked: 0 };
   }
 
-  // Condition 2: enough time since last GC
-  const hoursSinceLastGc = (Date.now() - lastGcTimestamp) / 3_600_000;
+  // Condition 2: enough time since last GC. P0-1: the throttle is cross-process now —
+  // take the max of this process's in-memory timestamp and the shared gc-last stamp
+  // file's mtime. The old module-level var alone let each of the 11 mcp-server
+  // processes run gc on its own independent 24h clock.
+  const gcStampPath = lockPathForKey("gc-last");
+  const lastGc = Math.max(lastGcTimestamp, getLastDistillTime({ lockPath: gcStampPath }));
+  const hoursSinceLastGc = (Date.now() - lastGc) / 3_600_000;
   if (hoursSinceLastGc < config.minHoursSinceLastGc) {
     return { triggered: false, reason: "too_soon", archivedCount: 0, totalChecked: 0 };
   }
 
+  // Concurrency guard: only one process scans the full corpus at a time. A process that
+  // passed the throttle in the same instant loses the O_EXCL race here and skips.
+  const gcRunLock = { lockPath: lockPathForKey("gc-run"), expireMs: 30 * 60_000 };
+  if (!acquireLock(gcRunLock)) {
+    return { triggered: false, reason: "locked_by_another_process", archivedCount: 0, totalChecked: 0 };
+  }
+
   // All conditions met — run GC
-  lastGcTimestamp = Date.now();
+  lastGcTimestamp = Date.now(); // in-process immediate throttle
 
+  try {
+    const { archivedCount, totalChecked } = await runGcScan(store, config, retentionConfigDir, auditLogger);
+    // Stamp completion into the shared throttle marker (create-or-touch → mtime = now)
+    // so the other processes observe "last run" via getLastDistillTime.
+    stampLock({ lockPath: gcStampPath });
+    return { triggered: true, archivedCount, totalChecked };
+  } finally {
+    releaseLock(gcRunLock);
+  }
+}
+
+/**
+ * The full-corpus archive scan — the body of a triggered GC run. Extracted from
+ * maybeRunGc so the P0-1 lock/throttle wiring stays readable; the scan logic itself
+ * is unchanged.
+ */
+async function runGcScan(
+  store: MemoryStorePort,
+  config: AutoGcConfig,
+  retentionConfigDir: string | undefined,
+  auditLogger: AuditLogger | undefined,
+): Promise<{ archivedCount: number; totalChecked: number }> {
   const now = Date.now();
   let archivedCount = 0;
   let totalChecked = 0;
 
-  // Scan memories by listing them
-  const entries = await store.list({ limit: 5000 });
-  totalChecked = entries.length;
+  // Full-corpus scan, page by page. The previous implementation listed only
+  // the newest 5000 rows (list() sorts by timestamp desc before slicing) —
+  // old low-value memories, the very target of GC, never entered the scan
+  // window on a 99K+ corpus. Two passes keep memory at one page instead of
+  // the whole corpus; pass 2 mutates rows (archive), which may shift fragment
+  // scan order — a row missed this run is caught by the next one.
+  const GC_PAGE_SIZE = 2000;
 
-  // Pre-compute per-scope active memory counts and cache retention policies.
-  // This avoids repeated file reads inside the loop.
+  // Pass 1: per-scope active memory counts for retention policies.
   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);
+  for (let offset = 0; ; offset += GC_PAGE_SIZE) {
+    const page = await store.listPage({ limit: GC_PAGE_SIZE, offset });
+    for (const entry of page) {
+      const scope = entry.scope ?? "";
+      scopesSeen.add(scope);
+      if (isActiveMemory(entry.metadata)) {
+        activeCounts.set(scope, (activeCounts.get(scope) ?? 0) + 1);
+      }
     }
+    if (page.length < GC_PAGE_SIZE) break;
   }
 
   // Batch-load retention policies for all scopes (one file read per scope)
@@ -122,8 +167,15 @@ export async function maybeRunGc(
     policyCache.set(scope, loadRetentionPolicy(scope, retentionConfigDir));
   }
 
-  for (const entry of entries) {
-    if (archivedCount >= config.maxArchivePerRun) break;
+  // Pass 2: archive sweep.
+  const useUsageAdjustedDecay = envConfig.usageDecay() && isUsageSignalActive();
+  outer:
+  for (let offset = 0; ; offset += GC_PAGE_SIZE) {
+    const page = await store.listPage({ limit: GC_PAGE_SIZE, offset });
+    totalChecked += page.length;
+
+  for (const entry of page) {
+    if (archivedCount >= config.maxArchivePerRun) break outer;
 
     // Only archive active memories
     if (!isActiveMemory(entry.metadata)) continue;
@@ -139,7 +191,9 @@ export async function maybeRunGc(
     let shouldArchive = false;
     if (ageDays >= config.minAgeDays) {
       const evo = parseEvolution(entry.metadata, entry.timestamp);
-      let decayScore = computeDecayScore(evo, importance, now, entry.metadata);
+      let decayScore = useUsageAdjustedDecay
+        ? computeUsageAdjustedDecayScore(evo, importance, now, entry.metadata)
+        : 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
@@ -182,12 +236,22 @@ export async function maybeRunGc(
     }
   }
 
-  return { triggered: true, archivedCount, totalChecked };
+    if (page.length < GC_PAGE_SIZE) break;
+  }
+
+  return { archivedCount, totalChecked };
 }
 
 /**
- * Reset last GC timestamp (for testing).
+ * Reset last GC timestamp (for testing). Clears both the in-memory timestamp and the
+ * persisted cross-process throttle marker / run lock so tests start from a clean slate.
  */
 export function resetGcTimestamp(): void {
   lastGcTimestamp = 0;
+  try {
+    releaseLock({ lockPath: lockPathForKey("gc-last") });
+    releaseLock({ lockPath: lockPathForKey("gc-run") });
+  } catch {
+    /* ignore — nothing to clear */
+  }
 }