recallnest 2.6.1 → 3.0.1

package/integrations/agy/README.md

@@ -0,0 +1,73 @@
+# Antigravity CLI (agy) Integration
+
+> agy 接入指南：一键配 MCP + continuity 规则，让 agy 在新窗口里主动恢复稳定上下文。
+
+> **Note on naming.** Google retired the standalone `gemini` CLI for personal
+> accounts on 2026-06-18; the [Antigravity CLI](https://antigravity.google)
+> (`agy`) is its successor. This integration targets `agy`. If you are on a
+> Code Assist Standard/Enterprise plan and still run the legacy CLI, point the
+> same MCP entry at whatever config file your build reads.
+
+## Quick Start
+
+```bash
+bash integrations/agy/setup.sh
+```
+
+## What It Does
+
+- Adds RecallNest as an MCP server in `~/.gemini/config/mcp_config.json`
+- Installs a managed RecallNest block in `~/.gemini/config/GEMINI.md`
+
+## Continuity Rules
+
+The managed block comes from [agy-md-snippet.md](agy-md-snippet.md) and tells agy to:
+
+- call `resume_context` at the start of fresh windows or continuity-sensitive tasks
+- run lightweight `search_memory` on task pivots inside the same project before repo exploration drifts
+- reuse known `scope` / `sessionId` and the resolved scope returned by `resume_context` in follow-up recall calls
+- treat recalled or startup-hook repo state as unverified until this window explicitly checks the repo
+- save `checkpoint_session` before leaving resumable work
+- do not inspect repo state just to enrich a close-window checkpoint unless the user explicitly asked for repo state
+- do not write unverified repo-state claims into `checkpoint_session`
+- capture durable facts with `store_memory` and reusable workflows with `store_workflow_pattern`
+
+## Shared Index
+
+agy shares the same LanceDB index as Claude Code, Codex and Kimi. Memories ingested from any source are searchable by all of them.
+
+## Manual Setup
+
+Add to `~/.gemini/config/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "recallnest": {
+      "type": "stdio",
+      "command": "bun",
+      "args": ["run", "RECALLNEST_PATH/src/mcp-server.ts"]
+    }
+  }
+}
+```
+
+Replace `RECALLNEST_PATH` with your actual path.
+
+Then copy [agy-md-snippet.md](agy-md-snippet.md) into `~/.gemini/config/GEMINI.md` if you are not using `setup.sh`.
+
+## Tool Permissions
+
+agy gates tool calls separately from MCP registration. In non-interactive mode
+(`agy -p`) it cannot prompt, so permission-requiring tools are auto-denied and
+the agent silently returns nothing. If RecallNest tools appear registered but
+never fire, set `toolPermission` in `~/.gemini/antigravity-cli/settings.json`,
+or pass `--dangerously-skip-permissions` for a single run.
+
+## Verify
+
+```bash
+agy -p "resume my context for RecallNest continuity work" --print-timeout 180s </dev/null
+```
+
+If `resume_context` or `search_memory` is called, you're set.

package/integrations/agy/setup.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# RecallNest — Antigravity CLI (agy) MCP setup (idempotent)
+# Usage: bash integrations/agy/setup.sh
+#
+# Google retired the standalone Gemini CLI for personal accounts on 2026-06-18.
+# Its successor is the Antigravity CLI (`agy`), which reads MCP servers from
+# ~/.gemini/config/mcp_config.json — not the old ~/.gemini/settings.json.
+
+set -euo pipefail
+
+AGY_CONFIG_DIR="$HOME/.gemini/config"
+AGY_MCP_CONFIG="$AGY_CONFIG_DIR/mcp_config.json"
+AGY_MD="$AGY_CONFIG_DIR/GEMINI.md"
+RECALLNEST_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
+MCP_ENTRY="$RECALLNEST_DIR/src/mcp-server.ts"
+RULES_SNIPPET="$RECALLNEST_DIR/integrations/agy/agy-md-snippet.md"
+RULES_HELPER="$RECALLNEST_DIR/integrations/shared/install-managed-block.sh"
+
+if [[ ! -f "$MCP_ENTRY" ]]; then
+  echo "ERROR: $MCP_ENTRY not found. Run this from the recallnest repo root."
+  exit 1
+fi
+
+if [[ ! -f "$RULES_HELPER" ]]; then
+  echo "ERROR: $RULES_HELPER not found."
+  exit 1
+fi
+
+if ! command -v agy >/dev/null 2>&1; then
+  echo "WARNING: 'agy' not found on PATH. Install the Antigravity CLI first:"
+  echo "  https://antigravity.google"
+  echo "Continuing anyway — the config will be written for when agy is installed."
+  echo ""
+fi
+
+mkdir -p "$AGY_CONFIG_DIR"
+if [[ ! -f "$AGY_MCP_CONFIG" ]]; then
+  echo '{"mcpServers":{}}' > "$AGY_MCP_CONFIG"
+  echo "Created $AGY_MCP_CONFIG"
+fi
+
+# Check if already configured
+if bun -e "
+  const c = JSON.parse(require('fs').readFileSync('$AGY_MCP_CONFIG','utf8'));
+  process.exit(c.mcpServers?.recallnest ? 0 : 1);
+" 2>/dev/null; then
+  echo "RecallNest MCP already configured in $AGY_MCP_CONFIG — skipping."
+else
+  bun -e "
+    const fs = require('fs');
+    const c = JSON.parse(fs.readFileSync('$AGY_MCP_CONFIG','utf8'));
+    if (!c.mcpServers) c.mcpServers = {};
+    c.mcpServers.recallnest = {
+      type: 'stdio',
+      command: 'bun',
+      args: ['run', '$MCP_ENTRY']
+    };
+    fs.writeFileSync('$AGY_MCP_CONFIG', JSON.stringify(c, null, 2) + '\n');
+  "
+  echo "Added RecallNest MCP to $AGY_MCP_CONFIG"
+fi
+
+. "$RULES_HELPER"
+install_managed_markdown_block "$RULES_SNIPPET" "$AGY_MD" "recallnest-continuity"
+echo "Installed RecallNest continuity rules in $AGY_MD"
+
+echo ""
+echo "Setup complete. Restart agy to activate, then verify with:"
+echo "  agy -p 'List your available MCP tools' --print-timeout 180s </dev/null"
+echo ""
+echo "Continuity baseline seed:"
+echo "  (cd \"$RECALLNEST_DIR\" && bun run seed:continuity)"
+echo ""
+echo "Managed snippet source:"
+echo "  $RULES_SNIPPET"

package/integrations/setup-all.sh

@@ -19,7 +19,7 @@ bash "$SCRIPT_DIR/codex/setup.sh"
 echo ""
 
 echo "--- Gemini CLI ---"
-bash "$SCRIPT_DIR/gemini-cli/setup.sh"
+bash "$SCRIPT_DIR/agy/setup.sh"
 echo ""
 
 echo "======================================"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recallnest",
-  "version": "2.6.1",
+  "version": "3.0.1",
   "description": "RecallNest — MCP-native, local-first memory search and distillation for AI conversations",
   "license": "MIT",
   "type": "module",
@@ -22,7 +22,8 @@
     "eval/continuity/*.json",
     "integrations/",
     "README_CN.md",
-    "src/"
+    "src/",
+    "!src/**/__tests__/**"
   ],
   "scripts": {
     "search": "bun run src/cli.ts search",
@@ -54,17 +55,18 @@
     "seed:continuity": "bun run seed:patterns && bun run seed:cases && bun run seed:memories",
     "smoke:claude-continuity": "bash integrations/claude-code/smoke-continuity.sh",
     "ui": "bun run src/ui-server.ts",
-    "api": "bun run src/api-server.ts"
+    "api": "bun run src/api-server.ts",
+    "gateway": "bun run src/gateway-server.ts"
   },
   "engines": {
-    "node": ">=18.14.1"
+    "node": ">=22"
   },
   "dependencies": {
     "@hono/node-server": "1.19.17",
     "@lancedb/lancedb": "^0.26.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "commander": "^12.0.0",
-    "openai": "^4.0.0",
+    "openai": "^7.5.0",
     "tsx": "^4.19.0",
     "zod": "^3.25.76"
   },

package/src/access-tracker.ts

@@ -11,6 +11,7 @@
 
 import type { MemoryStore } from "./store.js";
 import { evaluateTierChange, resolveTier, type MemoryTier } from "./decay-engine.js";
+import { PROCESS_READER_ID, recordRecallHits } from "./recall-ledger.js";
 import { logInfo, logWarn } from "./stderr-log.js";
 
 // ============================================================================
@@ -70,7 +71,10 @@ export class AccessTracker {
     private config: AccessTrackerConfig = DEFAULT_ACCESS_TRACKER_CONFIG,
     readerId?: string,
   ) {
-    this.readerId = readerId ?? `r-${crypto.randomUUID().slice(0, 8)}`;
+    // 默认取进程级身份，不是每个实例各随机一个：components 按 profile 缓存，
+    // 一个会话开两个 profile 就会伪造出两个 reader，既污染 distinctReaderCount
+    // 也让 workflow observation 的 readerId join 对不上（见 recall-ledger.ts 抬头）。
+    this.readerId = readerId ?? PROCESS_READER_ID;
   }
 
   /**
@@ -137,6 +141,11 @@ export class AccessTracker {
 
     const now = Date.now();
 
+    // P0 join key：先记账本再过闸。账本回答「agent 看到过哪些条目」，
+    // 下面的 novelty/cooldown 闸回答「哪些值得强化半衰期」——两个问题，
+    // 用后者过滤前者会把最常被读到的条目系统性排除在 join 之外。
+    recordRecallHits(ids, now);
+
     for (let i = 0; i < ids.length; i++) {
       const id = ids[i];
       const score = scores?.[i];

package/src/activity-counter.ts

@@ -2,6 +2,16 @@
  * HP-3: Activity-driven distill frequency.
  * Tracks write operations since last distill, exposes tier-based thresholds.
  * Complements CC-6 distill-lock: HP-3 decides "when to trigger", CC-6 decides "whether to allow".
+ *
+ * 2026-08-14 并发加固（dream 写爆库根治的一部分）：
+ * - 写路径（increment/reset/resetBatch/prune）全部 async 化，进 `activity-stats` 跨进程锁 ——
+ *   此前 increment（11 个 mcp-server + ingest）与 reset（dream 04:00）裸读改写同一文件，
+ *   互踩窗口内的计数会静默丢失。
+ * - writeStats 改临时文件 + 原子 rename：裸 writeFileSync 期间被并发读到半截 JSON 时，
+ *   readStats 的 catch 会返回空表 —— 一次损坏放大成"整个队列清零"。原子替换后读方
+ *   永远看到完整文件（旧版或新版）。
+ * - 读路径（getWriteCount/listScopesAboveThreshold/getDistillTier）保持同步无锁：原子
+ *   rename 保证读到的文件完整；读到旧一拍的计数对 best-effort 语义无害。
  */
 
 import {
@@ -9,9 +19,11 @@ import {
   readFileSync,
   writeFileSync,
   mkdirSync,
+  renameSync,
 } from "node:fs";
 import { join, dirname } from "node:path";
 import * as envConfig from "./env-config.js";
+import { withLock } from "./distill-lock.js";
 
 // ---------------------------------------------------------------------------
 // Config
@@ -80,7 +92,22 @@ function readStats(statsPath: string): ActivityStats {
 
 function writeStats(statsPath: string, stats: ActivityStats): void {
   mkdirSync(dirname(statsPath), { recursive: true });
-  writeFileSync(statsPath, JSON.stringify(stats, null, 2), "utf-8");
+  // 原子替换：先写同目录临时文件再 rename。并发读方要么看到旧版要么看到新版，
+  // 不会读到半截 JSON（那会被 readStats 的 catch 吞成空表，把整个队列清零）。
+  const tmpPath = `${statsPath}.tmp-${process.pid}`;
+  writeFileSync(tmpPath, JSON.stringify(stats, null, 2), "utf-8");
+  renameSync(tmpPath, statsPath);
+}
+
+/** 写路径共用的锁参数：等待而非跳过（丢计数=丢 dream 触发信号），短超时防卡死写入方。 */
+const ACTIVITY_LOCK_KEY = "activity-stats";
+const ACTIVITY_LOCK_OPTS = { onBusy: "wait" as const, waitTimeoutMs: 2_000, expireMs: 30_000 };
+
+async function withStatsLock<T>(fn: () => T): Promise<T> {
+  const outcome = await withLock(ACTIVITY_LOCK_KEY, async () => fn(), ACTIVITY_LOCK_OPTS);
+  // onBusy:"wait" resolves ran:true or throws on timeout; ran:false unreachable.
+  if (!outcome.ran) throw new Error("activity-stats lock unavailable");
+  return outcome.result;
 }
 
 // ---------------------------------------------------------------------------
@@ -88,16 +115,18 @@ function writeStats(statsPath: string, stats: ActivityStats): void {
 // ---------------------------------------------------------------------------
 
 /** Increment a scope's write counter by n (default 1). Returns the scope's new count. */
-export function incrementWriteCount(
+export async function incrementWriteCount(
   scope: string,
   n = 1,
   cfg?: Partial<ActivityCounterConfig>,
-): number {
+): Promise<number> {
   const { statsPath } = resolveConfig(cfg);
-  const stats = readStats(statsPath);
-  stats.scopes[scope] = (stats.scopes[scope] ?? 0) + n;
-  writeStats(statsPath, stats);
-  return stats.scopes[scope];
+  return withStatsLock(() => {
+    const stats = readStats(statsPath);
+    stats.scopes[scope] = (stats.scopes[scope] ?? 0) + n;
+    writeStats(statsPath, stats);
+    return stats.scopes[scope];
+  });
 }
 
 /** Read a scope's current write count without modifying (0 if never written). */
@@ -107,11 +136,40 @@ export function getWriteCount(scope: string, cfg?: Partial<ActivityCounterConfig
 }
 
 /** Reset one scope's counter after its successful dream/distill (leaves other scopes untouched). */
-export function resetWriteCount(scope: string, cfg?: Partial<ActivityCounterConfig>): void {
+export async function resetWriteCount(scope: string, cfg?: Partial<ActivityCounterConfig>): Promise<void> {
   const { statsPath } = resolveConfig(cfg);
-  const stats = readStats(statsPath);
-  delete stats.scopes[scope];
-  writeStats(statsPath, stats);
+  await withStatsLock(() => {
+    const stats = readStats(statsPath);
+    delete stats.scopes[scope];
+    writeStats(statsPath, stats);
+  });
+}
+
+/**
+ * Remove every scope entry matching `predicate` in one read-modify-write (one lock
+ * acquisition, one atomic file replace). Returns the removed scope names.
+ *
+ * dream --auto 用它把 transcript scope（原文层，不参与巩固——shared-behaviors §5.3）
+ * 从计数文件里整体清扫，含未达标条目：listScopesAboveThreshold 只能看到达标的，
+ * 而未达标的 transcript 条目会让 stats 文件无限膨胀（历史会话只增不减）。
+ */
+export async function pruneWriteCounts(
+  predicate: (scope: string) => boolean,
+  cfg?: Partial<ActivityCounterConfig>,
+): Promise<string[]> {
+  const { statsPath } = resolveConfig(cfg);
+  return withStatsLock(() => {
+    const stats = readStats(statsPath);
+    const removed: string[] = [];
+    for (const scope of Object.keys(stats.scopes)) {
+      if (predicate(scope)) {
+        delete stats.scopes[scope];
+        removed.push(scope);
+      }
+    }
+    if (removed.length > 0) writeStats(statsPath, stats);
+    return removed;
+  });
 }
 
 /** Scopes whose write count is at or above `threshold` — the dream scheduler's work list. */

package/src/age-label.ts

@@ -0,0 +1,29 @@
+/**
+ * Relative age labels for rendered output.
+ *
+ * Why: a model asked to do date arithmetic on `2026-08-03` will sometimes get it
+ * wrong, and "how long ago" is exactly what decides whether a memory is still
+ * worth raising. So every rendered date carries a whole-day age next to it and
+ * nobody downstream has to subtract. (Borrowed from HKUDS/DeepTutor
+ * `memory/recall.py` — "days_ago rather than an ISO timestamp", 2026-08-17.)
+ *
+ * A future stamp (clock skew on an imported record) reads as today, not as a
+ * negative age. Unusable stamps render as "-" instead of a fabricated number.
+ */
+
+const DAY_MS = 86_400_000;
+
+export const AGE_UNKNOWN = "-";
+
+export function formatAgeLabel(timestampMs: number | null | undefined, now: number = Date.now()): string {
+  if (!timestampMs || !Number.isFinite(timestampMs)) return AGE_UNKNOWN;
+  const days = Math.floor((now - timestampMs) / DAY_MS);
+  return `${Math.max(0, days)}d`;
+}
+
+export function formatIsoAgeLabel(iso: string | null | undefined, now: number = Date.now()): string {
+  if (!iso) return AGE_UNKNOWN;
+  const parsed = Date.parse(iso);
+  if (Number.isNaN(parsed)) return AGE_UNKNOWN;
+  return formatAgeLabel(parsed, now);
+}

package/src/audit-log.ts

@@ -21,6 +21,31 @@ export type AuditOperation =
   | "cascade_forget"
   | "reject";
 
+/**
+ * Which revision of a memory a retrieval actually served.
+ *
+ * A `retrieve` row used to record only the query and a hit count, which cannot answer the
+ * question the audit log exists for: when an agent acted on recalled memory, *what did it
+ * read*? Memories are versioned in place — `archiveBeliefVersion` keeps the canonical id
+ * and bumps `evolution.version`, so "memory X was retrieved" is ambiguous across a belief
+ * change. Recording the revision alongside the id makes a past answer reconstructable.
+ *
+ * Field names are short because retrieval is by far the highest-frequency audited
+ * operation and `audit.jsonl` has no rotation.
+ */
+export interface RetrievedRevision {
+  /** First 8 chars of the memory id — enough to join against the store. */
+  id: string;
+  /** `evolution.version` at the moment it was served. */
+  rev: number;
+  /** `evolution.status`: active / superseded / archived / consolidated / pending_review. */
+  st: string;
+  /** `boundary.layer` — durable vs evidence decides how much authority the hit carried. */
+  ly?: string;
+  /** `boundary.authority` — where the content originally came from. */
+  au?: string;
+}
+
 export interface AuditEntry {
   timestamp: string; // ISO 8601
   operation: AuditOperation;
@@ -28,8 +53,18 @@ export interface AuditEntry {
   memoryId?: string;
   actor: string; // "manual" | "agent" | "api" | "system"
   details?: string; // brief context (<=200 chars)
+  /** Revision + provenance of each served result. Capped — see `retrievedTotal`. */
+  retrieved?: RetrievedRevision[];
+  /**
+   * Total results served. Present only when it exceeds `retrieved.length`, so a truncated
+   * list is always visibly truncated rather than silently short.
+   */
+  retrievedTotal?: number;
 }
 
+/** Upper bound on `retrieved` entries per row, keeping line size bounded. */
+export const AUDIT_RETRIEVED_CAP = 10;
+
 export interface AuditLogger {
   log(entry: Omit<AuditEntry, "timestamp">): void;
   /** Read recent entries (newest first) */

package/src/auto-gc.ts

@@ -14,7 +14,7 @@ import {
   parseEvolution,
   computeDecayScore,
   computeUsageAdjustedDecayScore,
-  buildArchivedMetadata,
+  patchEvolutionOnMeta,
   isActiveMemory,
 } from "./memory-evolution.js";
 import { loadRetentionPolicy, shouldArchiveByPolicy } from "./retention-policy.js";
@@ -23,6 +23,7 @@ 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";
+import { logInfo } from "./stderr-log.js";
 
 // ---------------------------------------------------------------------------
 // Config
@@ -54,6 +55,7 @@ export const DEFAULT_AUTO_GC_CONFIG: AutoGcConfig = {
 // ---------------------------------------------------------------------------
 
 let lastGcTimestamp = 0;
+let lastVersionGroupRepairTimestamp = 0;
 
 // ---------------------------------------------------------------------------
 // Core
@@ -64,6 +66,7 @@ export interface GcResult {
   reason?: string;
   archivedCount: number;
   totalChecked: number;
+  dissolvedVersionGroups: number;
 }
 
 /**
@@ -85,38 +88,70 @@ export async function maybeRunGc(
   const stats = await store.stats();
   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 };
-  }
+  // Singleton version-group repair has its own persistent throttle. It must not be
+  // hidden behind minMemoryCount: a small store can lose one member of a pair too.
+  // Reuse the configured maintenance interval, but keep a separate timestamp so a
+  // repair-only pass does not postpone a later archive pass (or vice versa).
+  const repairStampPath = lockPathForKey("version-group-repair-last");
+  const lastRepair = Math.max(
+    lastVersionGroupRepairTimestamp,
+    getLastDistillTime({ lockPath: repairStampPath }),
+  );
+  const repairDue = totalMemories > 0
+    && (Date.now() - lastRepair) / 3_600_000 >= config.minHoursSinceLastGc;
 
-  // 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.
+  // Archive GC retains its existing count and time gates. P0-1: the time throttle
+  // is cross-process, using the shared gc-last marker in addition to process state.
   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 };
+  const archiveSkipReason = totalMemories < config.minMemoryCount
+    ? "below_memory_threshold"
+    : hoursSinceLastGc < config.minHoursSinceLastGc
+      ? "too_soon"
+      : undefined;
+
+  // Nothing is due: preserve the old fast no-op path without taking a run lock.
+  if (!repairDue && archiveSkipReason) {
+    return { triggered: false, reason: archiveSkipReason, archivedCount: 0, totalChecked: 0, dissolvedVersionGroups: 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 };
+    return { triggered: false, reason: "locked_by_another_process", archivedCount: 0, totalChecked: 0, dissolvedVersionGroups: 0 };
   }
 
-  // All conditions met — run GC
-  lastGcTimestamp = Date.now(); // in-process immediate throttle
-
   try {
+    let dissolvedVersionGroups = 0;
+    if (repairDue) {
+      dissolvedVersionGroups = await store.repairSingletonVersionGroups();
+      lastVersionGroupRepairTimestamp = Date.now();
+      stampLock({ lockPath: repairStampPath });
+      if (dissolvedVersionGroups > 0) {
+        logInfo(`[INFO] Auto-GC dissolved ${dissolvedVersionGroups} singleton version group(s)`);
+      }
+    }
+
+    // A repair-only pass is still useful maintenance, but `triggered` continues to
+    // mean that the archive scan ran so existing callers keep their old semantics.
+    if (archiveSkipReason) {
+      return {
+        triggered: false,
+        reason: archiveSkipReason,
+        archivedCount: 0,
+        totalChecked: 0,
+        dissolvedVersionGroups,
+      };
+    }
+
+    lastGcTimestamp = Date.now(); // in-process immediate throttle
     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 };
+    return { triggered: true, archivedCount, totalChecked, dissolvedVersionGroups };
   } finally {
     releaseLock(gcRunLock);
   }
@@ -169,13 +204,47 @@ async function runGcScan(
 
   // Pass 2: archive sweep.
   const useUsageAdjustedDecay = envConfig.usageDecay() && isUsageSignalActive();
+
+  // 2026-08-14 批量化（dream 写爆库根治）：候选先收集，页末统一一次 patchMetadataBatch
+  // —— 原逐条 update 每行一个 LanceDB commit（每天最多 100 个 manifest），现在页数级。
+  // activeCounts 仍在"选中"时即刻预递减，保持旧路径"逐行归档、后续行的 retention 判断
+  // 看到已减的 activeCount"语义（互审 C6）。selected 与 archivedCount 分开：前者控
+  // maxArchivePerRun 上限（选中即占额度），后者按批量写的实际写入数累计。
+  let selected = 0;
+  let pendingArchive: Array<{ id: string; ageDays: number }> = [];
+  const flushArchiveBatch = async (): Promise<void> => {
+    if (pendingArchive.length === 0) return;
+    const batch = pendingArchive;
+    pendingArchive = [];
+    const written = await store.patchMetadataBatch(
+      batch.map(({ id }) => ({
+        id,
+        patchFn: (meta: Record<string, unknown>) => patchEvolutionOnMeta(meta, { status: "archived" }),
+      })),
+    );
+    archivedCount += written;
+    // F-1: Audit log — record archive operations (silent on failure)。按提交批记录：
+    // 批内个别行被并发删除时 audit 会多记一条，best-effort 语义可接受（旧路径里
+    // update 失败是直接炸掉整个 GC，连 audit 都到不了）。
+    for (const { id, ageDays } of batch) {
+      try {
+        auditLogger?.log({
+          operation: "archive",
+          memoryId: id,
+          actor: "system",
+          details: `auto-gc: age=${Math.floor(ageDays)}d`,
+        });
+      } catch { /* Audit must never block GC */ }
+    }
+  };
+
   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;
+    if (selected >= config.maxArchivePerRun) break outer;
 
     // Only archive active memories
     if (!isActiveMemory(entry.metadata)) continue;
@@ -215,19 +284,10 @@ async function runGcScan(
     }
 
     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)
+      pendingArchive.push({ id: entry.id, ageDays });
+      selected++;
+      // Decrement active count for the scope（预递减：选中即视为不再 active，
+      // 同页后续行的 retention 判断与旧逐行路径看到同样的计数）
       const scope = entry.scope ?? "";
       const prev = activeCounts.get(scope) ?? 0;
       if (prev > 0) {
@@ -236,9 +296,14 @@ async function runGcScan(
     }
   }
 
+    // 页末提交本页候选（含 break outer 前最后一页扫过的部分）
+    await flushArchiveBatch();
     if (page.length < GC_PAGE_SIZE) break;
   }
 
+  // break outer 跳出时 pendingArchive 可能还有未提交的候选 —— 上限命中不弃单（互审 C6）
+  await flushArchiveBatch();
+
   return { archivedCount, totalChecked };
 }
 
@@ -248,9 +313,11 @@ async function runGcScan(
  */
 export function resetGcTimestamp(): void {
   lastGcTimestamp = 0;
+  lastVersionGroupRepairTimestamp = 0;
   try {
     releaseLock({ lockPath: lockPathForKey("gc-last") });
     releaseLock({ lockPath: lockPathForKey("gc-run") });
+    releaseLock({ lockPath: lockPathForKey("version-group-repair-last") });
   } catch {
     /* ignore — nothing to clear */
   }