recallnest 2.3.0 → 2.5.4

package/src/consolidation-engine.ts

@@ -17,7 +17,9 @@
  * LLM-free — deterministic clustering and merge only.
  */
 
-import type { MemoryEntry, MemorySearchResult, MemoryStore } from "./store.js";
+import type { MemoryEntry, MemorySearchResult } from "./store.js";
+import { deterministicId } from "./store.js";
+import type { MemoryStorePort } from "./memory-store-port.js";
 import { createVersionGroup } from "./version-manager.js";
 import { isActiveMemory, parseEvolution, buildSupersedeMetadata, buildConsolidatedMetadata, patchEvolution } from "./memory-evolution.js";
 import { cosineSimilarity } from "./multi-vector.js";
@@ -35,12 +37,22 @@ export interface ConsolidationConfig {
   mergeThreshold: number;
   /** Maximum entries to scan per consolidation run (default 500) */
   maxEntriesPerRun: number;
+  /**
+   * KG evidence: triple-set Jaccard at/above this merges a grey-zone pair
+   * (vector sim between clusterThreshold and mergeThreshold). Default 0.5 —
+   * provisional until calibrated on production data (plan Q3).
+   */
+  tripleJaccardThreshold?: number;
+  /** KG evidence: both sides need at least this many triples to qualify (default 2) */
+  minTriplesForEvidence?: number;
 }
 
 export const DEFAULT_CONSOLIDATION_CONFIG: ConsolidationConfig = {
   clusterThreshold: 0.82,
   mergeThreshold: 0.92,
   maxEntriesPerRun: 500,
+  tripleJaccardThreshold: 0.5,
+  minTriplesForEvidence: 2,
 };
 
 export interface ConflictEvent {
@@ -54,10 +66,52 @@ export interface ConsolidationResult {
   clustersFound: number;
   mergedCount: number;
   relationsAdded: number;
+  /** Of mergedCount, how many were below mergeThreshold and merged on KG triple evidence */
+  tripleEvidenceMerges: number;
   conflictsDetected: ConflictEvent[];
   scope: string;
 }
 
+// ---------------------------------------------------------------------------
+// KG evidence source (duck-typed subset of KGStore)
+// ---------------------------------------------------------------------------
+
+/** The two triple fields consolidation needs — structurally satisfied by KGTriple. */
+export interface ConsolidationTripleEvidence {
+  id: string;
+  mention_count: number;
+}
+
+export interface ConsolidationKGSource {
+  getTriplesBySourceMemories(memoryIds: string[]): Promise<Map<string, ConsolidationTripleEvidence[]>>;
+}
+
+/**
+ * Jaccard overlap of two triple-id sets. Below `minSize` on either side the
+ * evidence is considered too weak and 0 is returned (a single shared triple
+ * must not merge two memories on its own).
+ */
+export function tripleJaccard(
+  a: ReadonlySet<string> | undefined,
+  b: ReadonlySet<string> | undefined,
+  minSize = 2,
+): number {
+  if (!a || !b || a.size < minSize || b.size < minSize) return 0;
+  let inter = 0;
+  for (const x of a) if (b.has(x)) inter++;
+  return inter / (a.size + b.size - inter);
+}
+
+/**
+ * Mention-frequency boost in canonical selection: tie-breaker ONLY, never an
+ * override of a clear canonicalScore gap (an entry with one hot triple must
+ * not demote a substantially more important memory to consolidated status).
+ * α=0.06 keeps the boost differentiating (m=1 → 1.042, m=9 → 1.138) while the
+ * 1.1 cap bounds the maximum flip at ~10% of the base score — effectively ties.
+ */
+const MENTION_ALPHA = 0.06;
+const MENTION_BOOST_CAP = 1.1;
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -108,7 +162,7 @@ export function detectHeuristicContradiction(textA: string, textB: string): bool
 // Store interface (duck-typed to avoid hard dependency)
 // ---------------------------------------------------------------------------
 
-type ConsolidationStore = Pick<MemoryStore, "list" | "getById" | "vectorSearch" | "update">;
+type ConsolidationStore = Pick<MemoryStorePort, "list" | "getById" | "vectorSearch" | "update">;
 
 // ---------------------------------------------------------------------------
 // Engine
@@ -118,17 +172,25 @@ export class ConsolidationEngine {
   constructor(
     private store: ConsolidationStore,
     private config: ConsolidationConfig = DEFAULT_CONSOLIDATION_CONFIG,
+    /** Optional KG evidence source — absent = pure vector behavior, unchanged */
+    private kgSource: ConsolidationKGSource | null = null,
   ) {}
 
   async run(scope: string): Promise<ConsolidationResult> {
-    const { clusterThreshold, mergeThreshold, maxEntriesPerRun } = this.config;
+    const {
+      clusterThreshold,
+      mergeThreshold,
+      maxEntriesPerRun,
+      tripleJaccardThreshold = 0.5,
+      minTriplesForEvidence = 2,
+    } = this.config;
 
     // 1. Fetch entries in scope
     const entries = await this.store.list([scope], undefined, maxEntriesPerRun, 0);
     const active = entries.filter(isActive);
 
     if (active.length === 0) {
-      return { originalCount: 0, clustersFound: 0, mergedCount: 0, relationsAdded: 0, conflictsDetected: [], scope };
+      return { originalCount: 0, clustersFound: 0, mergedCount: 0, relationsAdded: 0, tripleEvidenceMerges: 0, conflictsDetected: [], scope };
     }
 
     // 2. Group by category
@@ -142,6 +204,7 @@ export class ConsolidationEngine {
     let clustersFound = 0;
     let mergedCount = 0;
     let relationsAdded = 0;
+    let tripleEvidenceMerges = 0;
     const conflictsDetected: ConflictEvent[] = [];
 
     // 3. Cluster within each category
@@ -183,8 +246,27 @@ export class ConsolidationEngine {
         }
         if (memberEntries.length < 2) continue;
 
-        // Determine canonical: highest canonicalScore
-        const sorted = [...memberEntries].sort((a, b) => canonicalScore(b) - canonicalScore(a));
+        // KG triple evidence for this cluster (single batch query; best-effort —
+        // on failure consolidation proceeds vector-only)
+        const tripleIdsByMember = new Map<string, Set<string>>();
+        const maxMentionByMember = new Map<string, number>();
+        if (this.kgSource) {
+          try {
+            const triplesByMember = await this.kgSource.getTriplesBySourceMemories(memberEntries.map(e => e.id));
+            for (const [mid, triples] of triplesByMember) {
+              tripleIdsByMember.set(mid, new Set(triples.map(t => t.id)));
+              maxMentionByMember.set(mid, triples.reduce((m, t) => Math.max(m, t.mention_count), 0));
+            }
+          } catch { /* KG evidence is best-effort */ }
+        }
+
+        // Determine canonical: highest canonicalScore, frequency-boosted when
+        // KG evidence exists (memories carrying often-mentioned facts win ties)
+        const mentionBoost = (e: MemoryEntry) =>
+          Math.min(MENTION_BOOST_CAP, 1 + MENTION_ALPHA * Math.log((maxMentionByMember.get(e.id) ?? 0) + 1));
+        const sorted = [...memberEntries].sort(
+          (a, b) => canonicalScore(b) * mentionBoost(b) - canonicalScore(a) * mentionBoost(a),
+        );
         const canonical = sorted[0];
 
         if (!canonical.vector?.length) continue;
@@ -199,7 +281,16 @@ export class ConsolidationEngine {
         for (const member of sorted.slice(1)) {
           const sim = scoreMap.get(member.id) ?? clusterThreshold;
 
-          if (sim >= mergeThreshold) {
+          // Second evidence source: two memories whose extracted fact sets
+          // overlap heavily are duplicates even when vector sim sits in the
+          // grey zone (the "pairwise near-duplicates" the 0.92 bar misses).
+          const jaccard = tripleJaccard(
+            tripleIdsByMember.get(canonical.id),
+            tripleIdsByMember.get(member.id),
+            minTriplesForEvidence,
+          );
+
+          if (sim >= mergeThreshold || jaccard >= tripleJaccardThreshold) {
             // Tier 3.3: Version coexistence — both stay but grouped.
             await createVersionGroup(this.store, canonical, member, scope);
             // C-1: Also mark the weaker entry as consolidated via evolution metadata
@@ -214,6 +305,7 @@ export class ConsolidationEngine {
               await this.store.update(canonical.id, { metadata: updatedCanon }, [scope]);
             }
             mergedCount++;
+            if (sim < mergeThreshold) tripleEvidenceMerges++;
           } else {
             // Link: add clustered_with relation
             const memberMeta = parseMetadata(member);
@@ -245,7 +337,7 @@ export class ConsolidationEngine {
       }
     }
 
-    return { originalCount: active.length, clustersFound, mergedCount, relationsAdded, conflictsDetected, scope };
+    return { originalCount: active.length, clustersFound, mergedCount, relationsAdded, tripleEvidenceMerges, conflictsDetected, scope };
   }
 }
 
@@ -278,7 +370,7 @@ export async function clusterAndConsolidate(params: {
   entries: MemoryEntry[];
   embedder: Pick<Embedder, "embedPassage">;
   llm: LLMClient;
-  store: Pick<MemoryStore, "store" | "update">;
+  store: Pick<MemoryStorePort, "store" | "update">;
   scope: string;
   /** Minimum cluster size to trigger consolidation (default: 3) */
   minClusterSize?: number;
@@ -400,8 +492,13 @@ export async function clusterAndConsolidate(params: {
     // Embed the insight text
     const insightVector = await params.embedder.embedPassage(insight);
 
-    // Store the insight as a new memory
+    // Store the insight as a new memory. P0-2/P1-2: derive a deterministic id from the
+    // (sorted) source member ids so re-running dream/consolidate on the same cluster
+    // upserts the same insight row instead of appending a near-duplicate each run
+    // (the highest-frequency dup-id source). Cross-run stable because sourceIds are stable.
+    const sortedSourceIds = cluster.map(m => m.id).slice().sort();
     const insightEntry = await store.store({
+      id: deterministicId(scope, `cluster-insight:${sortedSourceIds.join(",")}`),
       text: insight,
       vector: insightVector,
       category: bestCat,
@@ -444,6 +541,7 @@ export async function clusterAndConsolidate(params: {
         const patternImportance = Math.min(maxImportance + 0.1, 1.0);
         const patternVector = await params.embedder.embedPassage(patternText);
         const patternEntry = await store.store({
+          id: deterministicId(scope, `cluster-pattern:${sortedSourceIds.join(",")}`),
           text: patternText,
           vector: patternVector,
           category: "patterns",
@@ -492,7 +590,7 @@ export function formatConsolidationResult(result: ConsolidationResult): string {
     `Consolidation complete for scope: ${result.scope}`,
     `Scanned: ${result.originalCount} active entries`,
     `Clusters found: ${result.clustersFound}`,
-    `Merged (versioned): ${result.mergedCount}`,
+    `Merged (versioned): ${result.mergedCount}${result.tripleEvidenceMerges > 0 ? ` (${result.tripleEvidenceMerges} on triple evidence)` : ""}`,
     `Relations added: ${result.relationsAdded}`,
     `Conflicts detected: ${result.conflictsDetected.length}`,
   ];

package/src/context-composer.ts

@@ -1,4 +1,5 @@
 import { listPinAssets, type PinAsset } from "./memory-assets.js";
+import * as envConfig from "./env-config.js";
 import { buildStableContextSections } from "./context-composer-stable.js";
 import {
   buildAssociativeNestEntityFallbackQuery,
@@ -32,6 +33,8 @@ type ResumeCategory = "profile" | "preferences" | "entities" | "patterns" | "cas
 
 interface ResumeRetriever {
   retrieve(context: RetrievalContext): Promise<RetrievalResult[]>;
+  /** Optional: 影子记录 resume reconstruction 引用的记忆（injection-vs-use）。未实现则 no-op。 */
+  recordReconstructionUsage?(citedIds: string[]): Promise<void>;
 }
 
 interface CheckpointLookup {
@@ -467,7 +470,7 @@ export async function composeResumeContext(
   let reconstructedContext: string | undefined;
   let reconstructionConfidence: number | undefined;
   let reconstructionContradictions: Array<{ memoryIds: [string, string]; description: string }> | undefined;
-  const constructiveFlag = process.env.RECALLNEST_CONSTRUCTIVE_RETRIEVAL === "true";
+  const constructiveFlag = envConfig.constructiveRetrieval();
   if (constructiveFlag && deps.llm?.isAvailable?.()) {
     const allReconResults = [...profileResults, ...preferenceResults, ...entityResults, ...filteredPatterns, ...filteredCases];
     if (allReconResults.length >= 3) {
@@ -489,6 +492,10 @@ export async function composeResumeContext(
         if (recon.contradictions.length > 0) {
           reconstructionContradictions = recon.contradictions;
         }
+        // Shadow usage：resume reconstruction 真正引用的记忆记 use 计数（不动 ranking/forget）。
+        if (recon.sources.length > 0) {
+          await deps.retriever.recordReconstructionUsage?.(recon.sources.map(s => s.id));
+        }
       } catch { /* silent fallback */ }
     }
   }

package/src/data-checkup.ts

@@ -16,6 +16,7 @@ import type { MemoryEntry, MemoryStore } from "./store.js";
 import { resolveTier, type MemoryTier } from "./decay-engine.js";
 import { measureInterferenceDensity } from "./interference-detector.js";
 import { readHeartbeats, checkSourceStaleness, formatAge } from "./source-heartbeat.js";
+import { deriveUsageStatus, isUsageSignalActive, type UsageStatus } from "./usage-tracker.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -30,6 +31,8 @@ export interface CheckResult {
 export interface CheckupReport {
   checks: CheckResult[];
   totalEntries: number;
+  /** Total entries in store; when > totalEntries, only the most recent were scanned. */
+  totalAvailable: number;
   timestamp: string;
 }
 
@@ -39,15 +42,33 @@ export interface CheckupReport {
 
 /** Check 1: All vectors should have the same dimension. */
 function checkVectorDimensions(entries: MemoryEntry[]): CheckResult {
+  // 只对真正取到向量的条目判维度一致性;取不到向量的(dim=0)单独计数后跳过——
+  // 否则会把"未补到向量"误报成"维度不一致",或把"全 0 维空向量"假报成健康。
   const dims = new Map<number, number>(); // dim → count
+  let missingVectors = 0;
   for (const e of entries) {
     const d = e.vector?.length ?? 0;
+    if (d === 0) { missingVectors++; continue; }
     dims.set(d, (dims.get(d) ?? 0) + 1);
   }
 
-  if (dims.size <= 1) {
+  const withVectors = entries.length - missingVectors;
+  if (entries.length === 0) {
+    return { name: "vector_dimensions", status: "ok", detail: "No entries to check" };
+  }
+  if (withVectors === 0) {
+    return {
+      name: "vector_dimensions",
+      status: "warning",
+      detail: `No retrievable vectors among ${entries.length} entries — dimension consistency not verified`,
+    };
+  }
+
+  const suffix = missingVectors > 0 ? ` (${missingVectors} without retrievable vector, skipped)` : "";
+
+  if (dims.size === 1) {
     const dim = dims.keys().next().value ?? 0;
-    return { name: "vector_dimensions", status: "ok", detail: `All ${entries.length} entries have dimension ${dim}` };
+    return { name: "vector_dimensions", status: "ok", detail: `All ${withVectors} vectors have dimension ${dim}${suffix}` };
   }
 
   const sorted = [...dims.entries()].sort((a, b) => b[1] - a[1]);
@@ -56,7 +77,7 @@ function checkVectorDimensions(entries: MemoryEntry[]): CheckResult {
   return {
     name: "vector_dimensions",
     status: "error",
-    detail: `${mismatched} entries have wrong dimension (expected ${expected}): ${sorted.map(([d, c]) => `dim=${d}: ${c}`).join(", ")}`,
+    detail: `${mismatched} entries have wrong dimension (expected ${expected}): ${sorted.map(([d, c]) => `dim=${d}: ${c}`).join(", ")}${suffix}`,
   };
 }
 
@@ -216,15 +237,78 @@ function checkInterferenceDensity(entries: MemoryEntry[]): CheckResult {
 // Main
 // ---------------------------------------------------------------------------
 
+/** Check 8 (P0 B-1 观察): usage 四档分布 — injection-vs-use 影子统计的离线观察口。
+ *  纯报告,不接任何决策;cold = 被反复 surface(accessCount≥6)却从未被
+ *  reconstruction 引用,是第二阶段 decay 联动前要先观察校准的核心对象。 */
+function checkUsageDistribution(entries: MemoryEntry[]): CheckResult {
+  // use 信号未采集时(reconstruction flag 关),useCount 恒零 → "cold" 全是假阳性。
+  // 如实报告信号缺失,不输出不可解释的判定。
+  if (!isUsageSignalActive()) {
+    return {
+      name: "usage_distribution",
+      status: "ok",
+      detail: "use signal inactive (RECALLNEST_CONSTRUCTIVE_RETRIEVAL off) — useCount 无写入路径,cold/warm/hot 不可判,统计跳过。该 flag 因合成召回缺失被 Alice 主动关闭(2026-06-11),usage 线搁置中。",
+    };
+  }
+
+  const counts: Record<UsageStatus, number> = { unused: 0, cold: 0, warm: 0, hot: 0 };
+  const coldSamples: Array<{ id: string; injection: number; ageDays: number; scope: string }> = [];
+  const now = Date.now();
+
+  for (const e of entries) {
+    const status = deriveUsageStatus(e);
+    counts[status]++;
+    if (status === "cold") {
+      let injection = 0;
+      try {
+        const meta = JSON.parse(e.metadata || "{}") as Record<string, unknown>;
+        injection = typeof meta.accessCount === "number" ? meta.accessCount : 0;
+      } catch { /* keep 0 */ }
+      coldSamples.push({
+        id: e.id.slice(0, 8),
+        injection,
+        ageDays: Math.floor((now - e.timestamp) / 86_400_000),
+        scope: e.scope || "(none)",
+      });
+    }
+  }
+
+  const total = entries.length;
+  const coldPct = total > 0 ? (counts.cold / total) * 100 : 0;
+  const top = coldSamples
+    .sort((a, b) => b.injection - a.injection)
+    .slice(0, 20)
+    .map(s => `${s.id}(inj=${s.injection}, ${s.ageDays}d, ${s.scope})`)
+    .join(", ");
+
+  return {
+    name: "usage_distribution",
+    status: coldPct > 10 ? "warning" : "ok",
+    detail:
+      `unused=${counts.unused} cold=${counts.cold} (${coldPct.toFixed(1)}%) ` +
+      `warm=${counts.warm} hot=${counts.hot}` +
+      (coldSamples.length > 0 ? `; cold top-${Math.min(20, coldSamples.length)}: ${top}` : ""),
+  };
+}
+
 export interface CheckupDeps {
-  store: Pick<MemoryStore, "list" | "stats">;
+  store: Pick<MemoryStore, "list" | "stats" | "getVectors">;
   openConflictCount: number;
   /** Optional override path for source-heartbeat.json (used in tests). */
   heartbeatPath?: string;
 }
 
 export async function runDataCheckup(deps: CheckupDeps): Promise<CheckupReport> {
-  const entries = await deps.store.list(undefined, undefined, 10000, 0);
+  const SCAN_LIMIT = 10000;
+  const listed = await deps.store.list(undefined, undefined, SCAN_LIMIT, 0);
+
+  // list() 为性能不返回向量(vector: []);维度/干扰检查靠向量,否则把"全 0 维"
+  // 误判成健康、干扰分析永远"样本不足"。补回真实向量再检查。
+  const vectorMap = await deps.store.getVectors(listed.map(e => e.id));
+  const entries = listed.map(e => ({ ...e, vector: vectorMap.get(e.id) ?? [] }));
+
+  // 截断披露:库总量 > 已扫,说明只体检了最近 SCAN_LIMIT 条。
+  const totalAvailable = (await deps.store.stats()).totalCount;
 
   return {
     checks: [
@@ -235,16 +319,21 @@ export async function runDataCheckup(deps: CheckupDeps): Promise<CheckupReport>
       checkVersionGroups(entries),
       checkSourceHealth(deps.heartbeatPath),
       checkInterferenceDensity(entries),
+      checkUsageDistribution(entries),
     ],
     totalEntries: entries.length,
+    totalAvailable,
     timestamp: new Date().toISOString(),
   };
 }
 
 export function formatCheckupReport(report: CheckupReport): string {
+  const truncationNote = report.totalAvailable > report.totalEntries
+    ? ` (of ${report.totalAvailable} total — only the most recent ${report.totalEntries} analyzed)`
+    : "";
   const lines = [
     `Data Checkup Report (${report.timestamp})`,
-    `Total entries scanned: ${report.totalEntries}`,
+    `Total entries scanned: ${report.totalEntries}${truncationNote}`,
     "",
   ];
 

package/src/distill-lock.ts

@@ -18,7 +18,9 @@ import {
   utimesSync,
   existsSync,
 } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
 import { join, dirname } from "node:path";
+import * as envConfig from "./env-config.js";
 
 // ---------------------------------------------------------------------------
 // Config
@@ -34,7 +36,7 @@ export interface DistillLockConfig {
 }
 
 export const DEFAULT_DISTILL_LOCK_CONFIG: DistillLockConfig = {
-  lockPath: join(process.env.RECALLNEST_DATA_DIR || "data", "distill.lock"),
+  lockPath: join(envConfig.dataDir(), "distill.lock"),
   expireMs: 3_600_000,
   minCheckpoints: 3,
 };
@@ -56,6 +58,17 @@ function isPidAlive(pid: number): boolean {
   }
 }
 
+// P2: in-process record of the ownership token we wrote into each lock file we hold.
+// releaseLock only removes a lock whose on-disk token still matches — so if our lock
+// expired mid-run and another process legitimately reclaimed it, our finally-release
+// won't delete the new owner's lock (which would break mutual exclusion).
+const heldTokens = new Map<string, string>();
+
+/** Parse the PID prefix from a lock file body (`<pid>` legacy or `<pid>:<token>`). */
+function parsePid(content: string): number {
+  return parseInt((content.split(":")[0] ?? "").trim(), 10);
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -66,29 +79,75 @@ function isPidAlive(pid: number): boolean {
  */
 export function acquireLock(cfg?: Partial<DistillLockConfig>): boolean {
   const { lockPath, expireMs } = resolveConfig(cfg);
+  mkdirSync(dirname(lockPath), { recursive: true });
 
-  if (existsSync(lockPath)) {
-    const existingPid = parseInt(readFileSync(lockPath, "utf-8").trim(), 10);
-    const mtime = statSync(lockPath).mtimeMs;
-    const expired = Date.now() - mtime > expireMs;
+  // Fast path: atomic exclusive create. On POSIX the O_EXCL ("wx") open wins the
+  // cross-process race — only one of N processes creating the same lock succeeds.
+  // This closes the check-then-write TOCTOU the previous existsSync+writeFileSync
+  // form had (two processes could both see "no lock" then both write); the P0-1
+  // store-write lock relies on acquisition being truly exclusive.
+  if (tryExclusiveCreate(lockPath)) return true;
 
-    if (!isNaN(existingPid) && isPidAlive(existingPid) && !expired) {
-      return false;
-    }
-    // PID dead or lock expired — overwrite
+  // Lock file exists — decide whether it is reclaimable (dead holder or expired).
+  let existingPid = NaN;
+  let mtime = 0;
+  try {
+    existingPid = parsePid(readFileSync(lockPath, "utf-8"));
+    mtime = statSync(lockPath).mtimeMs;
+  } catch {
+    // Holder released between our failed create and this read — retry the create.
+    return tryExclusiveCreate(lockPath);
+  }
+  const expired = Date.now() - mtime > expireMs;
+  if (!isNaN(existingPid) && isPidAlive(existingPid) && !expired) {
+    return false; // held by a live process, not expired
   }
 
-  mkdirSync(dirname(lockPath), { recursive: true });
-  writeFileSync(lockPath, String(process.pid), "utf-8");
-  return true;
+  // Reclaim a stale lock: remove it, then re-create atomically. If a competing
+  // process reclaims first, our O_EXCL create fails and we concede the race.
+  try {
+    unlinkSync(lockPath);
+  } catch {
+    /* already gone — fall through to the atomic create */
+  }
+  return tryExclusiveCreate(lockPath);
+}
+
+/**
+ * Atomic O_EXCL create of the lock file. Writes a unique ownership token (`<pid>:<uuid>`)
+ * and records it so releaseLock can verify we still own the lock. false on EEXIST.
+ */
+function tryExclusiveCreate(lockPath: string): boolean {
+  const token = `${process.pid}:${randomUUID()}`;
+  try {
+    writeFileSync(lockPath, token, { encoding: "utf-8", flag: "wx" });
+    heldTokens.set(lockPath, token);
+    return true;
+  } catch (err) {
+    if ((err as { code?: unknown }).code === "EEXIST") return false;
+    throw err;
+  }
 }
 
-/** Release the distill lock by removing the lock file. */
+/**
+ * Release the distill lock. If we hold a known ownership token for this path, only
+ * remove the file when its on-disk token still matches ours — otherwise our lock was
+ * expired and reclaimed by another process, and deleting would evict the new owner.
+ * When we hold no token (e.g. a direct caller/test-written lock) fall back to removing.
+ */
 export function releaseLock(cfg?: Partial<DistillLockConfig>): void {
   const { lockPath } = resolveConfig(cfg);
-  if (existsSync(lockPath)) {
-    unlinkSync(lockPath);
+  const ourToken = heldTokens.get(lockPath);
+  heldTokens.delete(lockPath);
+  if (!existsSync(lockPath)) return;
+  if (ourToken !== undefined) {
+    try {
+      if (readFileSync(lockPath, "utf-8").trim() !== ourToken) return; // reclaimed by another owner
+    } catch {
+      return;
+    }
   }
+  unlinkSync(lockPath);
 }
 
 /**
@@ -120,3 +179,123 @@ export function getLastDistillTime(cfg?: Partial<DistillLockConfig>): number {
   if (!existsSync(lockPath)) return 0;
   return statSync(lockPath).mtimeMs;
 }
+
+// ---------------------------------------------------------------------------
+// P0-1: Named cross-process locks (store-write + maintenance families)
+//
+// distill-lock was dead code (0 src imports). P0-1 wires it up: one global
+// `store-write` lock serializes every `memories`-table write across the 11
+// mcp-server processes, and scope-keyed maintenance locks (dream/consolidate/
+// distill) + a global gc lock stop redundant concurrent maintenance runs.
+// ---------------------------------------------------------------------------
+
+/** Base directory for named locks. Defaults to <dataDir>/locks; overridable in tests. */
+export function locksDir(lockDir?: string): string {
+  return lockDir ?? join(envConfig.dataDir(), "locks");
+}
+
+/**
+ * Resolve a lock key (e.g. "store-write", "dream-<scope>", "gc-global") to a safe
+ * lock-file path. The key is sanitized for the filesystem and suffixed with a short
+ * hash of the raw key so distinct keys never collide after sanitization/truncation.
+ */
+export function lockPathForKey(key: string, lockDir?: string): string {
+  const safe = key.replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 80);
+  const hash = createHash("sha256").update(key).digest("hex").slice(0, 8);
+  return join(locksDir(lockDir), `${safe}-${hash}.lock`);
+}
+
+export interface WithLockOptions {
+  /** Stale-lock reclaim window in ms (default 600_000 = 10min). */
+  expireMs?: number;
+  /** Override the base lock directory (tests). */
+  lockDir?: string;
+  /** Behavior when another live process holds the lock (default "skip"). */
+  onBusy?: "skip" | "wait";
+  /** For onBusy="wait": total time budget before throwing (default 10_000). */
+  waitTimeoutMs?: number;
+  /** For onBusy="wait": poll interval in ms (default 50). */
+  pollMs?: number;
+}
+
+export type WithLockOutcome<T> =
+  | { ran: true; result: T }
+  | { ran: false; reason: "locked_by_another_process" };
+
+const sleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Run `fn` while holding a named cross-process lock, releasing it afterwards
+ * (even on throw). Maintenance-type writes use onBusy:"skip" — for a personal
+ * store, skipping a redundant dream/consolidate/gc run beats queueing it.
+ */
+export async function withLock<T>(
+  key: string,
+  fn: () => Promise<T>,
+  opts: WithLockOptions = {},
+): Promise<WithLockOutcome<T>> {
+  const lockPath = lockPathForKey(key, opts.lockDir);
+  const lockCfg = { lockPath, expireMs: opts.expireMs ?? 600_000 };
+
+  if (!acquireLock(lockCfg)) {
+    if ((opts.onBusy ?? "skip") === "skip") {
+      return { ran: false, reason: "locked_by_another_process" };
+    }
+    // wait: poll until acquired or the budget is exhausted.
+    const timeoutMs = opts.waitTimeoutMs ?? 10_000;
+    const deadline = Date.now() + timeoutMs;
+    const pollMs = opts.pollMs ?? 50;
+    let acquired = false;
+    while (Date.now() < deadline) {
+      await sleep(pollMs);
+      if (acquireLock(lockCfg)) {
+        acquired = true;
+        break;
+      }
+    }
+    if (!acquired) {
+      throw new Error(`lock '${key}' timed out after ${timeoutMs}ms (held by another process)`);
+    }
+  }
+
+  try {
+    return { ran: true, result: await fn() };
+  } finally {
+    releaseLock(lockCfg);
+  }
+}
+
+/**
+ * Run `fn` under a named write lock, waiting for the lock rather than skipping —
+ * losing a memory write would be data loss. Throws if the lock can't be acquired
+ * within the timeout. Returns fn's result directly. Used by store.upsert/storeBatch
+ * so all `memories`-table writes serialize across the 11 mcp-server processes.
+ */
+export async function withWriteLock<T>(
+  key: string,
+  fn: () => Promise<T>,
+  opts: Omit<WithLockOptions, "onBusy"> = {},
+): Promise<T> {
+  const outcome = await withLock(key, fn, { ...opts, onBusy: "wait" });
+  // onBusy:"wait" resolves to {ran:true} or throws; ran:false is unreachable here.
+  if (!outcome.ran) {
+    throw new Error(`write lock '${key}' unavailable`);
+  }
+  return outcome.result;
+}
+
+/**
+ * Stamp a lock file's mtime to now without releasing it, marking "last completed".
+ * gc (auto-gc.ts) uses this to persist a cross-process throttle timestamp in the
+ * lock file's mtime (getLastDistillTime pattern) so the 24h throttle holds across
+ * processes rather than each process tracking its own module-level timestamp.
+ */
+export function stampLock(cfg?: Partial<DistillLockConfig>): void {
+  const { lockPath } = resolveConfig(cfg);
+  mkdirSync(dirname(lockPath), { recursive: true });
+  // Create-or-overwrite so the mtime becomes now. Unlike releaseLock this leaves the
+  // file in place — it is a persistent "last run" marker (gc's cross-process throttle),
+  // read back via getLastDistillTime.
+  writeFileSync(lockPath, String(process.pid), "utf-8");
+}