recallnest 2.2.1 → 2.5.4

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");
+}

package/src/doctor.ts

@@ -27,6 +27,7 @@ import {
 } from "./memory-schema.js";
 import { collectScopeInventory, type ScopeInventoryReport } from "./scope-inventory.js";
 import { MemoryStore, type MemoryEntry, validateStoragePath } from "./store.js";
+import { readHeartbeats, formatAge } from "./source-heartbeat.js";
 
 interface CheckResult {
   name: string;
@@ -61,6 +62,13 @@ function warn(name: string, message: string, fix?: string): CheckResult {
   return { name, status: "warn", message, fix };
 }
 
+export function describeSecretPresence(
+  value: string | undefined,
+  placeholder: string,
+): string | null {
+  return value && value !== placeholder ? "set" : null;
+}
+
 function summarizeScopeInventoryLayers(report: ScopeInventoryReport): string {
   return report.layers
     .filter((layer) => layer.anomalyCount > 0 || layer.invalidCount > 0)
@@ -322,8 +330,8 @@ export async function runDoctor(options: { ci?: boolean } = {}): Promise<CheckRe
   // 3. .env + JINA_API_KEY
   loadDotEnv();
   const jinaKey = process.env.JINA_API_KEY;
-  if (jinaKey && jinaKey !== "your_jina_api_key_here") {
-    results.push(pass("JINA_API_KEY", `set (${jinaKey.slice(0, 8)}...)`));
+  if (describeSecretPresence(jinaKey, "your_jina_api_key_here")) {
+    results.push(pass("JINA_API_KEY", "set"));
   } else if (options.ci) {
     results.push(warn(
       "JINA_API_KEY",
@@ -508,6 +516,34 @@ export async function runDoctor(options: { ci?: boolean } = {}): Promise<CheckRe
     ));
   }
 
+  // GB-3: Source heartbeat summary
+  try {
+    const heartbeats = readHeartbeats();
+    const sources = Object.values(heartbeats);
+    if (sources.length === 0) {
+      results.push(pass("Source heartbeats", "no connector sources tracked yet"));
+    } else {
+      const summary = sources
+        .map((s) => `${s.source}: ${formatAge(s.lastIngest)}`)
+        .join(", ");
+      const staleCount = sources.filter((s) => {
+        const daysSince = (Date.now() - Date.parse(s.lastIngest)) / 86_400_000;
+        return daysSince > 7;
+      }).length;
+      if (staleCount > 0) {
+        results.push(warn(
+          "Source heartbeats",
+          `${summary} (${staleCount} stale >7d)`,
+          "lm ingest --connector <file>",
+        ));
+      } else {
+        results.push(pass("Source heartbeats", summary));
+      }
+    }
+  } catch {
+    results.push(warn("Source heartbeats", "unable to read heartbeat file"));
+  }
+
   return results;
 }
 

package/src/dream-pipeline.ts

@@ -14,13 +14,15 @@
  * LLM-driven consolidation for semantic-level maintenance.
  */
 
-import type { MemoryStore } from "./store.js";
+import type { MemoryStorePort } from "./memory-store-port.js";
 import type { LLMClient } from "./llm-client.js";
 import type { Embedder } from "./embedder.js";
-import { ConsolidationEngine, clusterAndConsolidate, DEFAULT_CONSOLIDATION_CONFIG } from "./consolidation-engine.js";
+import { ConsolidationEngine, clusterAndConsolidate, DEFAULT_CONSOLIDATION_CONFIG, type ConsolidationKGSource } from "./consolidation-engine.js";
 import { maybeRunGc, type GcResult, type AutoGcConfig, DEFAULT_AUTO_GC_CONFIG } from "./auto-gc.js";
 import { getWriteCount, resetWriteCount } from "./activity-counter.js";
+import { deriveUsageStatus, getUsageMetadata, isUsageSignalActive } from "./usage-tracker.js";
 import { isActiveMemory } from "./memory-evolution.js";
+import { withLock } from "./distill-lock.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -75,17 +77,22 @@ export interface DreamResult {
 // Pipeline
 // ---------------------------------------------------------------------------
 
-export async function runDream(params: {
-  store: MemoryStore;
+async function runDreamInner(params: {
+  store: MemoryStorePort;
   llm: LLMClient | null;
   embedder: Pick<Embedder, "embedPassage">;
   scope: string;
   config?: Partial<DreamConfig>;
   /** Skip the minimum-writes gate (force run) */
   force?: boolean;
+  /** Override the activity-counter stats file (defaults to <dataDir>/activity-stats.json). */
+  activityStatsPath?: string;
+  /** Optional KG evidence source for triple-overlap merging (null/absent = vector-only) */
+  kgStore?: ConsolidationKGSource | null;
 }): Promise<DreamResult> {
   const { store, llm, embedder, scope, force = false } = params;
   const config = { ...DEFAULT_DREAM_CONFIG, ...params.config };
+  const statsCfg = params.activityStatsPath ? { statsPath: params.activityStatsPath } : undefined;
   const phases: DreamPhaseResult[] = [];
 
   const stats = {
@@ -102,7 +109,7 @@ export async function runDream(params: {
   // =========================================================================
   // Phase 1: Orient — assess current memory state
   // =========================================================================
-  const writeCount = getWriteCount();
+  const writeCount = getWriteCount(scope, statsCfg);
   stats.writesSinceLastDream = writeCount;
 
   const storeStats = await store.stats([scope]);
@@ -132,15 +139,41 @@ export async function runDream(params: {
   const active = entries.filter(e => isActiveMemory(e.metadata));
   stats.activeMemories = active.length;
 
+  // P0 B-1 观察:离线持久化 usageStatus 快照。写入路径不写 status(写入时
+  // useCount 必 >0,永远写不出 cold),所以 cold 只能由离线批量 derive 产生。
+  // 持久化值仅供 data_checkup/RIF 等观察视图——任何决策路径必须现场
+  // deriveUsageStatus(快照会 stale:之后 useCount/accessCount 继续变化)。
+  // best-effort:走 patchMetadata 单写通道,失败不阻断 dream。
+  // use 信号未采集时整段跳过——否则持久化的全是假 cold(useCount 恒零)。
+  let usageSnapshots = 0;
+  for (const entry of isUsageSignalActive() ? active : []) {
+    const status = deriveUsageStatus(entry);
+    const current = getUsageMetadata(entry).usageStatus;
+    if (status === current) continue;
+    // 默认态(unused 且从无 usage 对象)不写,避免给全库无谓写放大
+    if (status === "unused" && current === undefined) continue;
+    try {
+      await store.patchMetadata(entry.id, meta => {
+        const usage = meta.usage && typeof meta.usage === "object" && !Array.isArray(meta.usage)
+          ? (meta.usage as Record<string, unknown>)
+          : {};
+        meta.usage = { ...usage, usageStatus: status };
+        return meta;
+      });
+      usageSnapshots++;
+    } catch { /* observation snapshot must never block dream */ }
+  }
+
   phases.push({
     phase: "gather",
-    detail: `${active.length} active entries gathered from ${entries.length} total`,
+    detail: `${active.length} active entries gathered from ${entries.length} total`
+      + (usageSnapshots > 0 ? `; usage snapshot: ${usageSnapshots} statuses persisted` : ""),
   });
 
   if (active.length < config.minClusterSize) {
     phases.push({ phase: "consolidate", detail: "skipped — too few active entries" });
     phases.push({ phase: "prune", detail: "skipped — too few entries for GC" });
-    resetWriteCount();
+    resetWriteCount(scope, statsCfg);
     return { ran: true, reason: "completed_early", phases, stats };
   }
 
@@ -148,36 +181,44 @@ export async function runDream(params: {
   // Phase 3: Consolidate — cluster, merge, generate insights + patterns
   // =========================================================================
 
-  // 3a: Deterministic consolidation (merge near-duplicates, link clusters)
-  const engine = new ConsolidationEngine(store, {
-    ...DEFAULT_CONSOLIDATION_CONFIG,
-    clusterThreshold: config.clusterThreshold,
-    maxEntriesPerRun: config.maxEntriesPerRun,
-  });
-  const consolidation = await engine.run(scope);
-  stats.clustersFound += consolidation.clustersFound;
-  stats.mergedCount += consolidation.mergedCount;
-
-  // 3b: LLM-driven cluster consolidation (insights + patterns) — requires LLM
-  if (llm) {
-    const clusterResult = await clusterAndConsolidate({
-      entries: active,
-      embedder,
-      llm,
-      store,
-      scope,
-      minClusterSize: config.minClusterSize,
-      clusterThreshold: config.clusterThreshold - 0.07, // slightly lower for semantic clustering
-      extractPatterns: config.extractPatterns,
-    });
-    stats.clustersFound += clusterResult.clustersFound;
-    stats.insightsGenerated = clusterResult.insightsGenerated;
-    stats.patternsExtracted = clusterResult.patternsExtracted;
-  }
+  // P2 (codex): run the consolidation phase under the scope's consolidate lock so a
+  // standalone consolidate_memories on the same scope can't run concurrently with the
+  // dream's own consolidation. Nested inside the dream lock (dream → consolidate →
+  // store-write), consistent with the one-way lock order.
+  const consolidateOutcome = await withLock(`consolidate-${scope}`, async () => {
+    // 3a: Deterministic consolidation (merge near-duplicates, link clusters)
+    const engine = new ConsolidationEngine(store, {
+      ...DEFAULT_CONSOLIDATION_CONFIG,
+      clusterThreshold: config.clusterThreshold,
+      maxEntriesPerRun: config.maxEntriesPerRun,
+    }, params.kgStore ?? null);
+    const consolidation = await engine.run(scope);
+    stats.clustersFound += consolidation.clustersFound;
+    stats.mergedCount += consolidation.mergedCount;
+
+    // 3b: LLM-driven cluster consolidation (insights + patterns) — requires LLM
+    if (llm) {
+      const clusterResult = await clusterAndConsolidate({
+        entries: active,
+        embedder,
+        llm,
+        store,
+        scope,
+        minClusterSize: config.minClusterSize,
+        clusterThreshold: config.clusterThreshold - 0.07, // slightly lower for semantic clustering
+        extractPatterns: config.extractPatterns,
+      });
+      stats.clustersFound += clusterResult.clustersFound;
+      stats.insightsGenerated = clusterResult.insightsGenerated;
+      stats.patternsExtracted = clusterResult.patternsExtracted;
+    }
+  }, { onBusy: "skip", expireMs: 600_000 });
 
   phases.push({
     phase: "consolidate",
-    detail: `${stats.clustersFound} clusters, ${stats.mergedCount} merged, ${stats.insightsGenerated} insights, ${stats.patternsExtracted} patterns`,
+    detail: consolidateOutcome.ran
+      ? `${stats.clustersFound} clusters, ${stats.mergedCount} merged, ${stats.insightsGenerated} insights, ${stats.patternsExtracted} patterns`
+      : `skipped — another process holds the consolidate lock for scope ${scope}`,
   });
 
   // =========================================================================
@@ -199,6 +240,49 @@ export async function runDream(params: {
   return { ran: true, phases, stats };
 }
 
+/**
+ * P0-1: run dream under a per-scope cross-process lock. Dream internally does
+ * consolidation + gc, so the lock sits at this outermost entry — no nested maintenance
+ * locks. If another of the 11 mcp-server processes holds the scope's dream lock, skip
+ * rather than queue: a redundant dream on a personal store is pure waste, and the next
+ * writer's dream picks up whatever this run skipped.
+ */
+export async function runDream(params: {
+  store: MemoryStorePort;
+  llm: LLMClient | null;
+  embedder: Pick<Embedder, "embedPassage">;
+  scope: string;
+  config?: Partial<DreamConfig>;
+  /** Skip the minimum-writes gate (force run) */
+  force?: boolean;
+  /** Override the activity-counter stats file (defaults to <dataDir>/activity-stats.json). */
+  activityStatsPath?: string;
+  /** Optional KG evidence source for triple-overlap merging (null/absent = vector-only) */
+  kgStore?: ConsolidationKGSource | null;
+}): Promise<DreamResult> {
+  const outcome = await withLock(
+    `dream-${params.scope}`,
+    () => runDreamInner(params),
+    { onBusy: "skip", expireMs: 600_000 },
+  );
+  if (outcome.ran) return outcome.result;
+  return {
+    ran: false,
+    reason: "locked_by_another_process",
+    phases: [{ phase: "orient", detail: `another process holds the dream lock for scope ${params.scope}` }],
+    stats: {
+      totalMemories: 0,
+      activeMemories: 0,
+      writesSinceLastDream: 0,
+      clustersFound: 0,
+      insightsGenerated: 0,
+      patternsExtracted: 0,
+      mergedCount: 0,
+      archivedCount: 0,
+    },
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Formatting
 // ---------------------------------------------------------------------------

package/src/env-config.ts

@@ -0,0 +1,77 @@
+/**
+ * Centralized RECALLNEST_* environment variable accessors (P3-C config 收口).
+ *
+ * Single source of truth for every fixed `RECALLNEST_*` env flag read across `src/`:
+ * the env NAME, its default, and its parsing all live here. Consumers call these
+ * accessors instead of reading `process.env` directly.
+ *
+ * This is a PURE-MOVEMENT refactor — each accessor preserves the exact original
+ * parsing. Do not "improve" them; the following invariants are load-bearing:
+ *
+ * - Boolean flags use strict `=== "true"` — no trim, no case-folding, no truthy
+ *   coercion. `"True"` / `" true "` / `"1"` must NOT enable a flag.
+ * - String defaults use `||`, NOT `??` — an empty string falls through to the
+ *   default (matches the original inline reads).
+ * - Raw-value accessors (recall mode, ports) return the UNPARSED env value so the
+ *   caller keeps its existing validation / clamping / config-fallback logic. In
+ *   particular `recallModeRaw()` must not default to "summary" here, or it would
+ *   bypass the `config.recallMode` fallback in resolveRecallMode().
+ * - `mcpTier()` keeps only the type assertion with NO runtime validation — an
+ *   illegal non-empty value is preserved as-is (downstream shouldRegisterTool()
+ *   relies on this), so do not coerce unknown values back to the default.
+ *
+ * Accessors are FUNCTIONS (lazy): they read `process.env` at call time. Never
+ * freeze them into module-load constants — 100+ tests toggle `process.env` at
+ * runtime. Consumers must substitute in place and never relocate a read across
+ * the `loadDotEnv()` boundary or into a different evaluation phase: five reads are
+ * intentionally module-init-time eager (mcp-server tier, api/ui ports,
+ * activity-counter / distill-lock data dir) and must stay eager.
+ *
+ * Intentionally NOT centralized here:
+ * - scope-policy.ts's RECALLNEST_DEFAULT_SCOPE / _SCOPE / _PROJECT_SCOPE /
+ *   _SESSION_ID — an injectable `options.env || process.env` policy entry that is
+ *   already consolidated in that module with caller-injection semantics.
+ * - store.ts's `RECALLNEST_NS` — a local hash-namespace constant, not an env var.
+ * - config-template `${VAR}` expansion in runtime-config / embedder / llm-client.
+ */
+
+// --- Boolean feature flags (strict === "true") ---
+
+export const multiVector = (): boolean => process.env.RECALLNEST_MULTI_VECTOR === "true";
+
+export const emotionScoring = (): boolean => process.env.RECALLNEST_EMOTION_SCORING === "true";
+
+export const predictiveMemory = (): boolean => process.env.RECALLNEST_PREDICTIVE_MEMORY === "true";
+
+export const synthesize = (): boolean => process.env.RECALLNEST_SYNTHESIZE === "true";
+
+export const llmConsolidation = (): boolean => process.env.RECALLNEST_LLM_CONSOLIDATION === "true";
+
+export const constructiveRetrieval = (): boolean =>
+  process.env.RECALLNEST_CONSTRUCTIVE_RETRIEVAL === "true";
+
+export const narrativeMode = (): boolean => process.env.RECALLNEST_NARRATIVE_MODE === "true";
+
+export const kgMode = (): boolean => process.env.RECALLNEST_KG_MODE === "true";
+
+export const coreSummary = (): boolean => process.env.RECALLNEST_CORE_SUMMARY === "true";
+
+export const errorSignatureBoost = (): boolean =>
+  process.env.RECALLNEST_ERROR_SIGNATURE_BOOST === "true";
+
+export const usageDecay = (): boolean => process.env.RECALLNEST_USAGE_DECAY === "true";
+
+// --- String settings with `||` default (empty string falls through) ---
+
+export const dataDir = (): string => process.env.RECALLNEST_DATA_DIR || "data";
+
+export const mcpTier = (): "core" | "advanced" | "full" =>
+  (process.env.RECALLNEST_MCP_TIER || "advanced") as "core" | "advanced" | "full";
+
+// --- Raw env values (caller validates / clamps / falls back to config) ---
+
+export const recallModeRaw = (): string | undefined => process.env.RECALLNEST_RECALL_MODE;
+
+export const uiPortRaw = (): string | undefined => process.env.RECALLNEST_UI_PORT;
+
+export const apiPortRaw = (): string | undefined => process.env.RECALLNEST_API_PORT;