memory-braid 0.3.6 → 0.4.0

package/src/mem0-client.ts

@@ -112,6 +112,64 @@ function asNonEmptyString(value: unknown): string | undefined {
   return trimmed ? trimmed : undefined;
 }
 
+function cloneConfigValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((entry) => cloneConfigValue(entry));
+  }
+  if (isObjectLike(value)) {
+    return cloneConfigRecord(value);
+  }
+  return value;
+}
+
+function cloneConfigRecord(value: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    out[key] = cloneConfigValue(entry);
+  }
+  return out;
+}
+
+function shouldReplaceProviderSection(
+  baseValue: Record<string, unknown>,
+  overrideValue: Record<string, unknown>,
+): boolean {
+  const baseProvider = asNonEmptyString(baseValue.provider)?.toLowerCase();
+  const overrideProvider = asNonEmptyString(overrideValue.provider)?.toLowerCase();
+  return Boolean(baseProvider && overrideProvider && baseProvider !== overrideProvider);
+}
+
+function deepMergeConfigRecords(
+  baseValue: Record<string, unknown>,
+  overrideValue: Record<string, unknown>,
+): Record<string, unknown> {
+  const merged = cloneConfigRecord(baseValue);
+  for (const [key, overrideEntry] of Object.entries(overrideValue)) {
+    if (typeof overrideEntry === "undefined") {
+      continue;
+    }
+    const currentBase = merged[key];
+    if (isObjectLike(currentBase) && isObjectLike(overrideEntry)) {
+      merged[key] = shouldReplaceProviderSection(currentBase, overrideEntry)
+        ? cloneConfigRecord(overrideEntry)
+        : deepMergeConfigRecords(currentBase, overrideEntry);
+      continue;
+    }
+    merged[key] = cloneConfigValue(overrideEntry);
+  }
+  return merged;
+}
+
+export function mergeOssConfigWithDefaults(
+  defaults: Record<string, unknown>,
+  override: Record<string, unknown>,
+): Record<string, unknown> {
+  if (!isLikelyOssConfig(override)) {
+    return cloneConfigRecord(defaults);
+  }
+  return deepMergeConfigRecords(defaults, override);
+}
+
 function asOssMemoryCtor(value: unknown): OssMemoryCtor | undefined {
   if (typeof value !== "function") {
     return undefined;
@@ -157,6 +215,20 @@ function isSqliteBindingsError(error: unknown): boolean {
   return /Could not locate the bindings file/i.test(message) || /node_sqlite3\.node/i.test(message);
 }
 
+export function isMem0DeleteNotFoundError(error: unknown): boolean {
+  const message = asErrorMessage(error).toLowerCase();
+  if (!message) {
+    return false;
+  }
+
+  return (
+    /\bmemory\b.*\bnot found\b/.test(message) ||
+    /\bnot found\b.*\bmemory\b/.test(message) ||
+    /\bmemory\b.*\bdoes not exist\b/.test(message) ||
+    /\bno such memory\b/.test(message)
+  );
+}
+
 function createLocalRequire(): NodeJS.Require {
   return createRequire(import.meta.url);
 }
@@ -410,12 +482,11 @@ export class Mem0Adapter {
         );
       }
 
-      const providedConfig = this.cfg.mem0.ossConfig;
+      const providedConfig = asRecord(this.cfg.mem0.ossConfig);
       const hasCustomConfig = isLikelyOssConfig(providedConfig);
-      const baseConfig = hasCustomConfig
-        ? { ...providedConfig }
-        : buildDefaultOssConfig(this.cfg, this.stateDir);
-      const configToUse = applyOssStorageDefaults(baseConfig, this.stateDir);
+      const defaultConfig = buildDefaultOssConfig(this.cfg, this.stateDir);
+      const mergedConfig = mergeOssConfigWithDefaults(defaultConfig, providedConfig);
+      const configToUse = applyOssStorageDefaults(mergedConfig, this.stateDir);
       await ensureSqliteParentDirs(configToUse);
 
       this.ossClient = new Memory(configToUse);
@@ -738,6 +809,21 @@ export class Mem0Adapter {
       });
       return true;
     } catch (err) {
+      const missingRemote = isMem0DeleteNotFoundError(err);
+      if (missingRemote) {
+        this.log.debug("memory_braid.mem0.response", {
+          runId: params.runId,
+          action: "delete",
+          mode: prepared.mode,
+          workspaceHash: params.scope.workspaceHash,
+          agentId: params.scope.agentId,
+          memoryId: params.memoryId,
+          durMs: Date.now() - startedAt,
+          alreadyMissing: true,
+        });
+        return true;
+      }
+
       this.log.warn("memory_braid.mem0.error", {
         runId: params.runId,
         action: "delete",

package/src/state.ts

@@ -1,27 +1,43 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import type { BootstrapState, CaptureDedupeState, ReconcileState } from "./types.js";
+import type {
+  CaptureDedupeState,
+  LifecycleState,
+  PluginStatsState,
+} from "./types.js";
 
-const DEFAULT_BOOTSTRAP: BootstrapState = {
+const DEFAULT_CAPTURE_DEDUPE: CaptureDedupeState = {
   version: 1,
-  completed: false,
+  seen: {},
 };
 
-const DEFAULT_RECONCILE: ReconcileState = {
+const DEFAULT_LIFECYCLE: LifecycleState = {
   version: 1,
   entries: {},
 };
 
-const DEFAULT_CAPTURE_DEDUPE: CaptureDedupeState = {
+const DEFAULT_STATS: PluginStatsState = {
   version: 1,
-  seen: {},
+  capture: {
+    runs: 0,
+    runsWithCandidates: 0,
+    runsNoCandidates: 0,
+    candidates: 0,
+    dedupeSkipped: 0,
+    persisted: 0,
+    mem0AddAttempts: 0,
+    mem0AddWithId: 0,
+    mem0AddWithoutId: 0,
+    entityAnnotatedCandidates: 0,
+    totalEntitiesAttached: 0,
+  },
 };
 
 export type StatePaths = {
   rootDir: string;
-  bootstrapFile: string;
-  reconcileFile: string;
   captureDedupeFile: string;
+  lifecycleFile: string;
+  statsFile: string;
   stateLockFile: string;
 };
 
@@ -29,9 +45,9 @@ export function createStatePaths(stateDir: string): StatePaths {
   const rootDir = path.join(stateDir, "memory-braid");
   return {
     rootDir,
-    bootstrapFile: path.join(rootDir, "bootstrap-checkpoint.v1.json"),
-    reconcileFile: path.join(rootDir, "reconcile-state.v1.json"),
     captureDedupeFile: path.join(rootDir, "capture-dedupe.v1.json"),
+    lifecycleFile: path.join(rootDir, "lifecycle.v1.json"),
+    statsFile: path.join(rootDir, "stats.v1.json"),
     stateLockFile: path.join(rootDir, "state.v1.lock"),
   };
 }
@@ -57,41 +73,52 @@ async function writeJsonFile(filePath: string, value: unknown): Promise<void> {
   await fs.rename(tmpPath, filePath);
 }
 
-export async function readBootstrapState(paths: StatePaths): Promise<BootstrapState> {
-  const value = await readJsonFile(paths.bootstrapFile, DEFAULT_BOOTSTRAP);
-  return { ...DEFAULT_BOOTSTRAP, ...value };
+export async function readCaptureDedupeState(paths: StatePaths): Promise<CaptureDedupeState> {
+  const value = await readJsonFile(paths.captureDedupeFile, DEFAULT_CAPTURE_DEDUPE);
+  return {
+    version: 1,
+    seen: value.seen ?? {},
+  };
 }
 
-export async function writeBootstrapState(paths: StatePaths, state: BootstrapState): Promise<void> {
-  await writeJsonFile(paths.bootstrapFile, state);
+export async function writeCaptureDedupeState(
+  paths: StatePaths,
+  state: CaptureDedupeState,
+): Promise<void> {
+  await writeJsonFile(paths.captureDedupeFile, state);
 }
 
-export async function readReconcileState(paths: StatePaths): Promise<ReconcileState> {
-  const value = await readJsonFile(paths.reconcileFile, DEFAULT_RECONCILE);
+export async function readLifecycleState(paths: StatePaths): Promise<LifecycleState> {
+  const value = await readJsonFile(paths.lifecycleFile, DEFAULT_LIFECYCLE);
   return {
     version: 1,
     entries: value.entries ?? {},
-    lastRunAt: value.lastRunAt,
+    lastCleanupAt: value.lastCleanupAt,
+    lastCleanupReason: value.lastCleanupReason,
+    lastCleanupScanned: value.lastCleanupScanned,
+    lastCleanupExpired: value.lastCleanupExpired,
+    lastCleanupDeleted: value.lastCleanupDeleted,
+    lastCleanupFailed: value.lastCleanupFailed,
   };
 }
 
-export async function writeReconcileState(paths: StatePaths, state: ReconcileState): Promise<void> {
-  await writeJsonFile(paths.reconcileFile, state);
+export async function writeLifecycleState(paths: StatePaths, state: LifecycleState): Promise<void> {
+  await writeJsonFile(paths.lifecycleFile, state);
 }
 
-export async function readCaptureDedupeState(paths: StatePaths): Promise<CaptureDedupeState> {
-  const value = await readJsonFile(paths.captureDedupeFile, DEFAULT_CAPTURE_DEDUPE);
+export async function readStatsState(paths: StatePaths): Promise<PluginStatsState> {
+  const value = await readJsonFile(paths.statsFile, DEFAULT_STATS);
   return {
     version: 1,
-    seen: value.seen ?? {},
+    capture: {
+      ...DEFAULT_STATS.capture,
+      ...(value.capture ?? {}),
+    },
   };
 }
 
-export async function writeCaptureDedupeState(
-  paths: StatePaths,
-  state: CaptureDedupeState,
-): Promise<void> {
-  await writeJsonFile(paths.captureDedupeFile, state);
+export async function writeStatsState(paths: StatePaths, state: PluginStatsState): Promise<void> {
+  await writeJsonFile(paths.statsFile, state);
 }
 
 export async function withStateLock<T>(

package/src/types.ts

@@ -1,22 +1,11 @@
 export type MemoryBraidSource = "local" | "mem0";
 
-export type ManagedSourceType = "markdown" | "session";
-
-export type PersistedSourceType = ManagedSourceType | "capture";
-
 export type ScopeKey = {
   workspaceHash: string;
   agentId: string;
   sessionKey?: string;
 };
 
-export type TargetWorkspace = {
-  workspaceDir: string;
-  stateDir: string;
-  agentId: string;
-  workspaceHash: string;
-};
-
 export type MemoryBraidResult = {
   id?: string;
   source: MemoryBraidSource;
@@ -31,61 +20,54 @@ export type MemoryBraidResult = {
   contentHash?: string;
 };
 
-export type ManifestChunk = {
-  chunkKey: string;
-  contentHash: string;
-  sourceType: ManagedSourceType;
-  text: string;
-  path: string;
-  workspaceHash: string;
-  agentId: string;
-  updatedAt: number;
+export type CaptureDedupeState = {
+  version: 1;
+  seen: Record<string, number>;
 };
 
-export type IndexedEntry = {
-  chunkKey: string;
-  id?: string;
+export type LifecycleEntry = {
+  memoryId: string;
   contentHash: string;
-  sourceType: PersistedSourceType;
-  path?: string;
   workspaceHash: string;
   agentId: string;
+  sessionKey?: string;
+  category?: string;
+  createdAt: number;
+  lastCapturedAt: number;
+  lastRecalledAt?: number;
+  recallCount: number;
   updatedAt: number;
-  missingCount?: number;
 };
 
-export type ReconcileState = {
+export type LifecycleState = {
   version: 1;
-  entries: Record<string, IndexedEntry>;
-  lastRunAt?: string;
+  entries: Record<string, LifecycleEntry>;
+  lastCleanupAt?: string;
+  lastCleanupReason?: "startup" | "interval" | "command";
+  lastCleanupScanned?: number;
+  lastCleanupExpired?: number;
+  lastCleanupDeleted?: number;
+  lastCleanupFailed?: number;
 };
 
-export type BootstrapState = {
-  version: 1;
-  completed: boolean;
-  startedAt?: string;
-  completedAt?: string;
-  lastError?: string;
-  summary?: {
-    reason: string;
-    total: number;
-    upserted: number;
-    deleted: number;
-    unchanged: number;
-  };
+export type CaptureStats = {
+  runs: number;
+  runsWithCandidates: number;
+  runsNoCandidates: number;
+  candidates: number;
+  dedupeSkipped: number;
+  persisted: number;
+  mem0AddAttempts: number;
+  mem0AddWithId: number;
+  mem0AddWithoutId: number;
+  entityAnnotatedCandidates: number;
+  totalEntitiesAttached: number;
+  lastRunAt?: string;
 };
 
-export type CaptureDedupeState = {
+export type PluginStatsState = {
   version: 1;
-  seen: Record<string, number>;
-};
-
-export type ReconcileSummary = {
-  reason: string;
-  total: number;
-  upserted: number;
-  deleted: number;
-  unchanged: number;
+  capture: CaptureStats;
 };
 
 export type ExtractedCandidate = {

package/src/bootstrap.ts

@@ -1,82 +0,0 @@
-import type { MemoryBraidConfig } from "./config.js";
-import { MemoryBraidLogger } from "./logger.js";
-import { Mem0Adapter } from "./mem0-client.js";
-import {
-  readBootstrapState,
-  type StatePaths,
-  writeBootstrapState,
-} from "./state.js";
-import type { TargetWorkspace } from "./types.js";
-import { runReconcileOnce } from "./reconcile.js";
-
-export async function runBootstrapIfNeeded(params: {
-  cfg: MemoryBraidConfig;
-  mem0: Mem0Adapter;
-  statePaths: StatePaths;
-  log: MemoryBraidLogger;
-  targets: TargetWorkspace[];
-  runId?: string;
-}): Promise<{ started: boolean; completed: boolean }> {
-  const runId = params.runId ?? params.log.newRunId();
-
-  if (!params.cfg.bootstrap.enabled) {
-    return { started: false, completed: false };
-  }
-
-  const existing = await readBootstrapState(params.statePaths);
-  if (existing.completed) {
-    return { started: false, completed: true };
-  }
-
-  params.log.debug("memory_braid.bootstrap.begin", {
-    runId,
-    targets: params.targets.length,
-  }, true);
-
-  await writeBootstrapState(params.statePaths, {
-    version: 1,
-    completed: false,
-    startedAt: new Date().toISOString(),
-    lastError: undefined,
-  });
-
-  try {
-    const summary = await runReconcileOnce({
-      cfg: params.cfg,
-      mem0: params.mem0,
-      statePaths: params.statePaths,
-      log: params.log,
-      targets: params.targets,
-      reason: "bootstrap",
-      runId,
-      deleteStale: false,
-    });
-
-    await writeBootstrapState(params.statePaths, {
-      version: 1,
-      completed: true,
-      startedAt: existing.startedAt ?? new Date().toISOString(),
-      completedAt: new Date().toISOString(),
-      summary,
-    });
-
-    params.log.debug("memory_braid.bootstrap.complete", {
-      runId,
-      ...summary,
-    }, true);
-    return { started: true, completed: true };
-  } catch (err) {
-    const error = err instanceof Error ? err.message : String(err);
-    await writeBootstrapState(params.statePaths, {
-      version: 1,
-      completed: false,
-      startedAt: existing.startedAt ?? new Date().toISOString(),
-      lastError: error,
-    });
-    params.log.warn("memory_braid.bootstrap.error", {
-      runId,
-      error,
-    });
-    return { started: true, completed: false };
-  }
-}