wolbarg 0.5.5 → 0.5.7

package/dist/index.cjs

@@ -4,9 +4,9 @@ var fs6 = require("node:fs");
 var path7 = require("node:path");
 var crypto$1 = require('crypto');
 var fs = require('fs/promises');
+var async_hooks = require('async_hooks');
 var sqlite$1 = require("node:sqlite");
 var sqliteVec = require('sqlite-vec');
-var async_hooks = require('async_hooks');
 var events = require('events');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
@@ -472,8 +472,8 @@ var AsyncMutex = class {
    */
   async runExclusive(fn) {
     let release;
-    const next = new Promise((resolve) => {
-      release = resolve;
+    const next = new Promise((resolve3) => {
+      release = resolve3;
     });
     const previous = this.chain;
     this.chain = previous.then(() => next);
@@ -2265,19 +2265,35 @@ var DEFAULT_CONCURRENCY = {
   maxRetries: 5,
   baseBackoffMs: 50,
   maxBackoffMs: 2e3,
-  lockTimeoutMs: 5e3
+  lockTimeoutMs: 5e3,
+  lockDeadlineMs: 3e4
+};
+var MULTI_PROCESS_CONCURRENCY = {
+  maxRetries: 12,
+  baseBackoffMs: 40,
+  maxBackoffMs: 3e3,
+  lockTimeoutMs: 15e3,
+  lockDeadlineMs: 9e4
 };
 function resolveConcurrencyConfig(input) {
+  const base = input?.multiProcess ? MULTI_PROCESS_CONCURRENCY : DEFAULT_CONCURRENCY;
+  const maxRetries = input?.maxRetries ?? base.maxRetries;
+  const baseBackoffMs = input?.baseBackoffMs ?? base.baseBackoffMs;
+  const maxBackoffMs = input?.maxBackoffMs ?? base.maxBackoffMs;
+  const lockTimeoutMs = input?.lockTimeoutMs ?? base.lockTimeoutMs;
+  const lockDeadlineMs = input?.lockDeadlineMs ?? Math.max(base.lockDeadlineMs, lockTimeoutMs * (maxRetries + 1));
   const resolved = {
-    maxRetries: input?.maxRetries ?? DEFAULT_CONCURRENCY.maxRetries,
-    baseBackoffMs: input?.baseBackoffMs ?? DEFAULT_CONCURRENCY.baseBackoffMs,
-    maxBackoffMs: input?.maxBackoffMs ?? DEFAULT_CONCURRENCY.maxBackoffMs,
-    lockTimeoutMs: input?.lockTimeoutMs ?? DEFAULT_CONCURRENCY.lockTimeoutMs
+    maxRetries,
+    baseBackoffMs,
+    maxBackoffMs,
+    lockTimeoutMs,
+    lockDeadlineMs
   };
   assertPositiveInt(resolved.maxRetries, "concurrency.maxRetries");
   assertPositiveNumber(resolved.baseBackoffMs, "concurrency.baseBackoffMs");
   assertPositiveNumber(resolved.maxBackoffMs, "concurrency.maxBackoffMs");
   assertPositiveInt(resolved.lockTimeoutMs, "concurrency.lockTimeoutMs");
+  assertPositiveInt(resolved.lockDeadlineMs, "concurrency.lockDeadlineMs");
   if (resolved.maxBackoffMs < resolved.baseBackoffMs) {
     throw new ConfigurationError(
       "concurrency.maxBackoffMs must be >= concurrency.baseBackoffMs"
@@ -2303,19 +2319,25 @@ function isSqliteBusyError(error) {
   return lower.includes("database is locked") || lower.includes("sqlite_busy") || lower.includes("busy");
 }
 function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 function backoffDelay(attempt, config) {
   const exp = Math.min(
     config.maxBackoffMs,
     config.baseBackoffMs * 2 ** attempt
   );
-  const jitter = Math.random() * config.baseBackoffMs;
-  return Math.min(config.maxBackoffMs, exp + jitter);
+  return Math.random() * exp;
+}
+function deadlineExceeded(startedAt, config) {
+  return performance.now() - startedAt >= config.lockDeadlineMs;
 }
 async function withImmediateTransaction(db, config, fn, onRetry) {
   let lastError;
+  const startedAt = performance.now();
   for (let attempt = 0; attempt <= config.maxRetries; attempt += 1) {
+    if (attempt > 0 && deadlineExceeded(startedAt, config)) {
+      break;
+    }
     try {
       db.exec("BEGIN IMMEDIATE");
       try {
@@ -2335,7 +2357,7 @@ async function withImmediateTransaction(db, config, fn, onRetry) {
       if (!isBusy) {
         throw error;
       }
-      if (attempt >= config.maxRetries) {
+      if (attempt >= config.maxRetries || deadlineExceeded(startedAt, config)) {
         break;
       }
       const delay = backoffDelay(attempt, config);
@@ -2348,7 +2370,7 @@ async function withImmediateTransaction(db, config, fn, onRetry) {
     {
       cause: lastError instanceof Error ? lastError : void 0,
       reason: "SQLITE_BUSY exhausted retries",
-      suggestion: "Increase concurrency.maxRetries or concurrency.lockTimeoutMs, or consider the Postgres backend for high-concurrency multi-agent workloads."
+      suggestion: "Increase concurrency.maxRetries / concurrency.lockDeadlineMs, set concurrency.multiProcess: true for shared-file writers, or use the Postgres backend."
     }
   );
 }
@@ -2406,6 +2428,20 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
   transactionDepth = 0;
   /** Incrementing counter for deterministic savepoint names. */
   savepointCounter = 0;
+  /**
+   * Serializes top-level write transactions on the single SQLite connection.
+   * SQLite is single-writer; serializing in-process avoids SQLITE_BUSY churn
+   * AND prevents interleaved BEGIN/SAVEPOINT state corruption when many async
+   * callers share one connection (see "no such savepoint" class of bugs).
+   */
+  writeMutex = new AsyncMutex();
+  /**
+   * Async-context flag: true while executing inside a top-level write
+   * transaction held by this provider. Used so writes issued from within an
+   * ambient transaction (e.g. compress()) join that ACID unit, WITHOUT
+   * mistaking the coalescer's own flush window for an ambient transaction.
+   */
+  txContext = new async_hooks.AsyncLocalStorage();
   /** Hot in-process ANN for blob backend (sqlite-vec unavailable platforms). */
   memoryIndex = null;
   memoryIndexDirty = false;
@@ -2448,62 +2484,85 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
   }
   /** Open the database, run migrations, and prepare statements. */
   async open() {
-    try {
-      const dbPath = this.resolvePath(this.connectionString);
-      this.resolvedPath = dbPath;
-      if (dbPath !== ":memory:") {
-        fs6__default.default.mkdirSync(path7__default.default.dirname(dbPath), { recursive: true });
-      }
-      const db = new sqlite$1.DatabaseSync(dbPath, { allowExtension: true });
-      this.db = db;
-      db.exec("PRAGMA journal_mode = WAL;");
-      db.exec(`
-        PRAGMA synchronous = NORMAL;
-        PRAGMA foreign_keys = ON;
-        PRAGMA busy_timeout = ${this.concurrency.lockTimeoutMs};
-        PRAGMA temp_store = MEMORY;
-        PRAGMA cache_size = -32768;
-        PRAGMA mmap_size = 134217728;
-        PRAGMA wal_autocheckpoint = 2000;
-        PRAGMA recursive_triggers = OFF;
-      `);
-      this.sqliteVecLoaded = this.tryLoadSqliteVec(db);
-      this.runMigrations(db);
-      this.statements = this.prepareStatements(db);
-      const backend = this.readMetaString(META_KEYS.vectorBackend);
-      const dims = this.readMetaNumber(META_KEYS.embeddingDimensions);
-      if (backend) {
-        this.vectorBackend = backend;
-      } else if (this.sqliteVecLoaded) {
-        this.vectorBackend = "sqlite-vec";
-      } else {
-        if (!warnedSqliteVecFallback) {
-          warnedSqliteVecFallback = true;
-          warnLogger.warn(
-            "sqlite-vec unavailable on this platform; using blob ANN fallback."
+    const startedAt = performance.now();
+    let attempt = 0;
+    for (; ; ) {
+      try {
+        this.openOnce();
+        return;
+      } catch (error) {
+        try {
+          this.db?.close();
+        } catch {
+        }
+        this.db = null;
+        this.statements = null;
+        const busy = isSqliteBusyError(error);
+        const exhausted = attempt >= this.concurrency.maxRetries || performance.now() - startedAt >= this.concurrency.lockDeadlineMs;
+        if (!busy || exhausted) {
+          throw new InitializationError(
+            `Failed to open SQLite database: ${this.describe(error)}`,
+            { cause: error instanceof Error ? error : void 0 }
           );
         }
-        this.vectorBackend = "blob";
+        const base = Math.min(
+          this.concurrency.maxBackoffMs,
+          this.concurrency.baseBackoffMs * 2 ** attempt
+        );
+        const delay = Math.random() * base;
+        this.retryLog?.(
+          `SQLITE_BUSY during open attempt=${attempt + 1} backoffMs=${Math.round(delay)}`
+        );
+        attempt += 1;
+        await new Promise((r) => setTimeout(r, delay));
       }
-      if (dims !== null) {
-        this.vectorDimensions = dims;
-        this.ensureVectorStorage(dims);
-        this.reprepareVectorStatements();
-        if (this.vectorBackend === "blob") {
-          this.memoryIndexDirty = true;
-        }
+    }
+  }
+  /** Single open attempt — connect, apply pragmas, migrate, prepare. */
+  openOnce() {
+    const dbPath = this.resolvePath(this.connectionString);
+    this.resolvedPath = dbPath;
+    if (dbPath !== ":memory:") {
+      fs6__default.default.mkdirSync(path7__default.default.dirname(dbPath), { recursive: true });
+    }
+    const db = new sqlite$1.DatabaseSync(dbPath, { allowExtension: true });
+    this.db = db;
+    db.exec(`PRAGMA busy_timeout = ${this.concurrency.lockTimeoutMs};`);
+    db.exec("PRAGMA journal_mode = WAL;");
+    db.exec(`
+      PRAGMA synchronous = NORMAL;
+      PRAGMA foreign_keys = ON;
+      PRAGMA temp_store = MEMORY;
+      PRAGMA cache_size = -32768;
+      PRAGMA mmap_size = 134217728;
+      PRAGMA wal_autocheckpoint = 2000;
+      PRAGMA recursive_triggers = OFF;
+    `);
+    this.sqliteVecLoaded = this.tryLoadSqliteVec(db);
+    this.runMigrations(db);
+    this.statements = this.prepareStatements(db);
+    const backend = this.readMetaString(META_KEYS.vectorBackend);
+    const dims = this.readMetaNumber(META_KEYS.embeddingDimensions);
+    if (backend) {
+      this.vectorBackend = backend;
+    } else if (this.sqliteVecLoaded) {
+      this.vectorBackend = "sqlite-vec";
+    } else {
+      if (!warnedSqliteVecFallback) {
+        warnedSqliteVecFallback = true;
+        warnLogger.warn(
+          "sqlite-vec unavailable on this platform; using blob ANN fallback."
+        );
       }
-    } catch (error) {
-      try {
-        this.db?.close();
-      } catch {
+      this.vectorBackend = "blob";
+    }
+    if (dims !== null) {
+      this.vectorDimensions = dims;
+      this.ensureVectorStorage(dims);
+      this.reprepareVectorStatements();
+      if (this.vectorBackend === "blob") {
+        this.memoryIndexDirty = true;
       }
-      this.db = null;
-      this.statements = null;
-      throw new InitializationError(
-        `Failed to open SQLite database: ${this.describe(error)}`,
-        { cause: error instanceof Error ? error : void 0 }
-      );
     }
   }
   /** Drain pending inserts, optimize, and close the SQLite connection. */
@@ -2576,8 +2635,11 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
   /** Insert a single memory row (coalesced under concurrent writers). */
   async insertMemory(input) {
     this.requireVectorReady();
-    return new Promise((resolve, reject) => {
-      this.insertQueue.push({ input, resolve, reject });
+    if (this.txContext.getStore() === true) {
+      return this.insertMemoryImmediate(input);
+    }
+    return new Promise((resolve3, reject) => {
+      this.insertQueue.push({ input, resolve: resolve3, reject });
       if (this.insertQueue.length >= INSERT_COALESCE_THRESHOLD) {
         this.insertFlushScheduled = false;
         void this.flushInsertQueue();
@@ -2872,7 +2934,8 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
     const stmts = this.requireStatements();
     const archived = [];
     return this.withTransaction(() => {
-      for (const id of ids) {
+      const orderedIds = [...new Set(ids)].sort();
+      for (const id of orderedIds) {
         const existing = stmts.getMemoryById.get(id, organization);
         const result = stmts.archiveMemory.run(
           compressedIntoId,
@@ -3013,7 +3076,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
   }
   async withTransaction(fn) {
     const db = this.requireDb();
-    if (this.transactionDepth > 0) {
+    if (this.txContext.getStore() === true) {
       const savepointName = `wolbarg_sp_${this.savepointCounter++}`;
       db.exec(`SAVEPOINT ${savepointName}`);
       try {
@@ -3031,21 +3094,26 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
         this.transactionDepth -= 1;
       }
     }
-    this.transactionDepth = 1;
-    try {
-      return await withImmediateTransaction(
-        db,
-        this.concurrency,
-        fn,
-        (attempt, delayMs) => {
-          this.retryLog?.(
-            `SQLITE_BUSY retry attempt=${attempt} backoffMs=${Math.round(delayMs)}`
+    return this.writeMutex.runExclusive(
+      () => this.txContext.run(true, async () => {
+        this.transactionDepth = 1;
+        this.savepointCounter = 0;
+        try {
+          return await withImmediateTransaction(
+            db,
+            this.concurrency,
+            fn,
+            (attempt, delayMs) => {
+              this.retryLog?.(
+                `SQLITE_BUSY retry attempt=${attempt} backoffMs=${Math.round(delayMs)}`
+              );
+            }
           );
+        } finally {
+          this.transactionDepth = 0;
         }
-      );
-    } finally {
-      this.transactionDepth = 0;
-    }
+      })
+    );
   }
   // ─── internals ───────────────────────────────────────────────────────────
   tryLoadSqliteVec(db) {
@@ -4212,8 +4280,20 @@ function createPostgresListenerFromPool(pool, onError) {
 }
 
 // src/storage/providers/postgres.ts
-var txStore = new async_hooks.AsyncLocalStorage();
 var warnLogger2 = new WolbargLogger("warn");
+function isRetriablePgTxError(error) {
+  const code = error && typeof error === "object" && "code" in error ? String(error.code ?? "") : "";
+  if (code === "40P01" || code === "40001") {
+    return true;
+  }
+  const msg = error instanceof Error ? error.message : String(error);
+  return /deadlock detected|could not serialize access/i.test(msg);
+}
+function pgTxBackoffMs(attempt) {
+  const base = 25 * 2 ** attempt;
+  const jitter = Math.random() * 25;
+  return Math.min(1e3, base + jitter);
+}
 var warnedPgvectorFallback = false;
 var warnedFtsKeywordSearch2 = false;
 var warnedHnswSoftFail = false;
@@ -4258,7 +4338,11 @@ function withPoolStartupOptions(connectionString, durableWrites) {
     "-c jit=off",
     // Bake HNSW search GUCs into the connection — avoids per-recall set_config.
     "-c hnsw.ef_search=40",
-    "-c hnsw.iterative_scan=relaxed_order"
+    "-c hnsw.iterative_scan=relaxed_order",
+    // Bound waits so lock storms cannot hang agents indefinitely.
+    "-c statement_timeout=30000",
+    "-c lock_timeout=10000",
+    "-c idle_in_transaction_session_timeout=60000"
   ];
   if (!durableWrites) {
     flags.unshift("-c synchronous_commit=off");
@@ -4339,6 +4423,8 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
   insertFlushScheduled = false;
   insertFlushTimer = null;
   insertFlushInFlight = 0;
+  /** Per-provider TX context — never share across PostgresStorageProvider instances. */
+  txStore = new async_hooks.AsyncLocalStorage();
   /**
    * @param options - Connection string, pool size, and durability flags.
    */
@@ -4638,8 +4724,11 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
   /** Insert a single memory row (coalesced under concurrent writers). */
   async insertMemory(input) {
     this.requireVectorReady();
-    return new Promise((resolve, reject) => {
-      this.insertQueue.push({ input, resolve, reject });
+    if (this.txStore.getStore()) {
+      return this.insertMemoryImmediate(input);
+    }
+    return new Promise((resolve3, reject) => {
+      this.insertQueue.push({ input, resolve: resolve3, reject });
       if (this.insertQueue.length >= COALESCE_FLUSH_THRESHOLD) {
         this.clearInsertFlushTimer();
         void this.flushInsertQueue();
@@ -4874,10 +4963,18 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
   /** Update memory content, metadata, embedding, and content hash. */
   async updateMemory(input) {
     return this.withTransaction(async () => {
-      const existing = await this.getMemoryById(input.id, input.organization);
-      if (!existing) {
+      const locked = await this.query(
+        `SELECT id, organization, agent, content_text, metadata_json,
+                archived::int AS archived, compressed_into, content_hash, created_at, updated_at
+         FROM memories
+         WHERE id = $1 AND organization = $2
+         FOR UPDATE`,
+        [input.id, input.organization]
+      );
+      if (locked.rows.length === 0) {
         return null;
       }
+      const existing = this.mapRow(locked.rows[0]);
       const contentHash = input.contentHash !== void 0 ? input.contentHash : input.contentText !== void 0 ? hashMemoryContent(input.contentText) : existing.content_hash ?? null;
       await this.query(
         `UPDATE memories SET
@@ -5195,23 +5292,38 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
       if (ids.length === 0) {
         return [];
       }
+      const orderedIds = [...new Set(ids)].sort();
+      await this.query(
+        `SELECT id FROM memories
+         WHERE organization = $1 AND archived = false AND id = ANY($2::text[])
+         ORDER BY id
+         FOR UPDATE`,
+        [organization, orderedIds]
+      );
       const result = await this.query(
         `UPDATE memories
          SET archived = true, compressed_into = $1, updated_at = $2
          WHERE organization = $3 AND archived = false AND id = ANY($4::text[])
          RETURNING id`,
-        [compressedIntoId, archivedAt, organization, ids]
+        [compressedIntoId, archivedAt, organization, orderedIds]
       );
       const archived = result.rows.map((r) => String(r.id));
       if (archived.length === 0) {
         return [];
       }
-      await this.query(
-        `UPDATE memory_embeddings
-         SET archived = true
-         WHERE memory_id = ANY($1::text[])`,
-        [archived]
-      );
+      if (this.hasPgvector) {
+        await this.query(
+          `UPDATE memory_embeddings
+           SET archived = true
+           WHERE memory_id = ANY($1::text[])`,
+          [archived]
+        );
+      } else {
+        await this.query(
+          `DELETE FROM memory_embeddings_blob WHERE memory_id = ANY($1::text[])`,
+          [archived]
+        );
+      }
       const histIds = [];
       const memIds = [];
       const types = [];
@@ -5314,27 +5426,40 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     return Number(result.rows[0]?.size ?? 0);
   }
   async withTransaction(fn) {
-    const existing = txStore.getStore();
+    const existing = this.txStore.getStore();
     if (existing) {
       return fn();
     }
-    const client = await this.requirePool().connect();
-    try {
-      await client.query("BEGIN");
-      const result = await txStore.run(client, fn);
-      await client.query("COMMIT");
-      return result;
-    } catch (error) {
-      await client.query("ROLLBACK").catch(() => void 0);
-      if (error instanceof DatabaseError || error instanceof InitializationError) {
-        throw error;
+    const maxAttempts = 5;
+    let lastError;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+      const client = await this.requirePool().connect();
+      try {
+        await client.query("BEGIN");
+        const result = await this.txStore.run(client, fn);
+        await client.query("COMMIT");
+        return result;
+      } catch (error) {
+        await client.query("ROLLBACK").catch(() => void 0);
+        lastError = error;
+        if (isRetriablePgTxError(error) && attempt < maxAttempts - 1) {
+          await new Promise((r) => setTimeout(r, pgTxBackoffMs(attempt)));
+          continue;
+        }
+        if (error instanceof DatabaseError || error instanceof InitializationError) {
+          throw error;
+        }
+        throw new DatabaseError(`Transaction failed: ${this.describe(error)}`, {
+          cause: error instanceof Error ? error : void 0
+        });
+      } finally {
+        client.release();
       }
-      throw new DatabaseError(`Transaction failed: ${this.describe(error)}`, {
-        cause: error instanceof Error ? error : void 0
-      });
-    } finally {
-      client.release();
     }
+    throw new DatabaseError(
+      `Transaction failed after retries: ${this.describe(lastError)}`,
+      { cause: lastError instanceof Error ? lastError : void 0 }
+    );
   }
   async runMigrations() {
     await this.query(`
@@ -5562,13 +5687,13 @@ var PostgresStorageProvider = class _PostgresStorageProvider {
     await this.query(`DELETE FROM memory_embeddings_blob WHERE memory_id = $1`, [memoryId]).catch(() => void 0);
   }
   async query(text, params) {
-    const tx = txStore.getStore();
+    const tx = this.txStore.getStore();
     const target = tx ?? this.requirePool();
     return target.query(text, params);
   }
   /** Named prepared statement — parse/plan cached per pool connection. */
   async queryNamed(name, text, params) {
-    const tx = txStore.getStore();
+    const tx = this.txStore.getStore();
     const target = tx ?? this.requirePool();
     return target.query({ name, text, values: params });
   }
@@ -5654,7 +5779,7 @@ function createDatabaseProvider(config) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.5.5";
+var SDK_VERSION = "0.5.6";
 
 // src/memory/transfer.ts
 var warnedMissingExportManifest = false;
@@ -9610,12 +9735,18 @@ var Wolbarg = class {
             createdAt: timestamp,
             updatedAt: timestamp
           });
+          const sourceIds = [...records.map((r) => r.id)].sort();
           const archivedIds = await storage.archiveMemories(
-            records.map((r) => r.id),
+            sourceIds,
             organization,
             summaryId,
             timestamp
           );
+          if (archivedIds.length < 2) {
+            throw new ValidationError(
+              "compress lost a concurrency race: fewer than 2 source memories remained active"
+            );
+          }
           return {
             summary: toMemoryRecord(summaryRow),
             archivedIds
@@ -10627,8 +10758,11 @@ var meta = {
 };
 
 // src/factories/index.ts
-function sqlite(connectionString) {
-  return new SqliteStorageProvider({ connectionString });
+function sqlite(connectionString, options) {
+  return new SqliteStorageProvider({
+    connectionString,
+    concurrency: options?.concurrency
+  });
 }
 function sqliteConfig(connectionString) {
   return {
@@ -11145,9 +11279,279 @@ function percentile(sorted, p) {
   return sorted[idx];
 }
 
+// src/config/providers.ts
+var EMBEDDING_PROVIDER_PRESETS = [
+  {
+    id: "openai",
+    label: "OpenAI",
+    defaultBaseUrl: "https://api.openai.com/v1",
+    defaultModel: "text-embedding-3-small",
+    apiKeyEnv: "OPENAI_API_KEY"
+  },
+  {
+    id: "ollama",
+    label: "Ollama (local)",
+    defaultBaseUrl: "http://127.0.0.1:11434/v1",
+    defaultModel: "nomic-embed-text",
+    apiKeyEnv: "OLLAMA_API_KEY",
+    apiKeyHint: "Any non-empty value works locally (e.g. ollama)"
+  },
+  {
+    id: "openrouter",
+    label: "OpenRouter",
+    defaultBaseUrl: "https://openrouter.ai/api/v1",
+    defaultModel: "openai/text-embedding-3-small",
+    apiKeyEnv: "OPENROUTER_API_KEY"
+  },
+  {
+    id: "lmstudio",
+    label: "LM Studio (local)",
+    defaultBaseUrl: "http://127.0.0.1:1234/v1",
+    defaultModel: "text-embedding-nomic-embed-text-v1.5",
+    apiKeyEnv: "LM_STUDIO_API_KEY",
+    apiKeyHint: "Often unused locally \u2014 any non-empty value is fine"
+  },
+  {
+    id: "gemini",
+    label: "Google Gemini",
+    defaultBaseUrl: "https://generativelanguage.googleapis.com/v1beta/openai",
+    defaultModel: "text-embedding-004",
+    apiKeyEnv: "GEMINI_API_KEY"
+  },
+  {
+    id: "together",
+    label: "Together AI",
+    defaultBaseUrl: "https://api.together.xyz/v1",
+    defaultModel: "togethercomputer/m2-bert-80M-8k-retrieval",
+    apiKeyEnv: "TOGETHER_API_KEY"
+  },
+  {
+    id: "vllm",
+    label: "vLLM (local/server)",
+    defaultBaseUrl: "http://127.0.0.1:8000/v1",
+    defaultModel: "text-embedding-ada-002",
+    apiKeyEnv: "VLLM_API_KEY",
+    apiKeyHint: "Only if your server requires auth"
+  },
+  {
+    id: "custom",
+    label: "Custom OpenAI-compatible",
+    defaultBaseUrl: "https://api.openai.com/v1",
+    defaultModel: "text-embedding-3-small",
+    apiKeyEnv: "WOLBARG_EMBEDDING_API_KEY"
+  }
+];
+function getEmbeddingProviderPreset(id) {
+  return EMBEDDING_PROVIDER_PRESETS.find((p) => p.id === id);
+}
+var DEFAULT_SQLITE_DB_PATH = ".wolbarg/shared-memory/memory.db";
+var DEFAULT_ORGANIZATION = "default";
+var DEFAULT_CONFIG_PATH = ".wolbarg/config.json";
+var DEFAULT_ENV_PATH = ".wolbarg/.env";
+function defaultProjectConfig() {
+  return {
+    version: 1,
+    organization: DEFAULT_ORGANIZATION,
+    database: {
+      provider: "sqlite",
+      url: DEFAULT_SQLITE_DB_PATH
+    },
+    paths: {
+      config: DEFAULT_CONFIG_PATH
+    }
+  };
+}
+function resolveConfigPath(cwd = process.cwd(), configPath) {
+  const rel = configPath ?? DEFAULT_CONFIG_PATH;
+  return path7.isAbsolute(rel) ? rel : path7.resolve(cwd, rel);
+}
+function resolveEnvPath(cwd = process.cwd(), envPath) {
+  const rel = envPath ?? DEFAULT_ENV_PATH;
+  return path7.isAbsolute(rel) ? rel : path7.resolve(cwd, rel);
+}
+function loadProjectConfig(cwd = process.cwd(), configPath) {
+  const full = resolveConfigPath(cwd, configPath);
+  if (!fs6.existsSync(full)) return null;
+  const raw = JSON.parse(fs6.readFileSync(full, "utf8"));
+  if (!raw || raw.version !== 1 || !raw.database?.url) {
+    throw new Error(`Invalid Wolbarg config at ${full}`);
+  }
+  return raw;
+}
+function saveProjectConfig(config, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const configPath = resolveConfigPath(cwd, options.configPath);
+  const dir = path7.dirname(configPath);
+  if (!fs6.existsSync(dir)) fs6.mkdirSync(dir, { recursive: true });
+  if (fs6.existsSync(configPath) && options.overwrite === false) {
+    throw new Error(`Config already exists: ${configPath} (pass --force to overwrite)`);
+  }
+  const toWrite = {
+    ...config,
+    paths: {
+      config: options.configPath ?? DEFAULT_CONFIG_PATH,
+      ...options.envPath || options.apiKey ? { env: options.envPath ?? DEFAULT_ENV_PATH } : config.paths?.env ? { env: config.paths.env } : {}
+    }
+  };
+  fs6.writeFileSync(configPath, `${JSON.stringify(toWrite, null, 2)}
+`, "utf8");
+  let envPath;
+  if (options.apiKey && config.embedding?.apiKeyEnv) {
+    envPath = resolveEnvPath(cwd, options.envPath);
+    ensureParent(envPath);
+    upsertEnvVar(envPath, config.embedding.apiKeyEnv, options.apiKey);
+    ensureGitignore(cwd, [DEFAULT_ENV_PATH, ".env"]);
+  }
+  if (config.database.provider === "sqlite" && !config.database.url.includes("://")) {
+    const dbPath = path7.isAbsolute(config.database.url) ? config.database.url : path7.resolve(cwd, config.database.url);
+    ensureParent(dbPath);
+  }
+  return { configPath, envPath };
+}
+function ensureParent(filePath) {
+  const dir = path7.dirname(filePath);
+  if (!fs6.existsSync(dir)) fs6.mkdirSync(dir, { recursive: true });
+}
+function upsertEnvVar(envPath, key, value) {
+  ensureParent(envPath);
+  let text = fs6.existsSync(envPath) ? fs6.readFileSync(envPath, "utf8") : "";
+  const line = `${key}=${shellQuoteEnv(value)}`;
+  const re = new RegExp(`^${escapeRegExp(key)}=.*$`, "m");
+  if (re.test(text)) {
+    text = text.replace(re, line);
+  } else {
+    if (text && !text.endsWith("\n")) text += "\n";
+    text += `${line}
+`;
+  }
+  fs6.writeFileSync(envPath, text, "utf8");
+}
+function shellQuoteEnv(value) {
+  if (/[\s#"']/.test(value)) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+  }
+  return value;
+}
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function ensureGitignore(cwd, entries) {
+  const gi = path7.join(cwd, ".gitignore");
+  let text = fs6.existsSync(gi) ? fs6.readFileSync(gi, "utf8") : "";
+  let changed = false;
+  for (const entry of entries) {
+    if (text.split(/\r?\n/).some((l) => l.trim() === entry)) continue;
+    if (text && !text.endsWith("\n")) text += "\n";
+    text += `${entry}
+`;
+    changed = true;
+  }
+  if (changed) fs6.writeFileSync(gi, text, "utf8");
+}
+function resolveEmbeddingApiKey(config, env = process.env) {
+  const name = config.embedding?.apiKeyEnv;
+  if (!name) return "";
+  return env[name] ?? "";
+}
+function assertEmbeddingPreset(provider) {
+  const preset = getEmbeddingProviderPreset(provider);
+  if (!preset) {
+    throw new Error(
+      `Unknown embedding provider "${provider}". Choose one of: ${[
+        "openai",
+        "ollama",
+        "openrouter",
+        "lmstudio",
+        "gemini",
+        "together",
+        "vllm",
+        "custom"
+      ].join(", ")}`
+    );
+  }
+  return preset.id;
+}
+function applyEnvFile(envPath, base = {}) {
+  const out = { ...base };
+  if (!fs6.existsSync(envPath)) return out;
+  const text = fs6.readFileSync(envPath, "utf8");
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq <= 0) continue;
+    const key = line.slice(0, eq).trim();
+    let value = line.slice(eq + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    if (out[key] === void 0) out[key] = value;
+  }
+  return out;
+}
+function projectConfigToWolbargOptions(config, env = process.env) {
+  if (!config.embedding) {
+    throw new Error(
+      "Project config has no embedding section. Re-run `wolbarg init` and configure an embedding provider, or pass embedding explicitly to wolbarg()."
+    );
+  }
+  const apiKey = resolveEmbeddingApiKey(config, env);
+  if (!apiKey) {
+    throw new Error(
+      `Missing API key. Set ${config.embedding.apiKeyEnv} in the environment or in .wolbarg/.env (from wolbarg init).`
+    );
+  }
+  const dbUrl = config.database.url;
+  return {
+    organization: config.organization,
+    database: {
+      provider: config.database.provider,
+      url: dbUrl,
+      connectionString: dbUrl
+    },
+    embedding: {
+      baseUrl: config.embedding.baseUrl,
+      apiKey,
+      model: config.embedding.model
+    }
+  };
+}
+function createWolbargFromProjectConfig(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const config = loadProjectConfig(cwd, options.configPath);
+  if (!config) {
+    throw new Error(
+      `No Wolbarg config found. Run \`wolbarg init\` in ${cwd} (expected .wolbarg/config.json).`
+    );
+  }
+  let env = options.env ?? { ...process.env };
+  if (options.loadEnvFile !== false) {
+    const envFile = resolveEnvPath(
+      cwd,
+      config.paths?.env ?? DEFAULT_ENV_PATH
+    );
+    env = applyEnvFile(envFile, env);
+  }
+  if (options.organization) {
+    config.organization = options.organization;
+  }
+  if (config.database.provider === "sqlite" && !config.database.url.includes("://") && !path7.isAbsolute(config.database.url)) {
+    config.database = {
+      ...config.database,
+      url: path7.resolve(cwd, config.database.url)
+    };
+  }
+  return wolbarg(projectConfigToWolbargOptions(config, env));
+}
+
 exports.CompressionError = CompressionError;
 exports.ConfigurationError = ConfigurationError;
+exports.DEFAULT_CONFIG_PATH = DEFAULT_CONFIG_PATH;
+exports.DEFAULT_ENV_PATH = DEFAULT_ENV_PATH;
+exports.DEFAULT_ORGANIZATION = DEFAULT_ORGANIZATION;
+exports.DEFAULT_SQLITE_DB_PATH = DEFAULT_SQLITE_DB_PATH;
 exports.DatabaseError = DatabaseError;
+exports.EMBEDDING_PROVIDER_PRESETS = EMBEDDING_PROVIDER_PRESETS;
 exports.EmbeddingError = EmbeddingError;
 exports.FixedChunkingStrategy = FixedChunkingStrategy;
 exports.GraphCheckpointNotSupportedError = GraphCheckpointNotSupportedError;
@@ -11175,6 +11579,8 @@ exports.ValidationError = ValidationError;
 exports.Wolbarg = Wolbarg;
 exports.WolbargError = WolbargError;
 exports.WolbargLogger = WolbargLogger;
+exports.applyEnvFile = applyEnvFile;
+exports.assertEmbeddingPreset = assertEmbeddingPreset;
 exports.bgeReranker = bgeReranker;
 exports.bm25 = bm25;
 exports.cohereReranker = cohereReranker;
@@ -11186,11 +11592,15 @@ exports.createLlmProvider = createLlmProvider;
 exports.createStorageProvider = createStorageProvider;
 exports.createTelemetryProvider = createTelemetryProvider;
 exports.createWolbarg = createWolbarg;
+exports.createWolbargFromProjectConfig = createWolbargFromProjectConfig;
 exports.crossEncoder = crossEncoder;
+exports.defaultProjectConfig = defaultProjectConfig;
 exports.geminiEmbedding = geminiEmbedding;
 exports.geminiVision = geminiVision;
+exports.getEmbeddingProviderPreset = getEmbeddingProviderPreset;
 exports.jinaReranker = jinaReranker;
 exports.lmStudioEmbedding = lmStudioEmbedding;
+exports.loadProjectConfig = loadProjectConfig;
 exports.meta = meta;
 exports.neo4jGraph = neo4jGraph;
 exports.ollamaEmbedding = ollamaEmbedding;
@@ -11205,7 +11615,12 @@ exports.openaiReranker = openaiReranker;
 exports.openaiVision = openaiVision;
 exports.postgres = postgres;
 exports.postgresConfig = postgresConfig;
+exports.projectConfigToWolbargOptions = projectConfigToWolbargOptions;
+exports.resolveConfigPath = resolveConfigPath;
+exports.resolveEmbeddingApiKey = resolveEmbeddingApiKey;
+exports.resolveEnvPath = resolveEnvPath;
 exports.runBenchmark = runBenchmark;
+exports.saveProjectConfig = saveProjectConfig;
 exports.sqlite = sqlite;
 exports.sqliteCheckpoint = sqliteCheckpoint;
 exports.sqliteConfig = sqliteConfig;
@@ -11214,6 +11629,7 @@ exports.sqliteTelemetry = sqliteTelemetry;
 exports.summarizeBenchmark = summarizeBenchmark;
 exports.tesseract = tesseract;
 exports.togetherEmbedding = togetherEmbedding;
+exports.upsertEnvVar = upsertEnvVar;
 exports.vllmEmbedding = vllmEmbedding;
 exports.wolbarg = wolbarg;
 exports.wrapOperationError = wrapOperationError;