wolbarg 0.3.0

package/dist/index.cjs

@@ -0,0 +1,4547 @@
+'use strict';
+
+var fs = require('fs/promises');
+var path2 = require("node:path");
+var fs2 = require("node:fs");
+var sqlite$1 = require("node:sqlite");
+var sqliteVec = require('sqlite-vec');
+var async_hooks = require('async_hooks');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var fs__default = /*#__PURE__*/_interopDefault(fs);
+var path2__default = /*#__PURE__*/_interopDefault(path2);
+var fs2__default = /*#__PURE__*/_interopDefault(fs2);
+var sqliteVec__namespace = /*#__PURE__*/_interopNamespace(sqliteVec);
+
+// src/errors/index.ts
+var WolbargError = class extends Error {
+  code;
+  constructor(message, code, options) {
+    super(message, options);
+    this.name = "WolbargError";
+    this.code = code;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var InitializationError = class extends WolbargError {
+  constructor(message, options) {
+    super(message, "INITIALIZATION_ERROR", options);
+    this.name = "InitializationError";
+  }
+};
+var ConfigurationError = class extends WolbargError {
+  constructor(message, options) {
+    super(message, "CONFIGURATION_ERROR", options);
+    this.name = "ConfigurationError";
+  }
+};
+var ValidationError = class extends WolbargError {
+  constructor(message, options) {
+    super(message, "VALIDATION_ERROR", options);
+    this.name = "ValidationError";
+  }
+};
+var DatabaseError = class extends WolbargError {
+  constructor(message, options) {
+    super(message, "DATABASE_ERROR", options);
+    this.name = "DatabaseError";
+  }
+};
+var EmbeddingError = class extends WolbargError {
+  constructor(message, options) {
+    super(message, "EMBEDDING_ERROR", options);
+    this.name = "EmbeddingError";
+  }
+};
+var CompressionError = class extends WolbargError {
+  constructor(message, options) {
+    super(message, "COMPRESSION_ERROR", options);
+    this.name = "CompressionError";
+  }
+};
+var MemoryNotFoundError = class extends WolbargError {
+  constructor(message, options) {
+    super(message, "MEMORY_NOT_FOUND", options);
+    this.name = "MemoryNotFoundError";
+  }
+};
+var ProviderNotConfiguredError = class extends ConfigurationError {
+  provider;
+  constructor(provider, method, hint) {
+    super(
+      `${method} requires ${provider} \u2014 ${hint}`
+    );
+    this.name = "ProviderNotConfiguredError";
+    this.provider = provider;
+  }
+};
+
+// src/compression/index.ts
+var SYSTEM_PROMPT = `You are a memory compression engine for multi-agent systems.
+Given related memories from a single agent, produce ONE concise summary that preserves:
+- Key facts and decisions
+- Important entities, numbers, and identifiers
+- Actionable conclusions
+
+Rules:
+- Output plain text only (no markdown headings, no bullet lists unless essential)
+- Do not invent facts that are not present
+- Prefer precision over verbosity
+- Keep the summary self-contained`;
+var LlmCompressionProvider = class {
+  name = "llm";
+  llm;
+  constructor(llm) {
+    this.llm = llm;
+  }
+  async compress(memories) {
+    return compressMemories(this.llm, memories);
+  }
+};
+async function compressMemories(llm, memories) {
+  if (memories.length === 0) {
+    throw new CompressionError("No memories available to compress");
+  }
+  const payload = memories.map((memory, index) => {
+    const meta2 = Object.keys(memory.metadata).length > 0 ? `
+Metadata: ${JSON.stringify(memory.metadata)}` : "";
+    return `[${index + 1}] (id=${memory.id}, created=${memory.createdAt.toISOString()})${meta2}
+${memory.content.text}`;
+  }).join("\n\n");
+  try {
+    return await llm.complete([
+      { role: "system", content: SYSTEM_PROMPT },
+      {
+        role: "user",
+        content: `Compress the following ${memories.length} memories into a single concise summary:
+
+${payload}`
+      }
+    ]);
+  } catch (error) {
+    if (error instanceof CompressionError) {
+      throw error;
+    }
+    throw new CompressionError(
+      `Compression failed: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error instanceof Error ? error : void 0 }
+    );
+  }
+}
+function createCompressionProvider(llm) {
+  return new LlmCompressionProvider(llm);
+}
+
+// src/chunking/index.ts
+function clampOptions(options) {
+  const chunkSize = Math.max(32, options?.chunkSize ?? 800);
+  const overlap = Math.min(
+    Math.max(0, options?.overlap ?? 100),
+    Math.floor(chunkSize / 2)
+  );
+  return { chunkSize, overlap };
+}
+function windowChunks(pieces, chunkSize, overlap, joiner) {
+  if (pieces.length === 0) {
+    return [];
+  }
+  const chunks = [];
+  let buf = "";
+  let index = 0;
+  const flush = () => {
+    const trimmed = buf.trim();
+    if (trimmed) {
+      chunks.push({ text: trimmed, index });
+      index += 1;
+    }
+  };
+  for (const piece of pieces) {
+    const candidate = buf ? `${buf}${joiner}${piece}` : piece;
+    if (candidate.length <= chunkSize) {
+      buf = candidate;
+      continue;
+    }
+    flush();
+    if (piece.length > chunkSize) {
+      let start = 0;
+      while (start < piece.length) {
+        const end = Math.min(start + chunkSize, piece.length);
+        chunks.push({ text: piece.slice(start, end).trim(), index });
+        index += 1;
+        start = Math.max(end - overlap, end);
+      }
+      buf = "";
+    } else {
+      buf = piece;
+    }
+  }
+  flush();
+  if (overlap > 0 && chunks.length > 1) {
+    const full = pieces.join(joiner);
+    return slidingWindow(full, chunkSize, overlap);
+  }
+  return chunks;
+}
+function slidingWindow(text, chunkSize, overlap) {
+  const chunks = [];
+  let start = 0;
+  let index = 0;
+  while (start < text.length) {
+    const end = Math.min(start + chunkSize, text.length);
+    const slice = text.slice(start, end).trim();
+    if (slice) {
+      chunks.push({ text: slice, index });
+      index += 1;
+    }
+    if (end >= text.length) {
+      break;
+    }
+    start = Math.max(end - overlap, start + 1);
+  }
+  return chunks;
+}
+var FixedChunkingStrategy = class {
+  name = "fixed";
+  chunk(text, options) {
+    const { chunkSize, overlap } = clampOptions(options);
+    return slidingWindow(text, chunkSize, overlap);
+  }
+};
+var SentenceChunkingStrategy = class {
+  name = "sentence";
+  chunk(text, options) {
+    const { chunkSize, overlap } = clampOptions(options);
+    const sentences = text.split(/(?<=[.!?])\s+/).map((s) => s.trim()).filter(Boolean);
+    return windowChunks(sentences, chunkSize, overlap, " ");
+  }
+};
+var ParagraphChunkingStrategy = class {
+  name = "paragraph";
+  chunk(text, options) {
+    const { chunkSize, overlap } = clampOptions(options);
+    const paragraphs = text.split(/\n\s*\n/).map((p) => p.trim()).filter(Boolean);
+    return windowChunks(paragraphs, chunkSize, overlap, "\n\n");
+  }
+};
+var MarkdownChunkingStrategy = class {
+  name = "markdown";
+  chunk(text, options) {
+    const { chunkSize, overlap } = clampOptions(options);
+    const sections = text.split(/(?=^#{1,6}\s)/m).map((s) => s.trim()).filter(Boolean);
+    if (sections.length <= 1) {
+      return new ParagraphChunkingStrategy().chunk(text, options);
+    }
+    return windowChunks(sections, chunkSize, overlap, "\n\n");
+  }
+};
+var HeadingChunkingStrategy = class {
+  name = "heading";
+  chunk(text, options) {
+    return new MarkdownChunkingStrategy().chunk(text, options);
+  }
+};
+function createChunkingStrategy(name = "sentence") {
+  switch (name) {
+    case "fixed":
+      return new FixedChunkingStrategy();
+    case "paragraph":
+      return new ParagraphChunkingStrategy();
+    case "markdown":
+      return new MarkdownChunkingStrategy();
+    case "heading":
+      return new HeadingChunkingStrategy();
+    case "sentence":
+    default:
+      return new SentenceChunkingStrategy();
+  }
+}
+function inferChunkingStrategy(text) {
+  if (/^#{1,6}\s/m.test(text)) {
+    return new MarkdownChunkingStrategy();
+  }
+  return new SentenceChunkingStrategy();
+}
+
+// src/utils/index.ts
+function createId() {
+  return crypto.randomUUID();
+}
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function parseIso(value) {
+  return new Date(value);
+}
+function assertNonEmptyString(value, fieldName) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new ValidationError(`${fieldName} must be a non-empty string`);
+  }
+}
+function assertFiniteNumber(value, fieldName, options) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new ValidationError(`${fieldName} must be a finite number`);
+  }
+  if (options?.min !== void 0 && value < options.min) {
+    throw new ValidationError(`${fieldName} must be >= ${options.min}`);
+  }
+  if (options?.max !== void 0 && value > options.max) {
+    throw new ValidationError(`${fieldName} must be <= ${options.max}`);
+  }
+}
+var EMPTY_META_JSON = "{}";
+function serializeMetadata(metadata) {
+  for (const _key in metadata) {
+    return JSON.stringify(metadata);
+  }
+  return EMPTY_META_JSON;
+}
+function deserializeMetadata(raw) {
+  if (!raw || raw === EMPTY_META_JSON) {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+    return {};
+  } catch {
+    return {};
+  }
+}
+function embeddingToBuffer(embedding) {
+  return Buffer.from(embedding.buffer, embedding.byteOffset, embedding.byteLength);
+}
+function distanceToSimilarity(distance) {
+  return 1 - distance;
+}
+var AsyncMutex = class {
+  chain = Promise.resolve();
+  async runExclusive(fn) {
+    let release;
+    const next = new Promise((resolve) => {
+      release = resolve;
+    });
+    const previous = this.chain;
+    this.chain = previous.then(() => next);
+    await previous;
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
+  }
+};
+function joinUrl(baseUrl, path3) {
+  const base = baseUrl.replace(/\/+$/, "");
+  const suffix = path3.startsWith("/") ? path3 : `/${path3}`;
+  return `${base}${suffix}`;
+}
+
+// src/embedding/index.ts
+var OpenAICompatibleEmbeddingProvider = class {
+  model;
+  baseUrl;
+  apiKey;
+  timeoutMs;
+  constructor(config) {
+    this.baseUrl = config.baseUrl;
+    this.apiKey = config.apiKey;
+    this.model = config.model;
+    this.timeoutMs = config.timeoutMs ?? 3e4;
+  }
+  async embed(text) {
+    const response = await this.request(text);
+    const vector = response.data?.[0]?.embedding;
+    if (!vector || vector.length === 0) {
+      throw new EmbeddingError("Embedding response did not contain a vector");
+    }
+    return Float32Array.from(vector);
+  }
+  async embedBatch(texts) {
+    if (texts.length === 0) {
+      return [];
+    }
+    if (texts.length === 1) {
+      return [await this.embed(texts[0])];
+    }
+    const response = await this.request(texts);
+    const data = response.data ?? [];
+    const sorted = [...data].sort(
+      (a, b) => (a.index ?? 0) - (b.index ?? 0)
+    );
+    if (sorted.length !== texts.length) {
+      const out = [];
+      for (const text of texts) {
+        out.push(await this.embed(text));
+      }
+      return out;
+    }
+    return sorted.map((item) => {
+      if (!item.embedding || item.embedding.length === 0) {
+        throw new EmbeddingError("Embedding batch response contained an empty vector");
+      }
+      return Float32Array.from(item.embedding);
+    });
+  }
+  async validate() {
+    try {
+      const embedding = await this.embed("Wolbarg health check");
+      return { dimensions: embedding.length };
+    } catch (error) {
+      if (error instanceof EmbeddingError) {
+        throw error;
+      }
+      throw new EmbeddingError(
+        `Failed to validate embedding endpoint: ${this.describe(error)}`,
+        { cause: error instanceof Error ? error : void 0 }
+      );
+    }
+  }
+  async request(input) {
+    const url = joinUrl(this.baseUrl, "/embeddings");
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify({
+          model: this.model,
+          input
+        }),
+        signal: controller.signal
+      });
+      let body;
+      try {
+        body = await res.json();
+      } catch {
+        throw new EmbeddingError(
+          `Embedding endpoint returned non-JSON response (HTTP ${res.status})`
+        );
+      }
+      if (!res.ok) {
+        const message = body.error?.message ?? `HTTP ${res.status}`;
+        throw new EmbeddingError(`Embedding request failed: ${message}`);
+      }
+      return body;
+    } catch (error) {
+      if (error instanceof EmbeddingError) {
+        throw error;
+      }
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new EmbeddingError(
+          `Embedding request timed out after ${this.timeoutMs}ms`
+        );
+      }
+      throw new EmbeddingError(
+        `Embedding request failed: ${this.describe(error)}`,
+        { cause: error instanceof Error ? error : void 0 }
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  describe(error) {
+    if (error instanceof Error) {
+      return error.message;
+    }
+    return String(error);
+  }
+};
+function createEmbeddingProvider(config) {
+  return new OpenAICompatibleEmbeddingProvider(config);
+}
+function factory(defaults) {
+  return (config) => createEmbeddingProvider({
+    baseUrl: config.baseUrl ?? defaults.baseUrl,
+    apiKey: config.apiKey,
+    model: config.model,
+    timeoutMs: config.timeoutMs
+  });
+}
+var openaiCompatibleEmbedding = (config) => createEmbeddingProvider(config);
+var openaiEmbedding = factory({
+  baseUrl: "https://api.openai.com/v1"
+});
+var ollamaEmbedding = factory({
+  baseUrl: "http://127.0.0.1:11434/v1"
+});
+var openRouterEmbedding = factory({
+  baseUrl: "https://openrouter.ai/api/v1"
+});
+var lmStudioEmbedding = factory({
+  baseUrl: "http://127.0.0.1:1234/v1"
+});
+var geminiEmbedding = factory({
+  baseUrl: "https://generativelanguage.googleapis.com/v1beta/openai"
+});
+var togetherEmbedding = factory({
+  baseUrl: "https://api.together.xyz/v1"
+});
+var vllmEmbedding = factory({
+  baseUrl: "http://127.0.0.1:8000/v1"
+});
+async function embedMany(provider, texts, concurrency = 8) {
+  if (provider.embedBatch) {
+    return provider.embedBatch(texts);
+  }
+  const out = new Array(texts.length);
+  let index = 0;
+  async function worker() {
+    while (index < texts.length) {
+      const current = index;
+      index += 1;
+      out[current] = await provider.embed(texts[current]);
+    }
+  }
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, texts.length) }, () => worker())
+  );
+  return out;
+}
+
+// src/llm/index.ts
+var OpenAICompatibleLlmProvider = class {
+  model;
+  baseUrl;
+  apiKey;
+  temperature;
+  maxTokens;
+  timeoutMs;
+  constructor(config) {
+    this.baseUrl = config.baseUrl;
+    this.apiKey = config.apiKey;
+    this.model = config.model;
+    this.temperature = config.temperature ?? 0.2;
+    this.maxTokens = config.maxTokens ?? 4096;
+    this.timeoutMs = config.timeoutMs ?? 6e4;
+  }
+  async complete(messages) {
+    const response = await this.request(messages);
+    const content = response.choices?.[0]?.message?.content;
+    if (typeof content !== "string" || content.trim().length === 0) {
+      throw new CompressionError("LLM response did not contain text content");
+    }
+    return content.trim();
+  }
+  async validate() {
+    try {
+      await this.complete([
+        {
+          role: "user",
+          content: 'Reply with exactly the word "ok".'
+        }
+      ]);
+    } catch (error) {
+      if (error instanceof CompressionError) {
+        throw new CompressionError(
+          `Failed to validate LLM endpoint: ${error.message}`,
+          { cause: error }
+        );
+      }
+      throw new CompressionError(
+        `Failed to validate LLM endpoint: ${this.describe(error)}`,
+        { cause: error instanceof Error ? error : void 0 }
+      );
+    }
+  }
+  async request(messages) {
+    const url = joinUrl(this.baseUrl, "/chat/completions");
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify({
+          model: this.model,
+          messages,
+          temperature: this.temperature,
+          max_tokens: this.maxTokens
+        }),
+        signal: controller.signal
+      });
+      let body;
+      try {
+        body = await res.json();
+      } catch {
+        throw new CompressionError(
+          `LLM endpoint returned non-JSON response (HTTP ${res.status})`
+        );
+      }
+      if (!res.ok) {
+        const message = body.error?.message ?? `HTTP ${res.status}`;
+        throw new CompressionError(`LLM request failed: ${message}`);
+      }
+      return body;
+    } catch (error) {
+      if (error instanceof CompressionError) {
+        throw error;
+      }
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new CompressionError(
+          `LLM request timed out after ${this.timeoutMs}ms`
+        );
+      }
+      throw new CompressionError(`LLM request failed: ${this.describe(error)}`, {
+        cause: error instanceof Error ? error : void 0
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  describe(error) {
+    if (error instanceof Error) {
+      return error.message;
+    }
+    return String(error);
+  }
+};
+function createLlmProvider(config) {
+  return new OpenAICompatibleLlmProvider(config);
+}
+function llmFactory(defaults) {
+  return (config) => createLlmProvider({
+    baseUrl: config.baseUrl ?? defaults.baseUrl,
+    apiKey: config.apiKey,
+    model: config.model,
+    temperature: config.temperature,
+    maxTokens: config.maxTokens,
+    timeoutMs: config.timeoutMs
+  });
+}
+var openaiCompatibleLlm = (config) => createLlmProvider(config);
+var openaiLlm = llmFactory({
+  baseUrl: "https://api.openai.com/v1"
+});
+var ollamaLlm = llmFactory({
+  baseUrl: "http://127.0.0.1:11434/v1"
+});
+var openRouterLlm = llmFactory({
+  baseUrl: "https://openrouter.ai/api/v1"
+});
+function extOf(filename) {
+  if (!filename) {
+    return "";
+  }
+  return path2__default.default.extname(filename).toLowerCase();
+}
+var TextParser = class {
+  name = "text";
+  extensions = [".txt", ".md", ".markdown", ".csv", ".json"];
+  async parse(input) {
+    const ext = extOf(input.filename);
+    let text = input.buffer.toString("utf8");
+    if (ext === ".json") {
+      try {
+        text = JSON.stringify(JSON.parse(text), null, 2);
+      } catch {
+      }
+    }
+    return {
+      text,
+      mimeType: input.mimeType ?? "text/plain",
+      filename: input.filename,
+      isImage: false
+    };
+  }
+};
+var ImageParser = class {
+  name = "image";
+  extensions = [".png", ".jpg", ".jpeg", ".webp"];
+  async parse(input) {
+    const ext = extOf(input.filename);
+    const mime = input.mimeType ?? (ext === ".png" ? "image/png" : ext === ".webp" ? "image/webp" : "image/jpeg");
+    return {
+      text: "",
+      mimeType: mime,
+      filename: input.filename,
+      isImage: true,
+      imageBuffer: input.buffer
+    };
+  }
+};
+var PdfParser = class {
+  name = "pdf";
+  extensions = [".pdf"];
+  async parse(input) {
+    try {
+      const mod = await import('pdf-parse');
+      const maybeClass = mod.PDFParse;
+      let text = "";
+      if (typeof maybeClass === "function") {
+        const parser = new maybeClass({ data: input.buffer });
+        try {
+          const result = await parser.getText();
+          text = result.text ?? "";
+        } finally {
+          await parser.destroy?.();
+        }
+      } else {
+        const pdfParse = mod.default ?? mod;
+        if (typeof pdfParse !== "function") {
+          throw new Error("pdf-parse export is not a function");
+        }
+        const result = await pdfParse(input.buffer);
+        text = result.text ?? "";
+      }
+      return {
+        text,
+        mimeType: "application/pdf",
+        filename: input.filename,
+        isImage: false
+      };
+    } catch (error) {
+      if (error instanceof ConfigurationError) {
+        throw error;
+      }
+      const detail = error instanceof Error ? error.message : String(error);
+      throw new ConfigurationError(
+        `PDF ingest failed (${detail}). Install compatible pdf-parse: npm install pdf-parse@1.1.4`,
+        { cause: error instanceof Error ? error : void 0 }
+      );
+    }
+  }
+};
+var DocxParser = class {
+  name = "docx";
+  extensions = [".docx"];
+  async parse(input) {
+    try {
+      const mod = await import('mammoth');
+      const extractRawText = mod.extractRawText ?? mod.default?.extractRawText;
+      if (!extractRawText) {
+        throw new Error("mammoth.extractRawText unavailable");
+      }
+      const result = await extractRawText({ buffer: input.buffer });
+      return {
+        text: result.value ?? "",
+        mimeType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        filename: input.filename,
+        isImage: false
+      };
+    } catch {
+      throw new ConfigurationError(
+        'DOCX ingest requires the optional "mammoth" package. Install it with: npm install mammoth'
+      );
+    }
+  }
+};
+var DEFAULT_PARSERS = [
+  new TextParser(),
+  new ImageParser(),
+  new PdfParser(),
+  new DocxParser()
+];
+function resolveParser(filename, mimeType, parsers = DEFAULT_PARSERS) {
+  const ext = extOf(filename);
+  if (ext) {
+    const byExt = parsers.find((p) => p.extensions.includes(ext));
+    if (byExt) {
+      return byExt;
+    }
+  }
+  if (mimeType?.startsWith("image/")) {
+    return parsers.find((p) => p.name === "image") ?? new ImageParser();
+  }
+  if (mimeType === "application/pdf") {
+    return parsers.find((p) => p.name === "pdf") ?? new PdfParser();
+  }
+  return parsers.find((p) => p.name === "text") ?? new TextParser();
+}
+async function loadIngestSource(source) {
+  if (source.text !== void 0) {
+    return {
+      buffer: Buffer.from(source.text, "utf8"),
+      filename: source.filename ?? "document.txt",
+      mimeType: source.mimeType ?? "text/plain",
+      rawText: source.text
+    };
+  }
+  if (source.buffer) {
+    return {
+      buffer: source.buffer,
+      filename: source.filename,
+      mimeType: source.mimeType
+    };
+  }
+  if (source.path) {
+    const buffer = await fs__default.default.readFile(source.path);
+    return {
+      buffer,
+      filename: path2__default.default.basename(source.path),
+      mimeType: source.mimeType
+    };
+  }
+  throw new ConfigurationError("ingest source must include path, buffer, or text");
+}
+
+// src/filters/match.ts
+function getField(metadata, field) {
+  const parts = field.split(".");
+  let current = metadata;
+  for (const part of parts) {
+    if (current === null || typeof current !== "object" || Array.isArray(current)) {
+      return void 0;
+    }
+    current = current[part];
+  }
+  return current;
+}
+function compare(value, op) {
+  if ("eq" in op) {
+    return value === op.eq;
+  }
+  if ("contains" in op) {
+    if (typeof value === "string") {
+      return value.includes(op.contains);
+    }
+    if (Array.isArray(value)) {
+      return value.some((item) => String(item).includes(op.contains));
+    }
+    return false;
+  }
+  if ("gt" in op) {
+    return value != null && value > op.gt;
+  }
+  if ("gte" in op) {
+    return value != null && value >= op.gte;
+  }
+  if ("lt" in op) {
+    return value != null && value < op.lt;
+  }
+  if ("lte" in op) {
+    return value != null && value <= op.lte;
+  }
+  if ("between" in op) {
+    const [lo, hi] = op.between;
+    return value != null && value >= lo && value <= hi;
+  }
+  return false;
+}
+function matchesMetadata(metadata, filter) {
+  if ("and" in filter) {
+    return filter.and.every((f) => matchesMetadata(metadata, f));
+  }
+  if ("or" in filter) {
+    return filter.or.some((f) => matchesMetadata(metadata, f));
+  }
+  if ("not" in filter) {
+    return !matchesMetadata(metadata, filter.not);
+  }
+  return compare(getField(metadata, filter.field), filter.op);
+}
+
+// src/schema/index.ts
+var SCHEMA_VERSION = 2;
+var META_KEYS = {
+  schemaVersion: "schema_version",
+  embeddingDimensions: "embedding_dimensions",
+  vectorBackend: "vector_backend"
+};
+var CREATE_META_TABLE = `
+CREATE TABLE IF NOT EXISTS Wolbarg_meta (
+  key TEXT PRIMARY KEY NOT NULL,
+  value TEXT NOT NULL
+);
+`;
+var CREATE_MEMORIES_TABLE = `
+CREATE TABLE IF NOT EXISTS memories (
+  id TEXT PRIMARY KEY NOT NULL,
+  organization TEXT NOT NULL,
+  agent TEXT NOT NULL,
+  content_text TEXT NOT NULL,
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  archived INTEGER NOT NULL DEFAULT 0 CHECK (archived IN (0, 1)),
+  compressed_into TEXT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  FOREIGN KEY (compressed_into) REFERENCES memories(id) ON DELETE SET NULL
+);
+`;
+var CREATE_HISTORY_TABLE = `
+CREATE TABLE IF NOT EXISTS memory_history (
+  id TEXT PRIMARY KEY NOT NULL,
+  memory_id TEXT NOT NULL,
+  event_type TEXT NOT NULL CHECK (event_type IN ('created', 'archived', 'compressed')),
+  related_memory_id TEXT NULL,
+  created_at TEXT NOT NULL,
+  FOREIGN KEY (memory_id) REFERENCES memories(id) ON DELETE CASCADE
+);
+`;
+var CREATE_BLOB_EMBEDDINGS_TABLE = `
+CREATE TABLE IF NOT EXISTS memory_embeddings_blob (
+  memory_rowid INTEGER PRIMARY KEY NOT NULL,
+  embedding BLOB NOT NULL
+);
+`;
+var CREATE_FTS_TABLE = `
+CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+  content_text,
+  memory_id UNINDEXED,
+  organization UNINDEXED,
+  agent UNINDEXED,
+  tokenize = 'porter unicode61'
+);
+`;
+var CREATE_INDEXES = [
+  `CREATE INDEX IF NOT EXISTS idx_memories_org_agent ON memories(organization, agent);`,
+  `CREATE INDEX IF NOT EXISTS idx_memories_org_archived ON memories(organization, archived);`,
+  /** Active-set covering path for org-scoped list / stats / compress. */
+  `CREATE INDEX IF NOT EXISTS idx_memories_org_active_created
+     ON memories(organization, created_at) WHERE archived = 0;`,
+  `CREATE INDEX IF NOT EXISTS idx_memories_created_at ON memories(created_at);`,
+  `CREATE INDEX IF NOT EXISTS idx_history_memory_id ON memory_history(memory_id);`
+];
+function buildVectorTableSql(dimensions) {
+  if (!Number.isInteger(dimensions) || dimensions <= 0) {
+    throw new Error(`Invalid embedding dimensions: ${dimensions}`);
+  }
+  return `
+CREATE VIRTUAL TABLE IF NOT EXISTS memory_embeddings USING vec0(
+  memory_rowid INTEGER PRIMARY KEY,
+  embedding float[${dimensions}] distance_metric=cosine
+);
+`;
+}
+
+// src/sql/index.ts
+var SQL = {
+  getMeta: `SELECT value FROM Wolbarg_meta WHERE key = ?`,
+  setMeta: `
+    INSERT INTO Wolbarg_meta (key, value) VALUES (?, ?)
+    ON CONFLICT(key) DO UPDATE SET value = excluded.value
+  `,
+  insertMemory: `
+    INSERT INTO memories (
+      id, organization, agent, content_text, metadata_json,
+      archived, compressed_into, created_at, updated_at
+    ) VALUES (?, ?, ?, ?, ?, 0, NULL, ?, ?)
+    RETURNING rowid, id, organization, agent, content_text, metadata_json,
+              archived, compressed_into, created_at, updated_at
+  `,
+  getMemoryById: `
+    SELECT rowid, id, organization, agent, content_text, metadata_json,
+           archived, compressed_into, created_at, updated_at
+    FROM memories
+    WHERE id = ? AND organization = ?
+  `,
+  getMemoryByRowid: `
+    SELECT rowid, id, organization, agent, content_text, metadata_json,
+           archived, compressed_into, created_at, updated_at
+    FROM memories
+    WHERE rowid = ? AND organization = ?
+  `,
+  getMemoriesByRowidsPrefix: `
+    SELECT rowid, id, organization, agent, content_text, metadata_json,
+           archived, compressed_into, created_at, updated_at
+    FROM memories
+    WHERE organization = ? AND rowid IN (
+  `,
+  listMemoriesBase: `
+    SELECT rowid, id, organization, agent, content_text, metadata_json,
+           archived, compressed_into, created_at, updated_at
+    FROM memories
+    WHERE organization = ?
+  `,
+  insertEmbedding: `
+    INSERT INTO memory_embeddings (memory_rowid, embedding) VALUES (?, ?)
+  `,
+  deleteEmbedding: `
+    DELETE FROM memory_embeddings WHERE memory_rowid = ?
+  `,
+  searchVectors: `
+    SELECT memory_rowid, distance
+    FROM memory_embeddings
+    WHERE embedding MATCH ?
+      AND k = ?
+  `,
+  insertEmbeddingBlob: `
+    INSERT INTO memory_embeddings_blob (memory_rowid, embedding) VALUES (?, ?)
+  `,
+  deleteEmbeddingBlob: `
+    DELETE FROM memory_embeddings_blob WHERE memory_rowid = ?
+  `,
+  listEmbeddingsBlob: `
+    SELECT memory_rowid, embedding FROM memory_embeddings_blob
+  `,
+  archiveMemory: `
+    UPDATE memories
+    SET archived = 1,
+        compressed_into = ?,
+        updated_at = ?
+    WHERE id = ? AND organization = ? AND archived = 0
+  `,
+  deleteMemoryById: `
+    DELETE FROM memories WHERE id = ? AND organization = ?
+  `,
+  deleteMemoriesByOrg: `
+    DELETE FROM memories WHERE organization = ?
+  `,
+  deleteMemoriesByOrgAgent: `
+    DELETE FROM memories WHERE organization = ? AND agent = ?
+  `,
+  insertHistory: `
+    INSERT INTO memory_history (id, memory_id, event_type, related_memory_id, created_at)
+    VALUES (?, ?, ?, ?, ?)
+  `,
+  getHistory: `
+    SELECT id, memory_id, event_type, related_memory_id, created_at
+    FROM memory_history
+    WHERE memory_id = ?
+    ORDER BY created_at ASC
+  `,
+  countMemories: `
+    SELECT COUNT(*) AS count FROM memories WHERE organization = ?
+  `,
+  countActiveMemories: `
+    SELECT COUNT(*) AS count FROM memories WHERE organization = ? AND archived = 0
+  `,
+  countArchivedMemories: `
+    SELECT COUNT(*) AS count FROM memories WHERE organization = ? AND archived = 1
+  `,
+  countAgents: `
+    SELECT COUNT(DISTINCT agent) AS count FROM memories WHERE organization = ? AND archived = 0
+  `,
+  /** FTS ranked by BM25 (archived rows are deleted from FTS on archive). */
+  searchFts: `
+    SELECT memory_id, bm25(memories_fts) AS rank
+    FROM memories_fts
+    WHERE memories_fts MATCH ?
+      AND organization = ?
+    ORDER BY rank
+    LIMIT ?
+  `,
+  listRowidsForOrg: `
+    SELECT rowid FROM memories WHERE organization = ?
+  `,
+  listRowidsForOrgAgent: `
+    SELECT rowid FROM memories WHERE organization = ? AND agent = ?
+  `,
+  vectorTableExists: `
+    SELECT name FROM sqlite_master
+    WHERE type = 'table' AND name = 'memory_embeddings'
+  `,
+  updateMemoryContent: `
+    UPDATE memories
+    SET content_text = COALESCE(?, content_text),
+        metadata_json = COALESCE(?, metadata_json),
+        updated_at = ?
+    WHERE id = ? AND organization = ?
+  `,
+  insertFts: `
+    INSERT INTO memories_fts (content_text, memory_id, organization, agent)
+    VALUES (?, ?, ?, ?)
+  `,
+  deleteFts: `
+    DELETE FROM memories_fts WHERE memory_id = ?
+  `
+};
+
+// src/utils/vector.ts
+function cosineDistance(a, b) {
+  const len = Math.min(a.length, b.length);
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < len; i += 1) {
+    const av = a[i] ?? 0;
+    const bv = b[i] ?? 0;
+    dot += av * bv;
+    normA += av * av;
+    normB += bv * bv;
+  }
+  if (normA === 0 || normB === 0) {
+    return 1;
+  }
+  const similarity = dot / (Math.sqrt(normA) * Math.sqrt(normB));
+  return 1 - similarity;
+}
+function bufferToEmbedding(data) {
+  const byteOffset = data.byteOffset ?? 0;
+  const byteLength = data.byteLength;
+  if (byteOffset % Float32Array.BYTES_PER_ELEMENT === 0) {
+    return new Float32Array(
+      data.buffer,
+      byteOffset,
+      byteLength / Float32Array.BYTES_PER_ELEMENT
+    );
+  }
+  const copy = new Uint8Array(byteLength);
+  copy.set(data);
+  return new Float32Array(copy.buffer);
+}
+
+// src/utils/vector-index.ts
+var InMemoryVectorIndex = class {
+  dims;
+  rowids = [];
+  data;
+  count = 0;
+  rowidToSlot = /* @__PURE__ */ new Map();
+  constructor(dimensions, initialCapacity = 256) {
+    this.dims = dimensions;
+    this.data = new Float32Array(initialCapacity * dimensions);
+  }
+  get size() {
+    return this.count;
+  }
+  clear() {
+    this.rowids.length = 0;
+    this.rowidToSlot.clear();
+    this.count = 0;
+  }
+  upsert(rowid, embedding) {
+    const existing = this.rowidToSlot.get(rowid);
+    const slot = existing !== void 0 ? existing : (() => {
+      this.ensureCapacity(this.count + 1);
+      const s = this.count;
+      this.rowids[s] = rowid;
+      this.rowidToSlot.set(rowid, s);
+      this.count += 1;
+      return s;
+    })();
+    const dims = this.dims;
+    const base = slot * dims;
+    const data = this.data;
+    const len = embedding.length < dims ? embedding.length : dims;
+    let norm = 0;
+    for (let i = 0; i < len; i += 1) {
+      const v = embedding[i];
+      data[base + i] = v;
+      norm += v * v;
+    }
+    for (let i = len; i < dims; i += 1) {
+      data[base + i] = 0;
+    }
+    if (norm > 0) {
+      const inv = 1 / Math.sqrt(norm);
+      for (let i = 0; i < len; i += 1) {
+        data[base + i] *= inv;
+      }
+    }
+  }
+  remove(rowid) {
+    const slot = this.rowidToSlot.get(rowid);
+    if (slot === void 0) {
+      return;
+    }
+    const last = this.count - 1;
+    if (slot !== last) {
+      const lastRowid = this.rowids[last];
+      this.data.copyWithin(
+        slot * this.dims,
+        last * this.dims,
+        (last + 1) * this.dims
+      );
+      this.rowids[slot] = lastRowid;
+      this.rowidToSlot.set(lastRowid, slot);
+    }
+    this.rowidToSlot.delete(rowid);
+    this.count = last;
+  }
+  /** Top-k by cosine distance (1 - dot) assuming query is L2-normalized. */
+  search(queryNormalized, topK) {
+    const n = this.count;
+    if (n === 0 || topK <= 0) {
+      return [];
+    }
+    const dims = this.dims;
+    const data = this.data;
+    const rowids = this.rowids;
+    const k = topK < n ? topK : n;
+    const heapDist = new Float64Array(k);
+    const heapRow = new Int32Array(k);
+    let heapSize = 0;
+    for (let i = 0; i < n; i += 1) {
+      const base = i * dims;
+      let dot = 0;
+      let d = 0;
+      for (; d + 3 < dims; d += 4) {
+        dot += queryNormalized[d] * data[base + d] + queryNormalized[d + 1] * data[base + d + 1] + queryNormalized[d + 2] * data[base + d + 2] + queryNormalized[d + 3] * data[base + d + 3];
+      }
+      for (; d < dims; d += 1) {
+        dot += queryNormalized[d] * data[base + d];
+      }
+      const distance = 1 - dot;
+      if (heapSize < k) {
+        heapDist[heapSize] = distance;
+        heapRow[heapSize] = rowids[i];
+        heapSize += 1;
+        if (heapSize === k) {
+          buildMaxHeap(heapDist, heapRow, k);
+        }
+      } else if (distance < heapDist[0]) {
+        heapDist[0] = distance;
+        heapRow[0] = rowids[i];
+        siftDown(heapDist, heapRow, 0, k);
+      }
+    }
+    const hits = new Array(heapSize);
+    for (let i = 0; i < heapSize; i += 1) {
+      hits[i] = { memoryRowid: heapRow[i], distance: heapDist[i] };
+    }
+    hits.sort((a, b) => a.distance - b.distance);
+    return hits;
+  }
+  ensureCapacity(needed) {
+    if (needed * this.dims <= this.data.length) {
+      return;
+    }
+    let cap = this.data.length / this.dims;
+    if (cap < 1) cap = 1;
+    while (cap < needed) cap *= 2;
+    const next = new Float32Array(cap * this.dims);
+    next.set(this.data.subarray(0, this.count * this.dims));
+    this.data = next;
+  }
+};
+function normalizeEmbedding(embedding, dims = embedding.length) {
+  return normalizeInto(embedding, dims);
+}
+function normalizeInto(embedding, dims) {
+  const out = new Float32Array(dims);
+  const len = embedding.length < dims ? embedding.length : dims;
+  let norm = 0;
+  for (let i = 0; i < len; i += 1) {
+    const v = embedding[i];
+    out[i] = v;
+    norm += v * v;
+  }
+  if (norm === 0) {
+    return out;
+  }
+  const inv = 1 / Math.sqrt(norm);
+  for (let i = 0; i < len; i += 1) {
+    out[i] *= inv;
+  }
+  return out;
+}
+function buildMaxHeap(dist, rows, n) {
+  for (let i = (n >> 1) - 1; i >= 0; i -= 1) {
+    siftDown(dist, rows, i, n);
+  }
+}
+function siftDown(dist, rows, i, n) {
+  for (; ; ) {
+    let largest = i;
+    const left = (i << 1) + 1;
+    const right = left + 1;
+    if (left < n && dist[left] > dist[largest]) largest = left;
+    if (right < n && dist[right] > dist[largest]) largest = right;
+    if (largest === i) return;
+    const td = dist[i];
+    dist[i] = dist[largest];
+    dist[largest] = td;
+    const tr = rows[i];
+    rows[i] = rows[largest];
+    rows[largest] = tr;
+    i = largest;
+  }
+}
+
+// src/storage/providers/sqlite.ts
+var SqliteStorageProvider = class {
+  name = "sqlite";
+  connectionString;
+  db = null;
+  statements = null;
+  vectorDimensions = null;
+  vectorBackend = null;
+  sqliteVecLoaded = false;
+  /** Hot in-process ANN for blob backend (sqlite-vec unavailable platforms). */
+  memoryIndex = null;
+  memoryIndexDirty = false;
+  /** Resolved absolute path (or `:memory:`) — avoid re-resolving on size checks. */
+  resolvedPath = null;
+  constructor(options) {
+    this.connectionString = options.connectionString;
+  }
+  async open() {
+    try {
+      const dbPath = this.resolvePath(this.connectionString);
+      this.resolvedPath = dbPath;
+      if (dbPath !== ":memory:") {
+        fs2__default.default.mkdirSync(path2__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 = 5000;
+        PRAGMA temp_store = MEMORY;
+        PRAGMA cache_size = -65536;
+        PRAGMA mmap_size = 268435456;
+        PRAGMA wal_autocheckpoint = 1000;
+        PRAGMA recursive_triggers = OFF;
+      `);
+      this.sqliteVecLoaded = this.tryLoadSqliteVec(db);
+      this.runMigrations(db);
+      this.statements = this.prepareStatements(db);
+      this.ensureFtsConsistency(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 {
+        this.vectorBackend = "blob";
+      }
+      if (dims !== null) {
+        this.vectorDimensions = dims;
+        this.ensureVectorStorage(dims);
+        this.reprepareVectorStatements();
+        if (this.vectorBackend === "blob") {
+          this.memoryIndexDirty = true;
+        }
+      }
+    } catch (error) {
+      try {
+        this.db?.close();
+      } catch {
+      }
+      this.db = null;
+      this.statements = null;
+      throw new InitializationError(
+        `Failed to open SQLite database: ${this.describe(error)}`,
+        { cause: error instanceof Error ? error : void 0 }
+      );
+    }
+  }
+  async close() {
+    if (!this.db) {
+      return;
+    }
+    try {
+      this.db.close();
+    } catch (error) {
+      throw new DatabaseError(`Failed to close database: ${this.describe(error)}`, {
+        cause: error instanceof Error ? error : void 0
+      });
+    } finally {
+      this.db = null;
+      this.statements = null;
+      this.memoryIndex = null;
+    }
+  }
+  async ensureVectorSchema(dimensions) {
+    const existing = await this.getEmbeddingDimensions();
+    if (existing !== null && existing !== dimensions) {
+      throw new InitializationError(
+        `Embedding dimensions mismatch: database is configured for ${existing}-d vectors, but the embedding model returned ${dimensions}-d vectors.`
+      );
+    }
+    if (!this.vectorBackend) {
+      this.vectorBackend = this.sqliteVecLoaded ? "sqlite-vec" : "blob";
+    }
+    if (this.sqliteVecLoaded && this.vectorBackend !== "blob") {
+      this.vectorBackend = "sqlite-vec";
+    }
+    this.ensureVectorStorage(dimensions);
+    await this.setMeta(META_KEYS.vectorBackend, this.vectorBackend);
+    if (existing === null) {
+      await this.setEmbeddingDimensions(dimensions);
+    }
+    this.vectorDimensions = dimensions;
+    this.reprepareVectorStatements();
+    this.hydrateMemoryIndex();
+  }
+  async getEmbeddingDimensions() {
+    return this.readMetaNumber(META_KEYS.embeddingDimensions);
+  }
+  async setEmbeddingDimensions(dimensions) {
+    await this.setMeta(META_KEYS.embeddingDimensions, String(dimensions));
+    this.vectorDimensions = dimensions;
+  }
+  async insertMemory(input) {
+    const stmts = this.requireStatements();
+    this.requireVectorReady();
+    return this.withTransaction(() => {
+      const row = stmts.insertMemory.get(
+        input.id,
+        input.organization,
+        input.agent,
+        input.contentText,
+        serializeMetadata(input.metadata),
+        input.createdAt,
+        input.updatedAt
+      );
+      if (!row || row.rowid === void 0) {
+        throw new DatabaseError("Failed to read memory after insert");
+      }
+      this.insertEmbedding(row.rowid, input.embedding);
+      this.insertFtsRow(
+        input.id,
+        input.organization,
+        input.agent,
+        input.contentText
+      );
+      stmts.insertHistory.run(
+        crypto.randomUUID(),
+        input.id,
+        "created",
+        null,
+        input.createdAt
+      );
+      return row;
+    });
+  }
+  async insertMemoriesBatch(inputs) {
+    if (inputs.length === 0) {
+      return [];
+    }
+    const stmts = this.requireStatements();
+    this.requireVectorReady();
+    return this.withTransaction(() => {
+      const rows = [];
+      for (const input of inputs) {
+        const row = stmts.insertMemory.get(
+          input.id,
+          input.organization,
+          input.agent,
+          input.contentText,
+          serializeMetadata(input.metadata),
+          input.createdAt,
+          input.updatedAt
+        );
+        if (!row || row.rowid === void 0) {
+          throw new DatabaseError("Failed to read memory after batch insert");
+        }
+        this.insertEmbedding(row.rowid, input.embedding);
+        this.insertFtsRow(
+          input.id,
+          input.organization,
+          input.agent,
+          input.contentText
+        );
+        stmts.insertHistory.run(
+          crypto.randomUUID(),
+          input.id,
+          "created",
+          null,
+          input.createdAt
+        );
+        rows.push(row);
+      }
+      return rows;
+    });
+  }
+  async updateMemory(input) {
+    const stmts = this.requireStatements();
+    return this.withTransaction(() => {
+      const existing = stmts.getMemoryById.get(
+        input.id,
+        input.organization
+      );
+      if (!existing || existing.rowid === void 0) {
+        return null;
+      }
+      const contentText = input.contentText ?? existing.content_text;
+      const metadataJson = input.metadata !== void 0 ? serializeMetadata(input.metadata) : existing.metadata_json;
+      stmts.updateMemoryContent.run(
+        input.contentText ?? null,
+        input.metadata !== void 0 ? metadataJson : null,
+        input.updatedAt,
+        input.id,
+        input.organization
+      );
+      if (input.embedding) {
+        this.deleteEmbedding(existing.rowid);
+        this.insertEmbedding(existing.rowid, input.embedding);
+      }
+      if (input.contentText !== void 0) {
+        this.upsertFts(
+          input.id,
+          input.organization,
+          existing.agent,
+          contentText
+        );
+      }
+      return stmts.getMemoryById.get(input.id, input.organization);
+    });
+  }
+  async searchByMetadata(filter, limit) {
+    const rows = await this.listMemories(filter, limit);
+    if (!filter.metadata) {
+      return rows;
+    }
+    return rows.filter(
+      (row) => matchesMetadata(deserializeMetadata(row.metadata_json), filter.metadata)
+    );
+  }
+  /** Keyword search via FTS5 BM25. Returns memory IDs ranked by relevance. */
+  async searchKeyword(query, organization, topK) {
+    const stmts = this.requireStatements();
+    if (!stmts.searchFts) {
+      return [];
+    }
+    try {
+      const sanitized = sanitizeFtsQuery(query);
+      if (!sanitized) {
+        return [];
+      }
+      const rows = stmts.searchFts.all(sanitized, organization, topK);
+      return rows.map((row) => ({
+        memoryId: row.memory_id,
+        // bm25 returns lower (more negative) for better matches — invert to [0, ∞)
+        score: 1 / (1 + Math.abs(row.rank))
+      }));
+    } catch {
+      return [];
+    }
+  }
+  async getMemoryById(id, organization) {
+    const stmts = this.requireStatements();
+    const row = stmts.getMemoryById.get(id, organization);
+    return row ?? null;
+  }
+  async getMemoryByRowid(rowid, organization) {
+    const stmts = this.requireStatements();
+    const row = stmts.getMemoryByRowid.get(rowid, organization);
+    return row ?? null;
+  }
+  async getMemoriesByRowids(rowids, organization) {
+    const out = /* @__PURE__ */ new Map();
+    if (rowids.length === 0) {
+      return out;
+    }
+    const db = this.requireDb();
+    const chunkSize = 400;
+    for (let offset = 0; offset < rowids.length; offset += chunkSize) {
+      const chunk = rowids.slice(offset, offset + chunkSize);
+      const placeholders = chunk.map(() => "?").join(",");
+      const sql = `${SQL.getMemoriesByRowidsPrefix}${placeholders})`;
+      const rows = db.prepare(sql).all(organization, ...chunk);
+      for (const row of rows) {
+        if (row.rowid !== void 0) {
+          out.set(row.rowid, row);
+        }
+      }
+    }
+    return out;
+  }
+  async listMemories(filter, limit) {
+    const db = this.requireDb();
+    const clauses = [`organization = ?`];
+    const params = [filter.organization];
+    if (filter.agent) {
+      clauses.push(`agent = ?`);
+      params.push(filter.agent);
+    }
+    if (!filter.includeArchived) {
+      clauses.push(`archived = 0`);
+    }
+    let sql = `
+      SELECT rowid, id, organization, agent, content_text, metadata_json,
+             archived, compressed_into, created_at, updated_at
+      FROM memories
+      WHERE ${clauses.join(" AND ")}
+      ORDER BY created_at ASC
+    `;
+    if (limit !== void 0 && !filter.metadata) {
+      sql += ` LIMIT ?`;
+      params.push(limit);
+    }
+    try {
+      let rows = db.prepare(sql).all(...params);
+      if (filter.metadata) {
+        rows = rows.filter(
+          (row) => matchesMetadata(
+            deserializeMetadata(row.metadata_json),
+            filter.metadata
+          )
+        );
+        if (limit !== void 0) {
+          rows = rows.slice(0, limit);
+        }
+      }
+      return rows;
+    } catch (error) {
+      throw new DatabaseError(`Failed to list memories: ${this.describe(error)}`, {
+        cause: error instanceof Error ? error : void 0
+      });
+    }
+  }
+  async searchVectors(embedding, topK) {
+    this.requireVectorReady();
+    if (this.vectorBackend === "sqlite-vec") {
+      return this.searchWithSqliteVec(embedding, topK);
+    }
+    return this.searchWithBlobFallback(embedding, topK);
+  }
+  /**
+   * Org-scoped KNN + memory rows.
+   * Caller (Wolbarg.recall) already passes an overfetched topK — do not multiply again.
+   */
+  async searchVectorsWithMemories(embedding, topK, organization, options) {
+    this.requireVectorReady();
+    const hits = await this.searchVectors(embedding, topK);
+    if (hits.length === 0) {
+      return [];
+    }
+    const map = await this.getMemoriesByRowids(
+      hits.map((h) => h.memoryRowid),
+      organization
+    );
+    const out = [];
+    for (const hit of hits) {
+      const row = map.get(hit.memoryRowid);
+      if (!row) continue;
+      if (options?.agent && row.agent !== options.agent) continue;
+      if (!options?.includeArchived && row.archived === 1) continue;
+      out.push({ row, distance: hit.distance });
+    }
+    return out;
+  }
+  async archiveMemories(ids, organization, compressedIntoId, archivedAt) {
+    const stmts = this.requireStatements();
+    const archived = [];
+    return this.withTransaction(() => {
+      for (const id of ids) {
+        const result = stmts.archiveMemory.run(
+          compressedIntoId,
+          archivedAt,
+          id,
+          organization
+        );
+        if (Number(result.changes) > 0) {
+          archived.push(id);
+          this.deleteFts(id);
+          stmts.insertHistory.run(
+            crypto.randomUUID(),
+            id,
+            "archived",
+            compressedIntoId,
+            archivedAt
+          );
+          stmts.insertHistory.run(
+            crypto.randomUUID(),
+            compressedIntoId,
+            "compressed",
+            id,
+            archivedAt
+          );
+        }
+      }
+      return archived;
+    });
+  }
+  async deleteMemoryById(id, organization) {
+    const stmts = this.requireStatements();
+    return this.withTransaction(() => {
+      const row = stmts.getMemoryById.get(id, organization);
+      if (!row || row.rowid === void 0) {
+        return false;
+      }
+      this.deleteEmbedding(row.rowid);
+      this.deleteFts(id);
+      const result = stmts.deleteMemoryById.run(id, organization);
+      return Number(result.changes) > 0;
+    });
+  }
+  async deleteMemoriesByFilter(filter) {
+    const stmts = this.requireStatements();
+    const agent = filter.agent;
+    if (!agent) {
+      throw new DatabaseError("deleteMemoriesByFilter requires an agent filter");
+    }
+    return this.withTransaction(() => {
+      const listed = this.listMemoriesSync({
+        organization: filter.organization,
+        agent,
+        includeArchived: true
+      });
+      for (const memory of listed) {
+        if (memory.rowid !== void 0) {
+          this.deleteEmbedding(memory.rowid);
+        }
+        this.deleteFts(memory.id);
+      }
+      const result = stmts.deleteMemoriesByOrgAgent.run(
+        filter.organization,
+        agent
+      );
+      return Number(result.changes);
+    });
+  }
+  async clearOrganization(organization) {
+    const stmts = this.requireStatements();
+    return this.withTransaction(() => {
+      const listed = this.listMemoriesSync({ organization, includeArchived: true });
+      for (const memory of listed) {
+        if (memory.rowid !== void 0) {
+          this.deleteEmbedding(memory.rowid);
+        }
+        this.deleteFts(memory.id);
+      }
+      const result = stmts.deleteMemoriesByOrg.run(organization);
+      return Number(result.changes);
+    });
+  }
+  async getHistory(memoryId) {
+    const stmts = this.requireStatements();
+    return stmts.getHistory.all(memoryId);
+  }
+  async insertHistoryEvent(event) {
+    const stmts = this.requireStatements();
+    stmts.insertHistory.run(
+      event.id,
+      event.memory_id,
+      event.event_type,
+      event.related_memory_id,
+      event.created_at
+    );
+  }
+  async getStats(organization) {
+    const stmts = this.requireStatements();
+    const memories = stmts.countMemories.get(organization);
+    const active = stmts.countActiveMemories.get(organization);
+    const archived = stmts.countArchivedMemories.get(organization);
+    const agents = stmts.countAgents.get(organization);
+    return {
+      totalMemories: Number(memories.count),
+      activeMemories: Number(active.count),
+      archivedMemories: Number(archived.count),
+      totalAgents: Number(agents.count)
+    };
+  }
+  async getDatabaseSizeBytes() {
+    const db = this.requireDb();
+    if (this.connectionString === ":memory:") {
+      const pageCountRow = db.prepare("PRAGMA page_count").get();
+      const pageSizeRow = db.prepare("PRAGMA page_size").get();
+      const pageCount = Number(
+        pageCountRow?.page_count ?? Object.values(pageCountRow ?? {})[0] ?? 0
+      );
+      const pageSize = Number(
+        pageSizeRow?.page_size ?? Object.values(pageSizeRow ?? {})[0] ?? 0
+      );
+      return pageCount * pageSize;
+    }
+    const dbPath = this.resolvedPath ?? this.resolvePath(this.connectionString);
+    try {
+      let total = fs2__default.default.statSync(dbPath).size;
+      for (const suffix of ["-wal", "-shm"]) {
+        const side = `${dbPath}${suffix}`;
+        if (fs2__default.default.existsSync(side)) {
+          total += fs2__default.default.statSync(side).size;
+        }
+      }
+      return total;
+    } catch (error) {
+      throw new DatabaseError(
+        `Failed to determine database size: ${this.describe(error)}`,
+        { cause: error instanceof Error ? error : void 0 }
+      );
+    }
+  }
+  withTransaction(fn) {
+    const db = this.requireDb();
+    db.exec("BEGIN");
+    try {
+      const result = fn();
+      db.exec("COMMIT");
+      return result;
+    } catch (error) {
+      try {
+        db.exec("ROLLBACK");
+      } catch {
+      }
+      if (error instanceof DatabaseError || error instanceof InitializationError) {
+        throw error;
+      }
+      throw new DatabaseError(`Transaction failed: ${this.describe(error)}`, {
+        cause: error instanceof Error ? error : void 0
+      });
+    }
+  }
+  // ─── internals ───────────────────────────────────────────────────────────
+  tryLoadSqliteVec(db) {
+    try {
+      sqliteVec__namespace.load(db);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  runMigrations(db) {
+    db.exec(CREATE_META_TABLE);
+    db.exec(CREATE_MEMORIES_TABLE);
+    db.exec(CREATE_HISTORY_TABLE);
+    db.exec(CREATE_BLOB_EMBEDDINGS_TABLE);
+    for (const indexSql of CREATE_INDEXES) {
+      db.exec(indexSql);
+    }
+    const current = this.readMetaNumberFromDb(db, META_KEYS.schemaVersion);
+    if (current === null) {
+      db.exec(CREATE_FTS_TABLE);
+      this.backfillFts(db);
+      db.prepare(SQL.setMeta).run(META_KEYS.schemaVersion, String(SCHEMA_VERSION));
+    } else if (current > SCHEMA_VERSION) {
+      throw new InitializationError(
+        `Database schema version ${current} is newer than this SDK (supports ${SCHEMA_VERSION}).`
+      );
+    } else if (current < SCHEMA_VERSION) {
+      db.exec(CREATE_FTS_TABLE);
+      this.backfillFts(db);
+      db.prepare(SQL.setMeta).run(META_KEYS.schemaVersion, String(SCHEMA_VERSION));
+    } else {
+      db.exec(CREATE_FTS_TABLE);
+    }
+  }
+  /**
+   * Rebuild FTS from active (non-archived) memories when counts diverge.
+   * Guarantees keyword/hybrid correctness after crashes or interrupted writes.
+   */
+  ensureFtsConsistency(db) {
+    try {
+      const memCount = db.prepare(`SELECT COUNT(*) AS c FROM memories WHERE archived = 0`).get();
+      const ftsCount = db.prepare(`SELECT COUNT(*) AS c FROM memories_fts`).get();
+      if (Number(memCount.c) !== Number(ftsCount.c)) {
+        this.backfillFts(db);
+      }
+    } catch {
+    }
+  }
+  backfillFts(db) {
+    try {
+      db.exec(`DELETE FROM memories_fts`);
+      const rows = db.prepare(
+        `SELECT id, organization, agent, content_text FROM memories WHERE archived = 0`
+      ).all();
+      const insert = db.prepare(SQL.insertFts);
+      for (const row of rows) {
+        insert.run(row.content_text, row.id, row.organization, row.agent);
+      }
+    } catch {
+    }
+  }
+  prepareStatements(db) {
+    let insertFts = null;
+    let deleteFts = null;
+    let searchFts = null;
+    try {
+      insertFts = db.prepare(SQL.insertFts);
+      deleteFts = db.prepare(SQL.deleteFts);
+      searchFts = db.prepare(SQL.searchFts);
+    } catch {
+    }
+    return {
+      getMeta: db.prepare(SQL.getMeta),
+      setMeta: db.prepare(SQL.setMeta),
+      insertMemory: db.prepare(SQL.insertMemory),
+      updateMemoryContent: db.prepare(SQL.updateMemoryContent),
+      getMemoryById: db.prepare(SQL.getMemoryById),
+      getMemoryByRowid: db.prepare(SQL.getMemoryByRowid),
+      insertEmbedding: null,
+      deleteEmbedding: null,
+      searchVectors: null,
+      insertEmbeddingBlob: null,
+      deleteEmbeddingBlob: null,
+      listEmbeddingsBlob: null,
+      archiveMemory: db.prepare(SQL.archiveMemory),
+      deleteMemoryById: db.prepare(SQL.deleteMemoryById),
+      deleteMemoriesByOrg: db.prepare(SQL.deleteMemoriesByOrg),
+      deleteMemoriesByOrgAgent: db.prepare(SQL.deleteMemoriesByOrgAgent),
+      insertHistory: db.prepare(SQL.insertHistory),
+      getHistory: db.prepare(SQL.getHistory),
+      countMemories: db.prepare(SQL.countMemories),
+      countActiveMemories: db.prepare(SQL.countActiveMemories),
+      countArchivedMemories: db.prepare(SQL.countArchivedMemories),
+      countAgents: db.prepare(SQL.countAgents),
+      listRowidsForOrg: db.prepare(SQL.listRowidsForOrg),
+      listRowidsForOrgAgent: db.prepare(SQL.listRowidsForOrgAgent),
+      vectorTableExists: db.prepare(SQL.vectorTableExists),
+      blobTableExists: db.prepare(
+        `SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'memory_embeddings_blob'`
+      ),
+      insertFts,
+      deleteFts,
+      searchFts
+    };
+  }
+  listMemoriesSync(filter) {
+    const db = this.requireDb();
+    const clauses = [`organization = ?`];
+    const params = [filter.organization];
+    if (filter.agent) {
+      clauses.push(`agent = ?`);
+      params.push(filter.agent);
+    }
+    if (!filter.includeArchived) {
+      clauses.push(`archived = 0`);
+    }
+    const sql = `
+      SELECT rowid, id, organization, agent, content_text, metadata_json,
+             archived, compressed_into, created_at, updated_at
+      FROM memories
+      WHERE ${clauses.join(" AND ")}
+    `;
+    return db.prepare(sql).all(...params);
+  }
+  /** Insert-only FTS row (new memory IDs never collide). */
+  insertFtsRow(memoryId, organization, agent, contentText) {
+    const stmts = this.requireStatements();
+    if (!stmts.insertFts) {
+      return;
+    }
+    try {
+      stmts.insertFts.run(contentText, memoryId, organization, agent);
+    } catch {
+    }
+  }
+  upsertFts(memoryId, organization, agent, contentText) {
+    const stmts = this.requireStatements();
+    if (!stmts.insertFts || !stmts.deleteFts) {
+      return;
+    }
+    try {
+      stmts.deleteFts.run(memoryId);
+      stmts.insertFts.run(contentText, memoryId, organization, agent);
+    } catch {
+    }
+  }
+  deleteFts(memoryId) {
+    const stmts = this.requireStatements();
+    if (!stmts.deleteFts) {
+      return;
+    }
+    try {
+      stmts.deleteFts.run(memoryId);
+    } catch {
+    }
+  }
+  ensureVectorStorage(dimensions) {
+    const db = this.requireDb();
+    if (this.vectorBackend === "sqlite-vec") {
+      if (!this.sqliteVecLoaded) {
+        throw new InitializationError(
+          "sqlite-vec is required for this database but is unavailable on this platform."
+        );
+      }
+      const stmts = this.requireStatements();
+      const exists = stmts.vectorTableExists.get();
+      if (!exists) {
+        db.exec(buildVectorTableSql(dimensions));
+      }
+      this.memoryIndex = null;
+      return;
+    }
+    db.exec(CREATE_BLOB_EMBEDDINGS_TABLE);
+    if (!this.memoryIndex || this.memoryIndex.size === 0) {
+      this.memoryIndex = new InMemoryVectorIndex(dimensions);
+    }
+  }
+  hydrateMemoryIndex() {
+    if (this.vectorBackend !== "blob" || this.vectorDimensions === null) {
+      this.memoryIndex = null;
+      return;
+    }
+    const stmts = this.requireStatements();
+    if (!stmts.listEmbeddingsBlob) {
+      stmts.listEmbeddingsBlob = this.requireDb().prepare(SQL.listEmbeddingsBlob);
+    }
+    const index = new InMemoryVectorIndex(this.vectorDimensions);
+    try {
+      const rows = stmts.listEmbeddingsBlob.all();
+      for (const row of rows) {
+        index.upsert(row.memory_rowid, bufferToEmbedding(row.embedding));
+      }
+    } catch {
+    }
+    this.memoryIndex = index;
+  }
+  reprepareVectorStatements() {
+    const db = this.requireDb();
+    const stmts = this.requireStatements();
+    if (this.vectorBackend === "sqlite-vec") {
+      stmts.insertEmbedding = db.prepare(SQL.insertEmbedding);
+      stmts.deleteEmbedding = db.prepare(SQL.deleteEmbedding);
+      stmts.searchVectors = db.prepare(SQL.searchVectors);
+      stmts.insertEmbeddingBlob = null;
+      stmts.deleteEmbeddingBlob = null;
+      stmts.listEmbeddingsBlob = null;
+      return;
+    }
+    stmts.insertEmbeddingBlob = db.prepare(SQL.insertEmbeddingBlob);
+    stmts.deleteEmbeddingBlob = db.prepare(SQL.deleteEmbeddingBlob);
+    stmts.listEmbeddingsBlob = db.prepare(SQL.listEmbeddingsBlob);
+    stmts.insertEmbedding = null;
+    stmts.deleteEmbedding = null;
+    stmts.searchVectors = null;
+  }
+  insertEmbedding(rowid, embedding) {
+    const stmts = this.requireStatements();
+    if (this.vectorBackend === "sqlite-vec") {
+      stmts.insertEmbedding.run(rowid, this.toVectorParam(embedding));
+      return;
+    }
+    stmts.insertEmbeddingBlob.run(rowid, embeddingToBuffer(embedding));
+    this.memoryIndexDirty = true;
+  }
+  deleteEmbedding(rowid) {
+    const stmts = this.requireStatements();
+    try {
+      if (this.vectorBackend === "sqlite-vec" && stmts.deleteEmbedding) {
+        stmts.deleteEmbedding.run(rowid);
+      } else if (stmts.deleteEmbeddingBlob) {
+        stmts.deleteEmbeddingBlob.run(rowid);
+        this.memoryIndex?.remove(rowid);
+        this.memoryIndexDirty = true;
+      }
+    } catch {
+    }
+  }
+  searchWithSqliteVec(embedding, topK) {
+    const stmts = this.requireStatements();
+    try {
+      const rows = stmts.searchVectors.all(
+        this.toVectorParam(embedding),
+        topK
+      );
+      const hits = new Array(rows.length);
+      for (let i = 0; i < rows.length; i += 1) {
+        const row = rows[i];
+        hits[i] = {
+          memoryRowid: row.memory_rowid,
+          distance: row.distance
+        };
+      }
+      return hits;
+    } catch (error) {
+      throw new DatabaseError(`Vector search failed: ${this.describe(error)}`, {
+        cause: error instanceof Error ? error : void 0
+      });
+    }
+  }
+  searchWithBlobFallback(embedding, topK) {
+    if (this.memoryIndexDirty || !this.memoryIndex) {
+      this.hydrateMemoryIndex();
+      this.memoryIndexDirty = false;
+    }
+    if (this.memoryIndex && this.vectorDimensions !== null) {
+      const query = normalizeEmbedding(embedding, this.vectorDimensions);
+      return this.memoryIndex.search(query, topK);
+    }
+    throw new DatabaseError("Blob vector index is not initialized");
+  }
+  async setMeta(key, value) {
+    const stmts = this.requireStatements();
+    stmts.setMeta.run(key, value);
+  }
+  readMetaNumber(key) {
+    const stmts = this.requireStatements();
+    const row = stmts.getMeta.get(key);
+    if (!row) {
+      return null;
+    }
+    const parsed = Number(row.value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  readMetaString(key) {
+    const stmts = this.requireStatements();
+    const row = stmts.getMeta.get(key);
+    return row?.value ?? null;
+  }
+  readMetaNumberFromDb(db, key) {
+    const row = db.prepare(SQL.getMeta).get(key);
+    if (!row) {
+      return null;
+    }
+    const parsed = Number(row.value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  resolvePath(connectionString) {
+    if (connectionString === ":memory:") {
+      return ":memory:";
+    }
+    return path2__default.default.isAbsolute(connectionString) ? connectionString : path2__default.default.resolve(process.cwd(), connectionString);
+  }
+  requireDb() {
+    if (!this.db) {
+      throw new DatabaseError("Database is not open. Call init() first.");
+    }
+    return this.db;
+  }
+  requireStatements() {
+    if (!this.statements) {
+      throw new DatabaseError("Database statements are not prepared. Call init() first.");
+    }
+    return this.statements;
+  }
+  requireVectorReady() {
+    if (!this.vectorBackend || this.vectorDimensions === null) {
+      throw new DatabaseError(
+        "Vector index is not ready. Embedding dimensions have not been initialized."
+      );
+    }
+  }
+  toVectorParam(embedding) {
+    const buffer = embeddingToBuffer(embedding);
+    return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+  }
+  describe(error) {
+    if (error instanceof Error) {
+      return error.message;
+    }
+    return String(error);
+  }
+};
+var SqliteDatabaseProvider = SqliteStorageProvider;
+function sanitizeFtsQuery(query) {
+  const terms = query.split(/\s+/).map((t) => t.replace(/["']/g, "").replace(/[^\p{L}\p{N}_-]/gu, "")).filter((t) => t.length > 0);
+  if (terms.length === 0) {
+    return "";
+  }
+  return terms.map((t) => `"${t}"`).join(" OR ");
+}
+var txStore = new async_hooks.AsyncLocalStorage();
+var STMT = {
+  insertOne: "Wolbarg_insert_one_v1",
+  insertBatch: "Wolbarg_insert_batch_v1"
+};
+function toVectorLiteral(embedding) {
+  const n = embedding.length;
+  let s = "[";
+  for (let i = 0; i < n; i += 1) {
+    if (i !== 0) s += ",";
+    s += embedding[i];
+  }
+  return s + "]";
+}
+var INSERT_ONE_SQL = `WITH mem AS (
+   INSERT INTO memories (
+     id, organization, agent, content_text, metadata_json,
+     archived, compressed_into, created_at, updated_at
+   ) VALUES ($1,$2,$3,$4,$5::jsonb,false,NULL,$6,$7)
+   RETURNING id, organization, agent, content_text, metadata_json,
+             archived::int AS archived, compressed_into, created_at, updated_at
+ ),
+ hist AS (
+   INSERT INTO memory_history (id, memory_id, event_type, related_memory_id, created_at)
+   SELECT $8, id, 'created', NULL, $6 FROM mem
+ ),
+ mapped AS (
+   INSERT INTO memory_row_map (memory_id)
+   SELECT id FROM mem
+   ON CONFLICT (memory_id) DO NOTHING
+ ),
+ emb AS (
+   INSERT INTO memory_embeddings (memory_id, embedding)
+   SELECT id, $9::vector FROM mem
+   ON CONFLICT (memory_id) DO UPDATE SET embedding = EXCLUDED.embedding
+ )
+ SELECT * FROM mem`;
+var INSERT_BATCH_SQL = `WITH mem AS (
+   INSERT INTO memories (
+     id, organization, agent, content_text, metadata_json,
+     archived, compressed_into, created_at, updated_at
+   )
+   SELECT id, org, agent, txt, meta::jsonb, false, NULL, c, u
+   FROM unnest(
+     $1::text[], $2::text[], $3::text[], $4::text[],
+     $5::text[], $6::timestamptz[], $7::timestamptz[]
+   ) AS t(id, org, agent, txt, meta, c, u)
+   RETURNING id, organization, agent, content_text, metadata_json,
+             archived::int AS archived, compressed_into, created_at, updated_at
+ ),
+ hist AS (
+   INSERT INTO memory_history (id, memory_id, event_type, related_memory_id, created_at)
+   SELECT h, m, 'created', NULL, c
+   FROM unnest($8::text[], $1::text[], $6::timestamptz[]) AS t(h, m, c)
+ ),
+ mapped AS (
+   INSERT INTO memory_row_map (memory_id)
+   SELECT unnest($1::text[])
+   ON CONFLICT (memory_id) DO NOTHING
+ ),
+ emb AS (
+   INSERT INTO memory_embeddings (memory_id, embedding)
+   SELECT id, emb::vector
+   FROM unnest($1::text[], $9::text[]) AS t(id, emb)
+   ON CONFLICT (memory_id) DO UPDATE SET embedding = EXCLUDED.embedding
+ )
+ SELECT * FROM mem`;
+var COPY_BATCH_THRESHOLD = 64;
+var PostgresStorageProvider = class {
+  name = "postgres";
+  connectionString;
+  maxPoolSize;
+  pool = null;
+  vectorDimensions = null;
+  hasPgvector = false;
+  hnswIndexEnsured = false;
+  hnswCreateFailures = 0;
+  hasContentTsv = false;
+  iterativeScanEnabled = false;
+  /** Coalesce concurrent insertMemory callers into one unnest batch. */
+  insertQueue = [];
+  insertFlushScheduled = false;
+  insertFlushInFlight = false;
+  constructor(options) {
+    this.connectionString = options.connectionString;
+    this.maxPoolSize = options.maxPoolSize ?? 32;
+  }
+  getPoolStats() {
+    const pool = this.pool;
+    return {
+      max: this.maxPoolSize,
+      total: pool?.totalCount ?? 0,
+      idle: pool?.idleCount ?? 0,
+      waiting: pool?.waitingCount ?? 0
+    };
+  }
+  async open() {
+    let PoolCtor;
+    try {
+      const mod = await import('pg');
+      PoolCtor = mod.Pool ?? mod.default.Pool;
+    } catch {
+      throw new ConfigurationError(
+        'PostgreSQL storage requires the optional "pg" package. Install it with: npm install pg'
+      );
+    }
+    try {
+      this.pool = new PoolCtor({
+        connectionString: this.connectionString,
+        max: this.maxPoolSize,
+        idleTimeoutMillis: 3e4,
+        allowExitOnIdle: true,
+        keepAlive: true
+      });
+      await this.runMigrations();
+      this.hasPgvector = await this.tryEnablePgvector();
+      const dims = await this.getEmbeddingDimensions();
+      if (dims !== null) {
+        this.vectorDimensions = dims;
+        await this.ensureVectorTables(dims);
+      }
+    } catch (error) {
+      await this.pool?.end().catch(() => void 0);
+      this.pool = null;
+      if (error instanceof ConfigurationError || error instanceof InitializationError) {
+        throw error;
+      }
+      throw new InitializationError(
+        `Failed to open PostgreSQL database: ${this.describe(error)}`,
+        { cause: error instanceof Error ? error : void 0 }
+      );
+    }
+  }
+  async close() {
+    if (!this.pool) {
+      return;
+    }
+    await this.pool.end();
+    this.pool = null;
+  }
+  async ensureVectorSchema(dimensions) {
+    const existing = await this.getEmbeddingDimensions();
+    if (existing !== null && existing !== dimensions) {
+      throw new InitializationError(
+        `Embedding dimensions mismatch: database is configured for ${existing}-d vectors, but the embedding model returned ${dimensions}-d vectors.`
+      );
+    }
+    this.hasPgvector = await this.tryEnablePgvector();
+    await this.ensureVectorTables(dimensions);
+    if (existing === null) {
+      await this.setEmbeddingDimensions(dimensions);
+    }
+    this.vectorDimensions = dimensions;
+  }
+  async ensureVectorTables(dimensions) {
+    if (this.hasPgvector) {
+      await this.query(`
+        CREATE TABLE IF NOT EXISTS memory_embeddings (
+          memory_id TEXT PRIMARY KEY REFERENCES memories(id) ON DELETE CASCADE,
+          embedding vector(${dimensions})
+        )
+      `);
+      const idx = await this.query(
+        `SELECT 1 FROM pg_indexes WHERE indexname = 'idx_memory_embeddings_hnsw' LIMIT 1`
+      );
+      this.hnswIndexEnsured = idx.rows.length > 0;
+    } else {
+      await this.query(`
+        CREATE TABLE IF NOT EXISTS memory_embeddings_blob (
+          memory_id TEXT PRIMARY KEY REFERENCES memories(id) ON DELETE CASCADE,
+          embedding BYTEA NOT NULL
+        )
+      `);
+    }
+  }
+  /**
+   * Soft reset for a single organization. Drops HNSW only when the embeddings
+   * table is empty so other corpora on a shared bench DB stay intact.
+   */
+  async resetOrganization(organization) {
+    await this.query(`DELETE FROM memories WHERE organization = $1`, [
+      organization
+    ]);
+    const count = await this.query(
+      `SELECT COUNT(*)::int AS n FROM memory_embeddings`
+    );
+    if (Number(count.rows[0]?.n ?? 0) === 0) {
+      await this.query(
+        `DROP INDEX IF EXISTS idx_memory_embeddings_hnsw`
+      ).catch(() => void 0);
+      this.hnswIndexEnsured = false;
+    }
+  }
+  /**
+   * Wipe all Wolbarg tables (explicit opt-in). Prefer {@link resetOrganization}.
+   */
+  async wipeAllData() {
+    await this.query(`TRUNCATE TABLE memories CASCADE`).catch(() => void 0);
+    await this.query(
+      `DROP INDEX IF EXISTS idx_memory_embeddings_hnsw`
+    ).catch(() => void 0);
+    this.hnswIndexEnsured = false;
+  }
+  /** Build HNSW once before the first KNN query (bulk-friendly inserts). */
+  async ensureHnswIndex() {
+    if (!this.hasPgvector || this.hnswIndexEnsured) {
+      return;
+    }
+    try {
+      await this.query(`
+        CREATE INDEX IF NOT EXISTS idx_memory_embeddings_hnsw
+        ON memory_embeddings USING hnsw (embedding vector_cosine_ops)
+        WITH (m = 16, ef_construction = 64)
+      `);
+      this.hnswIndexEnsured = true;
+      this.hnswCreateFailures = 0;
+      if (!this.iterativeScanEnabled) {
+        try {
+          await this.query(`SET hnsw.iterative_scan = relaxed_order`);
+          this.iterativeScanEnabled = true;
+        } catch {
+        }
+      }
+    } catch (error) {
+      this.hnswCreateFailures += 1;
+      if (this.hnswCreateFailures >= 3) {
+        throw new DatabaseError(
+          `Failed to create HNSW index after ${this.hnswCreateFailures} attempts: ${this.describe(error)}`,
+          { cause: error instanceof Error ? error : void 0 }
+        );
+      }
+    }
+  }
+  async getEmbeddingDimensions() {
+    const result = await this.query(
+      `SELECT value FROM Wolbarg_meta WHERE key = $1`,
+      [META_KEYS.embeddingDimensions]
+    );
+    const value = result.rows[0]?.value;
+    if (typeof value !== "string") {
+      return null;
+    }
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  async setEmbeddingDimensions(dimensions) {
+    await this.query(
+      `INSERT INTO Wolbarg_meta (key, value) VALUES ($1, $2)
+       ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value`,
+      [META_KEYS.embeddingDimensions, String(dimensions)]
+    );
+    this.vectorDimensions = dimensions;
+  }
+  async insertMemory(input) {
+    this.requireVectorReady();
+    if (!this.insertFlushInFlight && this.insertQueue.length === 0) {
+      this.insertFlushInFlight = true;
+      try {
+        return await this.insertMemoryImmediate(input);
+      } finally {
+        this.insertFlushInFlight = false;
+        if (this.insertQueue.length > 0) {
+          this.insertFlushScheduled = true;
+          queueMicrotask(() => {
+            void this.flushInsertQueue();
+          });
+        }
+      }
+    }
+    return new Promise((resolve, reject) => {
+      this.insertQueue.push({ input, resolve, reject });
+      if (this.insertQueue.length >= 16) {
+        if (this.insertFlushScheduled) {
+          this.insertFlushScheduled = false;
+        }
+        void this.flushInsertQueue();
+        return;
+      }
+      if (!this.insertFlushScheduled) {
+        this.insertFlushScheduled = true;
+        queueMicrotask(() => {
+          void this.flushInsertQueue();
+        });
+      }
+    });
+  }
+  async flushInsertQueue() {
+    if (this.insertFlushInFlight) {
+      return;
+    }
+    const batch = this.insertQueue;
+    this.insertQueue = [];
+    this.insertFlushScheduled = false;
+    if (batch.length === 0) {
+      return;
+    }
+    this.insertFlushInFlight = true;
+    try {
+      if (batch.length === 1) {
+        const row = await this.insertMemoryImmediate(batch[0].input);
+        batch[0].resolve(row);
+        return;
+      }
+      const rows = await this.insertMemoriesBatch(batch.map((b) => b.input));
+      for (let i = 0; i < batch.length; i += 1) {
+        batch[i].resolve(rows[i]);
+      }
+    } catch (error) {
+      for (const item of batch) {
+        item.reject(error);
+      }
+    } finally {
+      this.insertFlushInFlight = false;
+      if (this.insertQueue.length > 0) {
+        this.insertFlushScheduled = true;
+        queueMicrotask(() => {
+          void this.flushInsertQueue();
+        });
+      } else {
+        this.insertFlushScheduled = false;
+      }
+    }
+  }
+  /** Single-row insert without coalescing (used by flush + batch of 1). */
+  async insertMemoryImmediate(input) {
+    if (this.hasPgvector) {
+      const inserted = await this.queryNamed(STMT.insertOne, INSERT_ONE_SQL, [
+        input.id,
+        input.organization,
+        input.agent,
+        input.contentText,
+        serializeMetadata(input.metadata),
+        input.createdAt,
+        input.updatedAt,
+        crypto.randomUUID(),
+        toVectorLiteral(input.embedding)
+      ]);
+      return this.mapRow(inserted.rows[0]);
+    }
+    return this.insertOneBlob(input);
+  }
+  async insertMemoriesBatch(inputs) {
+    if (inputs.length === 0) {
+      return [];
+    }
+    this.requireVectorReady();
+    if (inputs.length === 1 && this.hasPgvector) {
+      return [await this.insertMemoryImmediate(inputs[0])];
+    }
+    if (this.hasPgvector) {
+      if (inputs.length >= COPY_BATCH_THRESHOLD) {
+        return this.insertBatchChunked(inputs);
+      }
+      return this.insertBatchPgvector(inputs);
+    }
+    return this.withTransaction(async () => {
+      const out = [];
+      for (const input of inputs) {
+        out.push(await this.insertOneBlob(input));
+      }
+      return out;
+    });
+  }
+  async insertBatchPgvector(inputs) {
+    const ids = new Array(inputs.length);
+    const orgs = new Array(inputs.length);
+    const agents = new Array(inputs.length);
+    const texts = new Array(inputs.length);
+    const metas = new Array(inputs.length);
+    const created = new Array(inputs.length);
+    const updated = new Array(inputs.length);
+    const histIds = new Array(inputs.length);
+    const vectors = new Array(inputs.length);
+    for (let i = 0; i < inputs.length; i += 1) {
+      const input = inputs[i];
+      ids[i] = input.id;
+      orgs[i] = input.organization;
+      agents[i] = input.agent;
+      texts[i] = input.contentText;
+      metas[i] = serializeMetadata(input.metadata);
+      created[i] = input.createdAt;
+      updated[i] = input.updatedAt;
+      histIds[i] = crypto.randomUUID();
+      vectors[i] = toVectorLiteral(input.embedding);
+    }
+    const inserted = await this.queryNamed(STMT.insertBatch, INSERT_BATCH_SQL, [
+      ids,
+      orgs,
+      agents,
+      texts,
+      metas,
+      created,
+      updated,
+      histIds,
+      vectors
+    ]);
+    const byId = new Map(
+      inserted.rows.map((r) => [String(r.id), this.mapRow(r)])
+    );
+    return ids.map((id) => byId.get(id));
+  }
+  /** Split large ingest batches into parallel unnest chunks (pool pipelining). */
+  async insertBatchChunked(inputs) {
+    const chunkSize = 128;
+    if (inputs.length <= chunkSize) {
+      return this.insertBatchPgvector(inputs);
+    }
+    const chunks = [];
+    for (let i = 0; i < inputs.length; i += chunkSize) {
+      chunks.push(inputs.slice(i, i + chunkSize));
+    }
+    const results = await Promise.all(
+      chunks.map((chunk) => this.insertBatchPgvector(chunk))
+    );
+    const out = new Array(inputs.length);
+    let offset = 0;
+    for (const part of results) {
+      for (let i = 0; i < part.length; i += 1) {
+        out[offset + i] = part[i];
+      }
+      offset += part.length;
+    }
+    return out;
+  }
+  async insertOneBlob(input) {
+    const buf = Buffer.from(
+      input.embedding.buffer,
+      input.embedding.byteOffset,
+      input.embedding.byteLength
+    );
+    const inserted = await this.query(
+      `INSERT INTO memories (
+        id, organization, agent, content_text, metadata_json,
+        archived, compressed_into, created_at, updated_at
+      ) VALUES ($1,$2,$3,$4,$5::jsonb,false,NULL,$6,$7)
+      RETURNING id, organization, agent, content_text, metadata_json,
+                archived::int AS archived, compressed_into, created_at, updated_at`,
+      [
+        input.id,
+        input.organization,
+        input.agent,
+        input.contentText,
+        serializeMetadata(input.metadata),
+        input.createdAt,
+        input.updatedAt
+      ]
+    );
+    const row = this.mapRow(inserted.rows[0]);
+    await this.query(
+      `WITH mapped AS (
+         INSERT INTO memory_row_map (memory_id) VALUES ($1)
+         ON CONFLICT (memory_id) DO NOTHING
+       )
+       INSERT INTO memory_embeddings_blob (memory_id, embedding)
+       VALUES ($1, $2)
+       ON CONFLICT (memory_id) DO UPDATE SET embedding = EXCLUDED.embedding`,
+      [input.id, buf]
+    );
+    await this.query(
+      `INSERT INTO memory_history (id, memory_id, event_type, related_memory_id, created_at)
+       VALUES ($1,$2,'created',NULL,$3)`,
+      [crypto.randomUUID(), input.id, input.createdAt]
+    );
+    return row;
+  }
+  async updateMemory(input) {
+    const existing = await this.getMemoryById(input.id, input.organization);
+    if (!existing) {
+      return null;
+    }
+    await this.query(
+      `UPDATE memories SET
+        content_text = COALESCE($1, content_text),
+        metadata_json = COALESCE($2::jsonb, metadata_json),
+        updated_at = $3
+       WHERE id = $4 AND organization = $5`,
+      [
+        input.contentText ?? null,
+        input.metadata !== void 0 ? serializeMetadata(input.metadata) : null,
+        input.updatedAt,
+        input.id,
+        input.organization
+      ]
+    );
+    if (input.embedding) {
+      await this.deleteEmbedding(input.id);
+      await this.insertEmbedding(input.id, input.embedding);
+    }
+    return this.getMemoryById(input.id, input.organization);
+  }
+  async getMemoryById(id, organization) {
+    const result = await this.query(
+      `SELECT id, organization, agent, content_text, metadata_json,
+              archived::int AS archived, compressed_into, created_at, updated_at
+       FROM memories WHERE id = $1 AND organization = $2`,
+      [id, organization]
+    );
+    const row = result.rows[0];
+    return row ? this.mapRow(row) : null;
+  }
+  async getMemoryByRowid(rowid, organization) {
+    const result = await this.query(
+      `SELECT m.id, m.organization, m.agent, m.content_text, m.metadata_json,
+              m.archived::int AS archived, m.compressed_into, m.created_at, m.updated_at,
+              e.row_num AS rowid
+       FROM memories m
+       JOIN memory_row_map e ON e.memory_id = m.id
+       WHERE e.row_num = $1 AND m.organization = $2`,
+      [rowid, organization]
+    );
+    const row = result.rows[0];
+    return row ? this.mapRow(row) : null;
+  }
+  async getMemoriesByRowids(rowids, organization) {
+    const out = /* @__PURE__ */ new Map();
+    if (rowids.length === 0) {
+      return out;
+    }
+    const result = await this.query(
+      `SELECT m.id, m.organization, m.agent, m.content_text, m.metadata_json,
+              m.archived::int AS archived, m.compressed_into, m.created_at, m.updated_at,
+              e.row_num AS rowid
+       FROM memories m
+       JOIN memory_row_map e ON e.memory_id = m.id
+       WHERE m.organization = $1 AND e.row_num = ANY($2::bigint[])`,
+      [organization, rowids]
+    );
+    for (const row of result.rows) {
+      const mapped = this.mapRow(row);
+      if (mapped.rowid !== void 0) {
+        out.set(mapped.rowid, mapped);
+      }
+    }
+    return out;
+  }
+  async listMemories(filter, limit) {
+    const clauses = [`organization = $1`];
+    const params = [filter.organization];
+    let idx = 2;
+    if (filter.agent) {
+      clauses.push(`agent = $${idx++}`);
+      params.push(filter.agent);
+    }
+    if (!filter.includeArchived) {
+      clauses.push(`archived = false`);
+    }
+    let sql = `
+      SELECT id, organization, agent, content_text, metadata_json,
+             archived::int AS archived, compressed_into, created_at, updated_at
+      FROM memories
+      WHERE ${clauses.join(" AND ")}
+      ORDER BY created_at ASC
+    `;
+    if (limit !== void 0 && !filter.metadata) {
+      sql += ` LIMIT $${idx}`;
+      params.push(limit);
+    }
+    const result = await this.query(sql, params);
+    let rows = result.rows.map((r) => this.mapRow(r));
+    if (filter.metadata) {
+      rows = rows.filter(
+        (row) => matchesMetadata(deserializeMetadata(row.metadata_json), filter.metadata)
+      );
+      if (limit !== void 0) {
+        rows = rows.slice(0, limit);
+      }
+    }
+    return rows;
+  }
+  async searchByMetadata(filter, limit) {
+    return this.listMemories(filter, limit);
+  }
+  async searchKeyword(query, organization, topK) {
+    const trimmed = query.trim();
+    if (!trimmed || topK <= 0) {
+      return [];
+    }
+    try {
+      const sql = this.hasContentTsv ? `SELECT id AS memory_id,
+                  ts_rank(content_tsv, plainto_tsquery('english', $1)) AS rank
+           FROM memories
+           WHERE organization = $2
+             AND archived = false
+             AND content_tsv @@ plainto_tsquery('english', $1)
+           ORDER BY rank DESC
+           LIMIT $3` : `SELECT id AS memory_id,
+                  ts_rank(to_tsvector('english', content_text), plainto_tsquery('english', $1)) AS rank
+           FROM memories
+           WHERE organization = $2
+             AND archived = false
+             AND to_tsvector('english', content_text) @@ plainto_tsquery('english', $1)
+           ORDER BY rank DESC
+           LIMIT $3`;
+      const result = await this.query(sql, [trimmed, organization, topK]);
+      return result.rows.map((row) => ({
+        memoryId: String(row.memory_id),
+        score: Number(row.rank)
+      }));
+    } catch {
+      return [];
+    }
+  }
+  async searchVectors(embedding, topK) {
+    this.requireVectorReady();
+    if (this.hasPgvector) {
+      await this.ensureHnswIndex();
+      const result2 = await this.query(
+        `SELECT r.row_num AS memory_rowid, ann.distance
+         FROM (
+           SELECT e.memory_id, (e.embedding <=> $1::vector) AS distance
+           FROM memory_embeddings e
+           ORDER BY e.embedding <=> $1::vector
+           LIMIT $2
+         ) ann
+         JOIN memory_row_map r ON r.memory_id = ann.memory_id
+         ORDER BY ann.distance`,
+        [toVectorLiteral(embedding), topK]
+      );
+      const hits = new Array(result2.rows.length);
+      for (let i = 0; i < result2.rows.length; i += 1) {
+        const row = result2.rows[i];
+        hits[i] = {
+          memoryRowid: Number(row.memory_rowid),
+          distance: Number(row.distance)
+        };
+      }
+      return hits;
+    }
+    const result = await this.query(
+      `SELECT r.row_num AS memory_rowid, e.embedding
+       FROM memory_embeddings_blob e
+       JOIN memory_row_map r ON r.memory_id = e.memory_id`
+    );
+    const scored = result.rows.map((row) => {
+      const buf = row.embedding;
+      const vec = new Float32Array(
+        buf.buffer,
+        buf.byteOffset,
+        buf.byteLength / Float32Array.BYTES_PER_ELEMENT
+      );
+      return {
+        memoryRowid: Number(row.memory_rowid),
+        distance: cosineDistance(embedding, vec)
+      };
+    });
+    scored.sort((a, b) => a.distance - b.distance);
+    return scored.slice(0, topK);
+  }
+  async searchVectorsWithMemories(embedding, topK, organization, options) {
+    this.requireVectorReady();
+    if (!this.hasPgvector) {
+      const hits = await this.searchVectors(embedding, topK);
+      const map = await this.getMemoriesByRowids(
+        hits.map((h) => h.memoryRowid),
+        organization
+      );
+      const out = [];
+      for (const hit of hits) {
+        const row = map.get(hit.memoryRowid);
+        if (!row) continue;
+        if (options?.agent && row.agent !== options.agent) continue;
+        if (!options?.includeArchived && row.archived === 1) continue;
+        out.push({ row, distance: hit.distance });
+      }
+      return out;
+    }
+    await this.ensureHnswIndex();
+    const vec = toVectorLiteral(embedding);
+    const mapHits = (rows) => rows.map((row) => ({
+      row: this.mapRow(row),
+      distance: Number(row.distance)
+    }));
+    let overfetch = Math.min(Math.max(topK * 8, topK), 512);
+    const maxFetch = Math.min(Math.max(topK * 64, 512), 8192);
+    for (; ; ) {
+      const agentClause = options?.agent ? "AND m.agent = $5" : "";
+      const archivedClause = options?.includeArchived ? "" : "AND m.archived = false";
+      const params = options?.agent ? [vec, overfetch, organization, topK, options.agent] : [vec, overfetch, organization, topK];
+      const ann = await this.query(
+        `WITH ann AS (
+           SELECT e.memory_id, (e.embedding <=> $1::vector) AS distance
+           FROM memory_embeddings e
+           ORDER BY e.embedding <=> $1::vector
+           LIMIT $2
+         )
+         SELECT m.id, m.organization, m.agent, m.content_text, m.metadata_json,
+                m.archived::int AS archived, m.compressed_into, m.created_at, m.updated_at,
+                r.row_num AS rowid,
+                ann.distance,
+                (SELECT COUNT(*)::int FROM ann) AS ann_fetched
+         FROM ann
+         JOIN memory_row_map r ON r.memory_id = ann.memory_id
+         JOIN memories m ON m.id = ann.memory_id
+         WHERE m.organization = $3
+           ${agentClause}
+           ${archivedClause}
+         ORDER BY ann.distance
+         LIMIT $4`,
+        params
+      );
+      const annFetched = Number(ann.rows[0]?.ann_fetched ?? ann.rows.length);
+      if (ann.rows.length >= topK || annFetched < overfetch || overfetch >= maxFetch) {
+        return mapHits(ann.rows.slice(0, topK));
+      }
+      const next = Math.min(overfetch * 4, maxFetch);
+      if (next === overfetch) {
+        return mapHits(ann.rows.slice(0, topK));
+      }
+      overfetch = next;
+    }
+  }
+  async archiveMemories(ids, organization, compressedIntoId, archivedAt) {
+    if (ids.length === 0) {
+      return [];
+    }
+    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]
+    );
+    const archived = result.rows.map((r) => String(r.id));
+    if (archived.length === 0) {
+      return [];
+    }
+    const histIds = [];
+    const memIds = [];
+    const types = [];
+    const related = [];
+    const times = [];
+    for (const id of archived) {
+      histIds.push(crypto.randomUUID(), crypto.randomUUID());
+      memIds.push(id, compressedIntoId);
+      types.push("archived", "compressed");
+      related.push(compressedIntoId, id);
+      times.push(archivedAt, archivedAt);
+    }
+    await this.query(
+      `INSERT INTO memory_history (id, memory_id, event_type, related_memory_id, created_at)
+       SELECT * FROM unnest($1::text[], $2::text[], $3::text[], $4::text[], $5::timestamptz[])`,
+      [histIds, memIds, types, related, times]
+    );
+    return archived;
+  }
+  async deleteMemoryById(id, organization) {
+    const result = await this.query(
+      `DELETE FROM memories WHERE id = $1 AND organization = $2`,
+      [id, organization]
+    );
+    return (result.rowCount ?? 0) > 0;
+  }
+  async deleteMemoriesByFilter(filter) {
+    if (!filter.agent) {
+      throw new DatabaseError("deleteMemoriesByFilter requires an agent filter");
+    }
+    const result = await this.query(
+      `DELETE FROM memories WHERE organization = $1 AND agent = $2`,
+      [filter.organization, filter.agent]
+    );
+    return result.rowCount ?? 0;
+  }
+  async clearOrganization(organization) {
+    const result = await this.query(
+      `DELETE FROM memories WHERE organization = $1`,
+      [organization]
+    );
+    return result.rowCount ?? 0;
+  }
+  async getHistory(memoryId) {
+    const result = await this.query(
+      `SELECT id, memory_id, event_type, related_memory_id, created_at
+       FROM memory_history WHERE memory_id = $1 ORDER BY created_at ASC`,
+      [memoryId]
+    );
+    return result.rows.map((row) => ({
+      id: String(row.id),
+      memory_id: String(row.memory_id),
+      event_type: row.event_type,
+      related_memory_id: row.related_memory_id === null ? null : String(row.related_memory_id),
+      created_at: String(row.created_at)
+    }));
+  }
+  async insertHistoryEvent(event) {
+    await this.query(
+      `INSERT INTO memory_history (id, memory_id, event_type, related_memory_id, created_at)
+       VALUES ($1,$2,$3,$4,$5)`,
+      [
+        event.id,
+        event.memory_id,
+        event.event_type,
+        event.related_memory_id,
+        event.created_at
+      ]
+    );
+  }
+  async getStats(organization) {
+    const result = await this.query(
+      `SELECT
+         COUNT(*)::int AS memories,
+         COUNT(*) FILTER (WHERE archived = false)::int AS active,
+         COUNT(*) FILTER (WHERE archived = true)::int AS archived,
+         COUNT(DISTINCT agent) FILTER (WHERE archived = false)::int AS agents
+       FROM memories WHERE organization = $1`,
+      [organization]
+    );
+    return {
+      totalMemories: Number(result.rows[0]?.memories ?? 0),
+      activeMemories: Number(result.rows[0]?.active ?? 0),
+      archivedMemories: Number(result.rows[0]?.archived ?? 0),
+      totalAgents: Number(result.rows[0]?.agents ?? 0)
+    };
+  }
+  async getDatabaseSizeBytes() {
+    const result = await this.query(
+      `SELECT pg_database_size(current_database())::bigint AS size`
+    );
+    return Number(result.rows[0]?.size ?? 0);
+  }
+  async withTransaction(fn) {
+    const existing = 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;
+      }
+      throw new DatabaseError(`Transaction failed: ${this.describe(error)}`, {
+        cause: error instanceof Error ? error : void 0
+      });
+    } finally {
+      client.release();
+    }
+  }
+  async runMigrations() {
+    await this.query(`
+      CREATE TABLE IF NOT EXISTS Wolbarg_meta (
+        key TEXT PRIMARY KEY NOT NULL,
+        value TEXT NOT NULL
+      )
+    `);
+    await this.query(`
+      CREATE TABLE IF NOT EXISTS memories (
+        id TEXT PRIMARY KEY NOT NULL,
+        organization TEXT NOT NULL,
+        agent TEXT NOT NULL,
+        content_text TEXT NOT NULL,
+        metadata_json JSONB NOT NULL DEFAULT '{}'::jsonb,
+        archived BOOLEAN NOT NULL DEFAULT false,
+        compressed_into TEXT NULL REFERENCES memories(id) ON DELETE SET NULL,
+        created_at TIMESTAMPTZ NOT NULL,
+        updated_at TIMESTAMPTZ NOT NULL
+      )
+    `);
+    await this.query(`
+      CREATE TABLE IF NOT EXISTS memory_history (
+        id TEXT PRIMARY KEY NOT NULL,
+        memory_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+        event_type TEXT NOT NULL CHECK (event_type IN ('created', 'archived', 'compressed')),
+        related_memory_id TEXT NULL,
+        created_at TIMESTAMPTZ NOT NULL
+      )
+    `);
+    await this.query(`
+      CREATE TABLE IF NOT EXISTS memory_row_map (
+        memory_id TEXT PRIMARY KEY REFERENCES memories(id) ON DELETE CASCADE,
+        row_num BIGSERIAL UNIQUE NOT NULL
+      )
+    `);
+    await this.query(
+      `CREATE INDEX IF NOT EXISTS idx_memories_org_agent ON memories(organization, agent)`
+    );
+    await this.query(
+      `CREATE INDEX IF NOT EXISTS idx_memories_org_archived ON memories(organization, archived)`
+    );
+    await this.query(
+      `CREATE INDEX IF NOT EXISTS idx_memories_org_active_created
+       ON memories(organization, created_at) WHERE archived = false`
+    ).catch(() => void 0);
+    await this.query(
+      `CREATE INDEX IF NOT EXISTS idx_memories_metadata ON memories USING GIN (metadata_json)`
+    );
+    try {
+      await this.query(`
+        ALTER TABLE memories
+        ADD COLUMN IF NOT EXISTS content_tsv tsvector
+        GENERATED ALWAYS AS (to_tsvector('english', content_text)) STORED
+      `);
+      await this.query(
+        `CREATE INDEX IF NOT EXISTS idx_memories_content_tsv ON memories USING GIN (content_tsv)`
+      );
+      this.hasContentTsv = true;
+    } catch {
+      await this.query(
+        `CREATE INDEX IF NOT EXISTS idx_memories_fts
+         ON memories USING GIN (to_tsvector('english', content_text))`
+      ).catch(() => void 0);
+      this.hasContentTsv = false;
+    }
+    const versionRow = await this.query(
+      `SELECT value FROM Wolbarg_meta WHERE key = $1`,
+      [META_KEYS.schemaVersion]
+    );
+    if (!versionRow.rows[0]) {
+      await this.query(
+        `INSERT INTO Wolbarg_meta (key, value) VALUES ($1, $2)`,
+        [META_KEYS.schemaVersion, String(SCHEMA_VERSION)]
+      );
+    }
+  }
+  async tryEnablePgvector() {
+    try {
+      await this.query(`CREATE EXTENSION IF NOT EXISTS vector`);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async insertEmbedding(memoryId, embedding) {
+    if (this.hasPgvector) {
+      await this.query(
+        `WITH mapped AS (
+           INSERT INTO memory_row_map (memory_id) VALUES ($1)
+           ON CONFLICT (memory_id) DO NOTHING
+         )
+         INSERT INTO memory_embeddings (memory_id, embedding)
+         VALUES ($1, $2::vector)
+         ON CONFLICT (memory_id) DO UPDATE SET embedding = EXCLUDED.embedding`,
+        [memoryId, toVectorLiteral(embedding)]
+      );
+      return;
+    }
+    const buf = Buffer.from(
+      embedding.buffer,
+      embedding.byteOffset,
+      embedding.byteLength
+    );
+    await this.query(
+      `WITH mapped AS (
+         INSERT INTO memory_row_map (memory_id) VALUES ($1)
+         ON CONFLICT (memory_id) DO NOTHING
+       )
+       INSERT INTO memory_embeddings_blob (memory_id, embedding)
+       VALUES ($1, $2)
+       ON CONFLICT (memory_id) DO UPDATE SET embedding = EXCLUDED.embedding`,
+      [memoryId, buf]
+    );
+  }
+  async deleteEmbedding(memoryId) {
+    await this.query(`DELETE FROM memory_embeddings WHERE memory_id = $1`, [memoryId]).catch(() => void 0);
+    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 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 target = tx ?? this.requirePool();
+    return target.query({ name, text, values: params });
+  }
+  mapRow(row) {
+    const meta2 = row.metadata_json;
+    let metadata_json;
+    if (typeof meta2 === "string") {
+      metadata_json = meta2;
+    } else if (meta2 && typeof meta2 === "object") {
+      metadata_json = JSON.stringify(meta2);
+    } else {
+      metadata_json = "{}";
+    }
+    const created = row.created_at instanceof Date ? row.created_at.toISOString() : String(row.created_at);
+    const updated = row.updated_at instanceof Date ? row.updated_at.toISOString() : String(row.updated_at);
+    return {
+      id: String(row.id),
+      organization: String(row.organization),
+      agent: String(row.agent),
+      content_text: String(row.content_text),
+      metadata_json,
+      archived: Number(row.archived ?? 0),
+      compressed_into: row.compressed_into === null || row.compressed_into === void 0 ? null : String(row.compressed_into),
+      created_at: created,
+      updated_at: updated,
+      rowid: row.rowid !== void 0 ? Number(row.rowid) : void 0
+    };
+  }
+  requirePool() {
+    if (!this.pool) {
+      throw new DatabaseError("Database is not open. Call open() first.");
+    }
+    return this.pool;
+  }
+  requireVectorReady() {
+    if (this.vectorDimensions === null) {
+      throw new DatabaseError(
+        "Vector index is not ready. Embedding dimensions have not been initialized."
+      );
+    }
+  }
+  describe(error) {
+    if (error instanceof Error) {
+      const aggregate = error;
+      if (Array.isArray(aggregate.errors) && aggregate.errors.length > 0) {
+        const nested = aggregate.errors.map((item) => item instanceof Error ? item.message : String(item)).join("; ");
+        return `${error.message || error.name}: ${nested}`;
+      }
+      return error.message || error.name;
+    }
+    return String(error);
+  }
+};
+
+// src/storage/index.ts
+function createStorageProvider(config) {
+  if (config.provider === "sqlite") {
+    return new SqliteStorageProvider({
+      connectionString: config.connectionString
+    });
+  }
+  if (config.provider === "postgres") {
+    return new PostgresStorageProvider({
+      connectionString: config.connectionString,
+      maxPoolSize: config.maxPoolSize
+    });
+  }
+  throw new ConfigurationError(
+    `Unsupported storage provider: ${String(config.provider)}`
+  );
+}
+function createDatabaseProvider(config) {
+  return createStorageProvider(config);
+}
+
+// src/memory/index.ts
+function toMemoryRecord(row) {
+  return {
+    id: row.id,
+    organization: row.organization,
+    agent: row.agent,
+    content: { text: row.content_text },
+    metadata: deserializeMetadata(row.metadata_json),
+    archived: row.archived === 1,
+    compressedInto: row.compressed_into,
+    createdAt: parseIso(row.created_at),
+    updatedAt: parseIso(row.updated_at)
+  };
+}
+function toRecallResult(row, similarity) {
+  return {
+    id: row.id,
+    organization: row.organization,
+    agent: row.agent,
+    content: { text: row.content_text },
+    metadata: deserializeMetadata(row.metadata_json),
+    archived: row.archived === 1,
+    similarity,
+    createdAt: parseIso(row.created_at),
+    updatedAt: parseIso(row.updated_at)
+  };
+}
+function toHistoryEvent(row) {
+  return {
+    id: row.id,
+    memoryId: row.memory_id,
+    eventType: row.event_type,
+    relatedMemoryId: row.related_memory_id,
+    createdAt: parseIso(row.created_at)
+  };
+}
+
+// src/retrieval/index.ts
+function fuseScores(semantic, keyword, weights) {
+  const ids = /* @__PURE__ */ new Set([...semantic.keys(), ...keyword.keys()]);
+  const fused = /* @__PURE__ */ new Map();
+  const semMax = Math.max(...semantic.values(), 1e-9);
+  const kwMax = Math.max(...keyword.values(), 1e-9);
+  for (const id of ids) {
+    const s = (semantic.get(id) ?? 0) / semMax;
+    const k = (keyword.get(id) ?? 0) / kwMax;
+    fused.set(
+      id,
+      weights.semanticWeight * s + weights.keywordWeight * k
+    );
+  }
+  return fused;
+}
+function resolveHybridWeights(hybrid) {
+  if (hybrid === false || hybrid === void 0) {
+    return null;
+  }
+  if (hybrid === true) {
+    return { semanticWeight: 0.7, keywordWeight: 0.3 };
+  }
+  return {
+    semanticWeight: hybrid.semanticWeight ?? 0.7,
+    keywordWeight: hybrid.keywordWeight ?? 0.3
+  };
+}
+function resolveMmr(mmr) {
+  if (mmr === false || mmr === void 0) {
+    return null;
+  }
+  if (mmr === true) {
+    return 0.5;
+  }
+  return mmr.lambda ?? 0.5;
+}
+function applyMmr(candidates, topK, lambda) {
+  if (candidates.length <= topK) {
+    return candidates;
+  }
+  const selected = [];
+  const remaining = [...candidates];
+  while (selected.length < topK && remaining.length > 0) {
+    let bestIdx = 0;
+    let bestScore = -Infinity;
+    for (let i = 0; i < remaining.length; i += 1) {
+      const candidate = remaining[i];
+      const relevance = candidate.similarity;
+      let maxSim = 0;
+      for (const chosen of selected) {
+        maxSim = Math.max(
+          maxSim,
+          jaccard(candidate.content.text, chosen.content.text)
+        );
+      }
+      const score = lambda * relevance - (1 - lambda) * maxSim;
+      if (score > bestScore) {
+        bestScore = score;
+        bestIdx = i;
+      }
+    }
+    selected.push(remaining[bestIdx]);
+    remaining.splice(bestIdx, 1);
+  }
+  return selected;
+}
+function jaccard(a, b) {
+  const ta = new Set(a.toLowerCase().split(/\s+/).filter(Boolean));
+  const tb = new Set(b.toLowerCase().split(/\s+/).filter(Boolean));
+  if (ta.size === 0 && tb.size === 0) {
+    return 1;
+  }
+  let inter = 0;
+  for (const t of ta) {
+    if (tb.has(t)) {
+      inter += 1;
+    }
+  }
+  const union = ta.size + tb.size - inter;
+  return union === 0 ? 0 : inter / union;
+}
+function adaptiveFetchK(topK, overFetchFactor, hasFilters) {
+  const factor = hasFilters ? Math.max(overFetchFactor, 4) : overFetchFactor;
+  return Math.min(Math.max(Math.ceil(topK * factor), topK), 1e3);
+}
+
+// src/core/options.ts
+function isEmbeddingProvider(value) {
+  return typeof value.embed === "function";
+}
+function isLlmProvider(value) {
+  return typeof value.complete === "function";
+}
+function isStorageProvider(value) {
+  return typeof value.open === "function";
+}
+
+// src/core/validate.ts
+function assertNonEmpty(value, fieldName) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new ConfigurationError(`${fieldName} must be a non-empty string`);
+  }
+}
+function assertUrl(value, fieldName) {
+  assertNonEmpty(value, fieldName);
+  try {
+    new URL(value);
+  } catch {
+    throw new ConfigurationError(
+      `${fieldName} must be a valid absolute URL (got "${value}")`
+    );
+  }
+}
+function validateEmbeddingConfig(config) {
+  assertUrl(config.baseUrl, "embedding.baseUrl");
+  assertNonEmpty(config.apiKey, "embedding.apiKey");
+  assertNonEmpty(config.model, "embedding.model");
+  if (config.timeoutMs !== void 0 && (!Number.isFinite(config.timeoutMs) || config.timeoutMs <= 0)) {
+    throw new ConfigurationError("embedding.timeoutMs must be a positive number");
+  }
+  return {
+    baseUrl: config.baseUrl.trim().replace(/\/+$/, ""),
+    apiKey: config.apiKey,
+    model: config.model.trim(),
+    ...config.timeoutMs !== void 0 ? { timeoutMs: config.timeoutMs } : {}
+  };
+}
+function validateLlmConfig(config) {
+  assertUrl(config.baseUrl, "llm.baseUrl");
+  assertNonEmpty(config.apiKey, "llm.apiKey");
+  assertNonEmpty(config.model, "llm.model");
+  if (config.temperature !== void 0 && (!Number.isFinite(config.temperature) || config.temperature < 0 || config.temperature > 2)) {
+    throw new ConfigurationError("llm.temperature must be between 0 and 2");
+  }
+  if (config.maxTokens !== void 0 && (!Number.isFinite(config.maxTokens) || config.maxTokens <= 0)) {
+    throw new ConfigurationError("llm.maxTokens must be a positive number");
+  }
+  if (config.timeoutMs !== void 0 && (!Number.isFinite(config.timeoutMs) || config.timeoutMs <= 0)) {
+    throw new ConfigurationError("llm.timeoutMs must be a positive number");
+  }
+  return {
+    baseUrl: config.baseUrl.trim().replace(/\/+$/, ""),
+    apiKey: config.apiKey,
+    model: config.model.trim(),
+    ...config.temperature !== void 0 ? { temperature: config.temperature } : {},
+    ...config.maxTokens !== void 0 ? { maxTokens: config.maxTokens } : {},
+    ...config.timeoutMs !== void 0 ? { timeoutMs: config.timeoutMs } : {}
+  };
+}
+function validateInitOptions(options) {
+  if (options === null || typeof options !== "object") {
+    throw new ConfigurationError("init options must be an object");
+  }
+  assertNonEmpty(options.organization, "organization");
+  if (!options.database || typeof options.database !== "object") {
+    throw new ConfigurationError("database configuration is required");
+  }
+  const provider = options.database.provider;
+  if (provider !== "sqlite" && provider !== "postgres") {
+    throw new ConfigurationError(
+      `Unsupported database provider "${String(options.database.provider)}". Supported: "sqlite", "postgres".`
+    );
+  }
+  assertNonEmpty(
+    options.database.connectionString,
+    "database.connectionString"
+  );
+  if (!options.embedding || typeof options.embedding !== "object") {
+    throw new ConfigurationError("embedding configuration is required");
+  }
+  const embedding = validateEmbeddingConfig(options.embedding);
+  const llm = options.llm ? validateLlmConfig(options.llm) : void 0;
+  return {
+    organization: options.organization.trim(),
+    database: provider === "postgres" ? {
+      provider: "postgres",
+      connectionString: options.database.connectionString.trim(),
+      ..."maxPoolSize" in options.database && options.database.maxPoolSize !== void 0 ? { maxPoolSize: options.database.maxPoolSize } : {}
+    } : {
+      provider: "sqlite",
+      connectionString: options.database.connectionString.trim()
+    },
+    embedding,
+    ...llm ? { llm } : {}
+  };
+}
+function validateWolbargOptions(options) {
+  if (options === null || typeof options !== "object") {
+    throw new ConfigurationError("Wolbarg options must be an object");
+  }
+  assertNonEmpty(options.organization, "organization");
+  if (!options.storage) {
+    throw new ConfigurationError("storage is required");
+  }
+  if (!isStorageProvider(options.storage)) {
+    if (typeof options.storage !== "object" || !("provider" in options.storage) || !("connectionString" in options.storage)) {
+      throw new ConfigurationError("storage must be a provider instance or config");
+    }
+    assertNonEmpty(options.storage.connectionString, "storage.connectionString");
+  }
+  if (!options.embedding) {
+    throw new ConfigurationError("embedding is required");
+  }
+  if (!isEmbeddingProvider(options.embedding)) {
+    validateEmbeddingConfig(options.embedding);
+  }
+  if (options.llm !== void 0 && !isLlmProvider(options.llm)) {
+    validateLlmConfig(options.llm);
+  }
+  return {
+    ...options,
+    organization: options.organization.trim()
+  };
+}
+
+// src/core/wolbarg.ts
+var Wolbarg = class {
+  initialized = false;
+  booting = null;
+  organization = null;
+  storage = null;
+  embedding = null;
+  llm = null;
+  compression = null;
+  reranker = null;
+  keywordSearch = null;
+  ocr = null;
+  vision = null;
+  chunking = null;
+  retrievalConfig = {};
+  embeddingDimensions = null;
+  writeMutex = new AsyncMutex();
+  constructor(options) {
+    if (!options) {
+      return;
+    }
+    const validated = validateWolbargOptions(options);
+    this.organization = validated.organization;
+    this.storage = isStorageProvider(validated.storage) ? validated.storage : createStorageProvider(validated.storage);
+    this.embedding = isEmbeddingProvider(validated.embedding) ? validated.embedding : createEmbeddingProvider(validated.embedding);
+    if (validated.llm) {
+      this.llm = isLlmProvider(validated.llm) ? validated.llm : createLlmProvider(validated.llm);
+      this.compression = validated.compression ?? createCompressionProvider(this.llm);
+    } else {
+      this.compression = validated.compression ?? null;
+    }
+    this.reranker = validated.reranker ?? null;
+    this.keywordSearch = validated.keywordSearch ?? null;
+    this.ocr = validated.ocr ?? null;
+    this.vision = validated.vision ?? null;
+    this.chunking = validated.chunking ?? null;
+    this.retrievalConfig = validated.retrieval ?? {};
+  }
+  /**
+   * Backwards-compatible initialization (v0.1 API).
+   * Prefer the constructor with `storage` / `embedding` / optional `llm`.
+   */
+  async init(options) {
+    if (this.initialized || this.storage) {
+      throw new InitializationError("Wolbarg is already initialized");
+    }
+    let validated;
+    try {
+      validated = validateInitOptions(options);
+    } catch (error) {
+      if (error instanceof ConfigurationError || error instanceof ValidationError) {
+        throw error;
+      }
+      throw new ConfigurationError(
+        `Invalid configuration: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error instanceof Error ? error : void 0 }
+      );
+    }
+    this.organization = validated.organization;
+    this.storage = createStorageProvider(validated.database);
+    this.embedding = createEmbeddingProvider(validated.embedding);
+    if (validated.llm) {
+      this.llm = createLlmProvider(validated.llm);
+      this.compression = createCompressionProvider(this.llm);
+    }
+    await this.ready();
+  }
+  /** Ensure storage is open and embedding dimensions are known. */
+  async ready() {
+    if (this.initialized) {
+      return;
+    }
+    if (this.booting) {
+      await this.booting;
+      return;
+    }
+    this.booting = this.boot();
+    try {
+      await this.booting;
+    } finally {
+      this.booting = null;
+    }
+  }
+  async boot() {
+    if (!this.storage || !this.embedding || !this.organization) {
+      throw new InitializationError(
+        "Wolbarg is not configured. Pass options to the constructor or call init()."
+      );
+    }
+    try {
+      await this.storage.open();
+      const probe = await this.embedding.validate();
+      await this.storage.ensureVectorSchema(probe.dimensions);
+      this.embeddingDimensions = probe.dimensions;
+      this.initialized = true;
+    } catch (error) {
+      await this.storage.close().catch(() => void 0);
+      this.initialized = false;
+      if (error instanceof ConfigurationError || error instanceof InitializationError || error instanceof ValidationError) {
+        throw error;
+      }
+      throw new InitializationError(
+        `Initialization failed: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error instanceof Error ? error : void 0 }
+      );
+    }
+  }
+  /** Store a semantic memory for an agent. */
+  async remember(options) {
+    const { storage, embedding, organization } = await this.requireReady();
+    assertNonEmptyString(options.agent, "agent");
+    if (!options.content || typeof options.content.text !== "string") {
+      throw new ValidationError("content.text must be a string");
+    }
+    assertNonEmptyString(options.content.text, "content.text");
+    const metadata = options.metadata ?? {};
+    if (metadata === null || typeof metadata !== "object" || Array.isArray(metadata)) {
+      throw new ValidationError("metadata must be a plain object when provided");
+    }
+    const profile = process.env.WOLBARG_PROFILE === "1";
+    const t0 = profile ? performance.now() : 0;
+    const vector = await embedding.embed(options.content.text);
+    const embedMs = profile ? performance.now() - t0 : 0;
+    this.assertEmbeddingDimensions(vector.length);
+    const id = createId();
+    const timestamp = nowIso();
+    return this.withWriteLock(async () => {
+      const tStore = profile ? performance.now() : 0;
+      const row = await storage.insertMemory({
+        id,
+        organization,
+        agent: options.agent.trim(),
+        contentText: options.content.text,
+        metadata,
+        embedding: vector,
+        createdAt: timestamp,
+        updatedAt: timestamp
+      });
+      if (profile) {
+        const storeMs = performance.now() - tStore;
+        const totalMs = performance.now() - t0;
+        console.log(
+          `[profile] remember embed=${embedMs.toFixed(2)}ms store=${storeMs.toFixed(2)}ms total=${totalMs.toFixed(2)}ms backend=${storage.name}`
+        );
+      }
+      return toMemoryRecord(row);
+    });
+  }
+  /**
+   * Semantic / hybrid search over stored memories.
+   * Optional keyword, metadata, MMR, and rerank stages degrade gracefully.
+   */
+  async recall(options) {
+    const { storage, embedding, organization } = await this.requireReady();
+    assertNonEmptyString(options.query, "query");
+    const topK = options.topK ?? 5;
+    const threshold = options.threshold ?? 0;
+    assertFiniteNumber(topK, "topK", { min: 1, max: 1e3 });
+    assertFiniteNumber(threshold, "threshold", { min: 0, max: 1 });
+    const query = options.query.trim();
+    const vector = await embedding.embed(query);
+    this.assertEmbeddingDimensions(vector.length);
+    const hasFilters = Boolean(
+      options.filter?.agent || options.filter?.metadata
+    );
+    const overFetch = this.retrievalConfig.overFetchFactor ?? (hasFilters ? 4 : 2);
+    const fetchK = adaptiveFetchK(topK, overFetch, hasFilters);
+    const semanticScores = /* @__PURE__ */ new Map();
+    const byId = /* @__PURE__ */ new Map();
+    const joined = storage.searchVectorsWithMemories;
+    if (typeof joined === "function") {
+      const joinedHits = await joined.call(
+        storage,
+        vector,
+        fetchK,
+        organization,
+        {
+          agent: options.filter?.agent,
+          includeArchived: options.filter?.includeArchived
+        }
+      );
+      for (const { row, distance } of joinedHits) {
+        if (options.filter?.metadata && !matchesMetadata(
+          deserializeMetadata(row.metadata_json),
+          options.filter.metadata
+        )) {
+          continue;
+        }
+        const similarity = distanceToSimilarity(distance);
+        if (similarity < threshold) {
+          continue;
+        }
+        const result = toRecallResult(row, similarity);
+        semanticScores.set(result.id, similarity);
+        byId.set(result.id, result);
+      }
+    } else {
+      const hits = await storage.searchVectors(vector, fetchK);
+      const rowids = hits.map((h) => h.memoryRowid);
+      let rowMap;
+      if (typeof storage.getMemoriesByRowids === "function") {
+        rowMap = await storage.getMemoriesByRowids(rowids, organization);
+      } else {
+        rowMap = /* @__PURE__ */ new Map();
+        const looked = await Promise.all(
+          hits.map(async (hit) => ({
+            hit,
+            row: await storage.getMemoryByRowid(hit.memoryRowid, organization)
+          }))
+        );
+        for (const { hit, row } of looked) {
+          if (row) rowMap.set(hit.memoryRowid, row);
+        }
+      }
+      for (const hit of hits) {
+        const row = rowMap.get(hit.memoryRowid);
+        if (!row) {
+          continue;
+        }
+        if (options.filter?.agent && row.agent !== options.filter.agent) {
+          continue;
+        }
+        if (!options.filter?.includeArchived && row.archived === 1) {
+          continue;
+        }
+        const metadata = deserializeMetadata(row.metadata_json);
+        if (options.filter?.metadata && !matchesMetadata(metadata, options.filter.metadata)) {
+          continue;
+        }
+        const similarity = distanceToSimilarity(hit.distance);
+        if (similarity < threshold) {
+          continue;
+        }
+        const result = toRecallResult(row, similarity);
+        semanticScores.set(result.id, similarity);
+        byId.set(result.id, result);
+      }
+    }
+    const hybridWeights = resolveHybridWeights(options.hybrid) ?? (options.hybrid === void 0 ? resolveHybridWeights(this.retrievalConfig.hybrid) : null);
+    if (hybridWeights) {
+      let keywordScores = /* @__PURE__ */ new Map();
+      if (typeof storage.searchKeyword === "function") {
+        const ftsHits = await storage.searchKeyword(
+          query,
+          organization,
+          fetchK
+        );
+        keywordScores = new Map(
+          ftsHits.map((h) => [h.memoryId, h.score])
+        );
+        const missingIds = [];
+        for (const id of keywordScores.keys()) {
+          if (!byId.has(id)) missingIds.push(id);
+        }
+        if (missingIds.length > 0) {
+          const fetched = await Promise.all(
+            missingIds.map((id) => storage.getMemoryById(id, organization))
+          );
+          for (const row of fetched) {
+            if (!row) continue;
+            if (options.filter?.agent && row.agent !== options.filter.agent) {
+              continue;
+            }
+            if (!options.filter?.includeArchived && row.archived === 1) {
+              continue;
+            }
+            if (options.filter?.metadata && !matchesMetadata(
+              deserializeMetadata(row.metadata_json),
+              options.filter.metadata
+            )) {
+              continue;
+            }
+            byId.set(row.id, toRecallResult(row, 0));
+          }
+        }
+      } else if (this.keywordSearch) {
+        const corpus = await storage.listMemories(
+          {
+            organization,
+            agent: options.filter?.agent,
+            includeArchived: options.filter?.includeArchived,
+            metadata: options.filter?.metadata
+          },
+          Math.min(fetchK * 2, 2e3)
+        );
+        const keywordHits = await this.keywordSearch.search(
+          query,
+          corpus.map((row) => ({ id: row.id, text: row.content_text })),
+          fetchK
+        );
+        keywordScores = new Map(
+          keywordHits.map((h) => [h.memoryId, h.score])
+        );
+        for (const row of corpus) {
+          if (byId.has(row.id)) {
+            continue;
+          }
+          if (!keywordScores.has(row.id)) {
+            continue;
+          }
+          const metadata = deserializeMetadata(row.metadata_json);
+          if (options.filter?.metadata && !matchesMetadata(metadata, options.filter.metadata)) {
+            continue;
+          }
+          if (!options.filter?.includeArchived && row.archived === 1) {
+            continue;
+          }
+          byId.set(row.id, toRecallResult(row, 0));
+        }
+      }
+      if (keywordScores.size > 0) {
+        const fused = fuseScores(semanticScores, keywordScores, hybridWeights);
+        for (const [id, score] of fused) {
+          const existing = byId.get(id);
+          if (existing) {
+            byId.set(id, { ...existing, similarity: score });
+          }
+        }
+      }
+    }
+    let results = [...byId.values()].sort(
+      (a, b) => b.similarity - a.similarity
+    );
+    const mmrLambda = resolveMmr(options.mmr) ?? resolveMmr(
+      this.retrievalConfig.mmr ? { lambda: this.retrievalConfig.mmr.lambda } : void 0
+    );
+    if (mmrLambda !== null) {
+      results = applyMmr(results, Math.max(topK * 2, topK), mmrLambda);
+    }
+    if (options.rerank && this.reranker) {
+      const reranked = await this.reranker.rerank(
+        query,
+        results.map((r) => ({ id: r.id, text: r.content.text })),
+        topK
+      );
+      const order = new Map(reranked.map((r, i) => [r.id, { score: r.score, i }]));
+      results = results.filter((r) => order.has(r.id)).sort((a, b) => order.get(a.id).i - order.get(b.id).i).map((r) => ({
+        ...r,
+        similarity: order.get(r.id)?.score ?? r.similarity
+      }));
+    }
+    return results.slice(0, topK);
+  }
+  /**
+   * Compress related memories for an agent into a single summarized memory.
+   * Only available when `llm` (or `compression`) was configured at construction.
+   */
+  async compress(options) {
+    return this.runCompress(options);
+  }
+  /** @internal */
+  async runCompress(options) {
+    const { storage, embedding, organization } = await this.requireReady();
+    if (!this.compression) {
+      throw new ProviderNotConfiguredError(
+        "llm",
+        "compress",
+        "pass llm: openaiLlm(...) (or compression) in the constructor"
+      );
+    }
+    assertNonEmptyString(options.agent, "agent");
+    const limit = options.limit ?? 50;
+    assertFiniteNumber(limit, "limit", { min: 2, max: 500 });
+    const rows = await storage.listMemories(
+      {
+        organization,
+        agent: options.agent.trim(),
+        includeArchived: false
+      },
+      limit
+    );
+    if (rows.length < 2) {
+      throw new ValidationError(
+        "compress requires at least 2 active memories for the given agent"
+      );
+    }
+    const records = rows.map(toMemoryRecord);
+    const summaryText = await this.compression.compress(records);
+    const vector = await embedding.embed(summaryText);
+    this.assertEmbeddingDimensions(vector.length);
+    const summaryId = createId();
+    const timestamp = nowIso();
+    return this.withWriteLock(async () => {
+      const summaryRow = await storage.insertMemory({
+        id: summaryId,
+        organization,
+        agent: options.agent.trim(),
+        contentText: summaryText,
+        metadata: {
+          compressed: true,
+          sourceCount: records.length,
+          sourceIds: records.map((r) => r.id)
+        },
+        embedding: vector,
+        createdAt: timestamp,
+        updatedAt: timestamp
+      });
+      const archivedIds = await storage.archiveMemories(
+        records.map((r) => r.id),
+        organization,
+        summaryId,
+        timestamp
+      );
+      return {
+        summary: toMemoryRecord(summaryRow),
+        archivedIds
+      };
+    });
+  }
+  /** Ingest a document: parse → OCR/vision (optional) → chunk → embed → store. */
+  async ingest(options) {
+    const { storage, embedding, organization } = await this.requireReady();
+    assertNonEmptyString(options.agent, "agent");
+    const loaded = await loadIngestSource(options.source);
+    let usedOcr = false;
+    let usedVision = false;
+    let text = loaded.rawText ?? "";
+    if (!loaded.rawText) {
+      const parser = resolveParser(loaded.filename, loaded.mimeType);
+      const parsed = await parser.parse({
+        buffer: loaded.buffer,
+        filename: loaded.filename,
+        mimeType: loaded.mimeType
+      });
+      text = parsed.text;
+      if (parsed.isImage && parsed.imageBuffer) {
+        const parts = [];
+        if (this.ocr) {
+          const ocrResult = await this.ocr.recognize(
+            parsed.imageBuffer,
+            parsed.mimeType
+          );
+          if (ocrResult.text) {
+            parts.push(ocrResult.text);
+            usedOcr = true;
+          }
+        }
+        if (this.vision) {
+          const visionResult = await this.vision.analyze(
+            parsed.imageBuffer,
+            parsed.mimeType
+          );
+          if (visionResult.caption) {
+            parts.push(`Caption: ${visionResult.caption}`);
+          }
+          if (visionResult.description) {
+            parts.push(visionResult.description);
+          }
+          if (visionResult.entities.length > 0) {
+            parts.push(`Entities: ${visionResult.entities.join(", ")}`);
+          }
+          if (parts.length > 0) {
+            usedVision = true;
+          }
+        }
+        text = parts.join("\n\n").trim();
+      }
+    }
+    if (!text) {
+      throw new ValidationError(
+        "ingest could not extract text from the document (configure ocr/vision for images, or provide text)"
+      );
+    }
+    const strategy = this.chunking ?? (options.chunking?.strategy ? createChunkingStrategy(options.chunking.strategy) : inferChunkingStrategy(text));
+    const chunks = strategy.chunk(text, {
+      chunkSize: options.chunking?.chunkSize,
+      overlap: options.chunking?.overlap
+    });
+    if (chunks.length === 0) {
+      throw new ValidationError("ingest produced zero chunks");
+    }
+    const vectors = await embedMany(
+      embedding,
+      chunks.map((c) => c.text)
+    );
+    for (const vector of vectors) {
+      this.assertEmbeddingDimensions(vector.length);
+    }
+    const baseMeta = options.metadata ?? {};
+    const timestamp = nowIso();
+    const inputs = chunks.map((chunk, i) => ({
+      id: createId(),
+      organization,
+      agent: options.agent.trim(),
+      contentText: chunk.text,
+      metadata: {
+        ...baseMeta,
+        ingest: true,
+        chunkIndex: chunk.index,
+        chunkCount: chunks.length,
+        sourceFilename: loaded.filename ?? null
+      },
+      embedding: vectors[i],
+      createdAt: timestamp,
+      updatedAt: timestamp
+    }));
+    const rows = await this.withWriteLock(async () => {
+      return storage.insertMemoriesBatch(inputs);
+    });
+    return {
+      memories: rows.map(toMemoryRecord),
+      extractedChars: text.length,
+      chunkCount: chunks.length,
+      usedOcr,
+      usedVision
+    };
+  }
+  /** Delete memories by ID or filter. */
+  async forget(options) {
+    const { storage, organization } = await this.requireReady();
+    return this.withWriteLock(async () => {
+      if ("id" in options && options.id !== void 0) {
+        assertNonEmptyString(options.id, "id");
+        const deleted = await storage.deleteMemoryById(
+          options.id.trim(),
+          organization
+        );
+        return deleted ? 1 : 0;
+      }
+      if ("filter" in options && options.filter?.agent) {
+        assertNonEmptyString(options.filter.agent, "filter.agent");
+        return storage.deleteMemoriesByFilter({
+          organization,
+          agent: options.filter.agent.trim(),
+          includeArchived: true
+        });
+      }
+      throw new ValidationError(
+        "forget requires either { id } or { filter: { agent } }"
+      );
+    });
+  }
+  /** Return the history of a memory. */
+  async history(options) {
+    const { storage, organization } = await this.requireReady();
+    assertNonEmptyString(options.id, "id");
+    const row = await storage.getMemoryById(options.id.trim(), organization);
+    if (!row) {
+      throw new MemoryNotFoundError(`Memory not found: ${options.id}`);
+    }
+    const events = await storage.getHistory(row.id);
+    return {
+      memory: toMemoryRecord(row),
+      events: events.map(toHistoryEvent)
+    };
+  }
+  /** Aggregate statistics for the current organization. */
+  async stats() {
+    const { storage, embedding, organization } = await this.requireReady();
+    const counts = await storage.getStats(organization);
+    const databaseSizeBytes = await storage.getDatabaseSizeBytes();
+    return {
+      totalMemories: counts.totalMemories,
+      activeMemories: counts.activeMemories,
+      archivedMemories: counts.archivedMemories,
+      totalAgents: counts.totalAgents,
+      databaseSizeBytes,
+      embeddingModel: embedding.model,
+      llmModel: this.llm?.model ?? null,
+      organization,
+      embeddingDimensions: this.embeddingDimensions ?? 0
+    };
+  }
+  /** Delete every memory in the current organization. */
+  async clear(options) {
+    const { storage, organization } = await this.requireReady();
+    if (!options || options.confirm !== true) {
+      throw new ValidationError(
+        "clear requires { confirm: true } to permanently delete all memories"
+      );
+    }
+    return this.withWriteLock(async () => {
+      return storage.clearOrganization(organization);
+    });
+  }
+  /**
+   * Serialize writes for SQLite (single connection). Postgres uses a pool and
+   * per-statement atomic CTEs — locking here only serializes throughput.
+   */
+  withWriteLock(fn) {
+    if (this.storage?.name === "sqlite") {
+      return this.writeMutex.runExclusive(fn);
+    }
+    return fn();
+  }
+  /** Close the database connection and release resources. */
+  async close() {
+    if (this.storage) {
+      await this.storage.close();
+    }
+    this.storage = null;
+    this.embedding = null;
+    this.llm = null;
+    this.compression = null;
+    this.organization = null;
+    this.embeddingDimensions = null;
+    this.initialized = false;
+  }
+  /** Whether providers are ready for API calls. */
+  get isInitialized() {
+    return this.initialized;
+  }
+  async requireReady() {
+    await this.ready();
+    if (!this.initialized || !this.storage || !this.embedding || !this.organization) {
+      throw new InitializationError(
+        "Wolbarg is not initialized. Pass options to the constructor or call init()."
+      );
+    }
+    return {
+      storage: this.storage,
+      embedding: this.embedding,
+      organization: this.organization
+    };
+  }
+  assertEmbeddingDimensions(dimensions) {
+    if (this.embeddingDimensions !== null && dimensions !== this.embeddingDimensions) {
+      throw new ValidationError(
+        `Embedding dimension mismatch: expected ${this.embeddingDimensions}, got ${dimensions}`
+      );
+    }
+  }
+};
+
+// src/filters/types.ts
+var meta = {
+  eq: (field, value) => ({
+    field,
+    op: { eq: value }
+  }),
+  contains: (field, value) => ({
+    field,
+    op: { contains: value }
+  }),
+  gt: (field, value) => ({
+    field,
+    op: { gt: value }
+  }),
+  gte: (field, value) => ({
+    field,
+    op: { gte: value }
+  }),
+  lt: (field, value) => ({
+    field,
+    op: { lt: value }
+  }),
+  lte: (field, value) => ({
+    field,
+    op: { lte: value }
+  }),
+  between: (field, lo, hi) => ({
+    field,
+    op: { between: [lo, hi] }
+  }),
+  and: (...filters) => ({ and: filters }),
+  or: (...filters) => ({ or: filters }),
+  not: (filter) => ({ not: filter })
+};
+
+// src/factories/index.ts
+function sqlite(connectionString) {
+  return new SqliteStorageProvider({ connectionString });
+}
+function sqliteConfig(connectionString) {
+  return { provider: "sqlite", connectionString };
+}
+function postgres(options) {
+  const opts = typeof options === "string" ? { connectionString: options } : options;
+  return new PostgresStorageProvider(opts);
+}
+function postgresConfig(connectionString, options) {
+  return {
+    provider: "postgres",
+    connectionString,
+    ...options
+  };
+}
+
+// src/keyword/index.ts
+var Bm25KeywordSearchProvider = class {
+  name = "bm25";
+  k1;
+  b;
+  constructor(options) {
+    this.k1 = options?.k1 ?? 1.2;
+    this.b = options?.b ?? 0.75;
+  }
+  async search(query, documents, topK) {
+    if (documents.length === 0 || topK <= 0) {
+      return [];
+    }
+    const docs = documents.map((doc) => ({
+      id: doc.id,
+      tokens: tokenize(doc.text)
+    }));
+    const queryTokens = tokenize(query);
+    if (queryTokens.length === 0) {
+      return [];
+    }
+    const N = docs.length;
+    const avgdl = docs.reduce((sum, d) => sum + d.tokens.length, 0) / Math.max(N, 1);
+    const df = /* @__PURE__ */ new Map();
+    for (const term of new Set(queryTokens)) {
+      let count = 0;
+      for (const doc of docs) {
+        if (doc.tokens.includes(term)) {
+          count += 1;
+        }
+      }
+      df.set(term, count);
+    }
+    const scored = docs.map((doc) => {
+      const tfMap = /* @__PURE__ */ new Map();
+      for (const token of doc.tokens) {
+        tfMap.set(token, (tfMap.get(token) ?? 0) + 1);
+      }
+      let score = 0;
+      for (const term of queryTokens) {
+        const tf = tfMap.get(term) ?? 0;
+        if (tf === 0) {
+          continue;
+        }
+        const n = df.get(term) ?? 0;
+        const idf = Math.log(1 + (N - n + 0.5) / (n + 0.5));
+        const denom = tf + this.k1 * (1 - this.b + this.b * (doc.tokens.length / avgdl));
+        score += idf * (tf * (this.k1 + 1) / denom);
+      }
+      return { memoryId: doc.id, score };
+    });
+    scored.sort((a, b) => b.score - a.score);
+    return scored.filter((s) => s.score > 0).slice(0, topK);
+  }
+};
+function tokenize(text) {
+  return text.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((t) => t.length > 1);
+}
+function bm25(options) {
+  return new Bm25KeywordSearchProvider(options);
+}
+
+// src/rerank/index.ts
+var HttpRerankerProvider = class {
+  name;
+  options;
+  constructor(options) {
+    this.name = options.name;
+    this.options = options;
+  }
+  async rerank(query, documents, topK) {
+    if (documents.length === 0) {
+      return [];
+    }
+    const controller = new AbortController();
+    const timeoutMs = this.options.timeoutMs ?? 3e4;
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const res = await fetch(this.options.url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.options.apiKey}`
+        },
+        body: JSON.stringify(
+          this.options.buildBody(
+            query,
+            documents,
+            topK,
+            this.options.model
+          )
+        ),
+        signal: controller.signal
+      });
+      const body = await res.json().catch(() => ({}));
+      if (!res.ok) {
+        return documents.slice(0, topK).map((d, i) => ({
+          id: d.id,
+          score: 1 - i / Math.max(documents.length, 1)
+        }));
+      }
+      const parsed = this.options.parseResults(body, documents);
+      return parsed.slice(0, topK);
+    } catch {
+      return documents.slice(0, topK).map((d, i) => ({
+        id: d.id,
+        score: 1 - i / Math.max(documents.length, 1)
+      }));
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+function crossEncoder(options) {
+  const base = options.baseUrl.replace(/\/+$/, "");
+  return new HttpRerankerProvider({
+    name: "cross-encoder",
+    url: `${base}/rerank`,
+    apiKey: options.apiKey,
+    model: options.model,
+    timeoutMs: options.timeoutMs,
+    buildBody: (query, documents, topK, model) => ({
+      model,
+      query,
+      documents: documents.map((d) => d.text),
+      top_n: topK
+    }),
+    parseResults: (body, documents) => {
+      const results = body.results ?? [];
+      return results.map((r) => ({
+        id: documents[r.index]?.id ?? String(r.index),
+        score: r.relevance_score
+      }));
+    }
+  });
+}
+function jinaReranker(options) {
+  return new HttpRerankerProvider({
+    name: "jina",
+    url: "https://api.jina.ai/v1/rerank",
+    apiKey: options.apiKey,
+    model: options.model ?? "jina-reranker-v2-base-multilingual",
+    timeoutMs: options.timeoutMs,
+    buildBody: (query, documents, topK, model) => ({
+      model,
+      query,
+      documents: documents.map((d) => d.text),
+      top_n: topK
+    }),
+    parseResults: (body, documents) => {
+      const results = body.results ?? [];
+      return results.map((r) => ({
+        id: documents[r.index]?.id ?? String(r.index),
+        score: r.relevance_score
+      }));
+    }
+  });
+}
+function cohereReranker(options) {
+  return new HttpRerankerProvider({
+    name: "cohere",
+    url: "https://api.cohere.com/v2/rerank",
+    apiKey: options.apiKey,
+    model: options.model ?? "rerank-v3.5",
+    timeoutMs: options.timeoutMs,
+    buildBody: (query, documents, topK, model) => ({
+      model,
+      query,
+      documents: documents.map((d) => d.text),
+      top_n: topK
+    }),
+    parseResults: (body, documents) => {
+      const results = body.results ?? [];
+      return results.map((r) => ({
+        id: documents[r.index]?.id ?? String(r.index),
+        score: r.relevance_score
+      }));
+    }
+  });
+}
+function bgeReranker(options) {
+  const base = options.baseUrl.replace(/\/+$/, "");
+  return new HttpRerankerProvider({
+    name: "bge",
+    url: `${base}/rerank`,
+    apiKey: options.apiKey,
+    model: options.model,
+    timeoutMs: options.timeoutMs,
+    buildBody: (query, documents, topK, model) => ({
+      model,
+      query,
+      documents: documents.map((d) => d.text),
+      top_n: topK
+    }),
+    parseResults: (body, documents) => {
+      const results = body.results ?? [];
+      return results.map((r) => ({
+        id: documents[r.index]?.id ?? String(r.index),
+        score: r.relevance_score
+      }));
+    }
+  });
+}
+function openaiReranker(options) {
+  const base = (options.baseUrl ?? "https://api.openai.com/v1").replace(
+    /\/+$/,
+    ""
+  );
+  const model = options.model ?? "gpt-4.1-mini";
+  const timeoutMs = options.timeoutMs ?? 6e4;
+  return {
+    name: "openai",
+    async rerank(query, documents, topK) {
+      if (documents.length === 0) {
+        return [];
+      }
+      const listed = documents.map((d, i) => `[${i}] ${d.text.slice(0, 800)}`).join("\n\n");
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const res = await fetch(`${base}/chat/completions`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${options.apiKey}`
+          },
+          body: JSON.stringify({
+            model,
+            temperature: 0,
+            response_format: { type: "json_object" },
+            messages: [
+              {
+                role: "system",
+                content: 'You rerank documents for a retrieval system. Reply ONLY with JSON: {"results":[{"index":0,"score":0.0}]} where score is 0-1 relevance.'
+              },
+              {
+                role: "user",
+                content: `Query: ${query}
+
+Documents:
+${listed}
+
+Return the top ${topK} indices sorted by score descending.`
+              }
+            ]
+          }),
+          signal: controller.signal
+        });
+        const body = await res.json();
+        const content = body.choices?.[0]?.message?.content ?? "{}";
+        let parsed;
+        try {
+          parsed = JSON.parse(content);
+        } catch {
+          return documents.slice(0, topK).map((d, i) => ({
+            id: d.id,
+            score: 1 - i / Math.max(documents.length, 1)
+          }));
+        }
+        const results = parsed.results ?? [];
+        if (results.length === 0) {
+          return documents.slice(0, topK).map((d, i) => ({
+            id: d.id,
+            score: 1 - i / Math.max(documents.length, 1)
+          }));
+        }
+        return results.filter((r) => documents[r.index]).slice(0, topK).map((r) => ({
+          id: documents[r.index].id,
+          score: Number(r.score) || 0
+        }));
+      } catch {
+        return documents.slice(0, topK).map((d, i) => ({
+          id: d.id,
+          score: 1 - i / Math.max(documents.length, 1)
+        }));
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+  };
+}
+
+// src/ocr/index.ts
+function tesseract() {
+  return {
+    name: "tesseract",
+    async recognize(image) {
+      try {
+        const mod = await import('tesseract.js');
+        const createWorker = mod.createWorker ?? mod.default?.createWorker;
+        if (!createWorker) {
+          return { text: "" };
+        }
+        const worker = await createWorker("eng");
+        try {
+          const result = await worker.recognize(image);
+          return { text: result.data.text.trim() };
+        } finally {
+          await worker.terminate();
+        }
+      } catch {
+        return { text: "" };
+      }
+    }
+  };
+}
+
+// src/vision/index.ts
+var OpenAICompatibleVisionProvider = class {
+  name;
+  options;
+  constructor(options) {
+    this.name = options.name;
+    this.options = options;
+  }
+  async analyze(image, mimeType = "image/png") {
+    const base = this.options.baseUrl.replace(/\/+$/, "");
+    const url = `${base}/chat/completions`;
+    const dataUrl = `data:${mimeType};base64,${image.toString("base64")}`;
+    const controller = new AbortController();
+    const timer = setTimeout(
+      () => controller.abort(),
+      this.options.timeoutMs ?? 6e4
+    );
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.options.apiKey}`
+        },
+        body: JSON.stringify({
+          model: this.options.model,
+          messages: [
+            {
+              role: "user",
+              content: [
+                {
+                  type: "text",
+                  text: 'Describe this image. Reply as JSON: {"caption":"...","description":"...","entities":["..."]}'
+                },
+                { type: "image_url", image_url: { url: dataUrl } }
+              ]
+            }
+          ],
+          max_tokens: 512
+        }),
+        signal: controller.signal
+      });
+      const body = await res.json();
+      const content = body.choices?.[0]?.message?.content ?? "";
+      return parseVisionJson(content);
+    } catch {
+      return { caption: "", description: "", entities: [] };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+function parseVisionJson(content) {
+  try {
+    const match = content.match(/\{[\s\S]*\}/);
+    if (!match) {
+      return { caption: content.trim(), description: content.trim(), entities: [] };
+    }
+    const parsed = JSON.parse(match[0]);
+    return {
+      caption: String(parsed.caption ?? ""),
+      description: String(parsed.description ?? ""),
+      entities: Array.isArray(parsed.entities) ? parsed.entities.map(String) : []
+    };
+  } catch {
+    return { caption: content.trim(), description: content.trim(), entities: [] };
+  }
+}
+function geminiVision(options) {
+  return new OpenAICompatibleVisionProvider({
+    name: "gemini",
+    baseUrl: options.baseUrl ?? "https://generativelanguage.googleapis.com/v1beta/openai",
+    apiKey: options.apiKey,
+    model: options.model ?? "gemini-2.0-flash",
+    timeoutMs: options.timeoutMs
+  });
+}
+function openaiVision(options) {
+  return new OpenAICompatibleVisionProvider({
+    name: "openai-vision",
+    baseUrl: options.baseUrl ?? "https://api.openai.com/v1",
+    apiKey: options.apiKey,
+    model: options.model ?? "gpt-4o-mini",
+    timeoutMs: options.timeoutMs
+  });
+}
+
+exports.CompressionError = CompressionError;
+exports.ConfigurationError = ConfigurationError;
+exports.DatabaseError = DatabaseError;
+exports.EmbeddingError = EmbeddingError;
+exports.FixedChunkingStrategy = FixedChunkingStrategy;
+exports.HeadingChunkingStrategy = HeadingChunkingStrategy;
+exports.InitializationError = InitializationError;
+exports.LlmCompressionProvider = LlmCompressionProvider;
+exports.MarkdownChunkingStrategy = MarkdownChunkingStrategy;
+exports.MemoryNotFoundError = MemoryNotFoundError;
+exports.ParagraphChunkingStrategy = ParagraphChunkingStrategy;
+exports.PostgresStorageProvider = PostgresStorageProvider;
+exports.ProviderNotConfiguredError = ProviderNotConfiguredError;
+exports.SentenceChunkingStrategy = SentenceChunkingStrategy;
+exports.SqliteDatabaseProvider = SqliteDatabaseProvider;
+exports.SqliteStorageProvider = SqliteStorageProvider;
+exports.ValidationError = ValidationError;
+exports.Wolbarg = Wolbarg;
+exports.WolbargError = WolbargError;
+exports.bgeReranker = bgeReranker;
+exports.bm25 = bm25;
+exports.cohereReranker = cohereReranker;
+exports.createChunkingStrategy = createChunkingStrategy;
+exports.createCompressionProvider = createCompressionProvider;
+exports.createDatabaseProvider = createDatabaseProvider;
+exports.createEmbeddingProvider = createEmbeddingProvider;
+exports.createLlmProvider = createLlmProvider;
+exports.createStorageProvider = createStorageProvider;
+exports.crossEncoder = crossEncoder;
+exports.geminiEmbedding = geminiEmbedding;
+exports.geminiVision = geminiVision;
+exports.jinaReranker = jinaReranker;
+exports.lmStudioEmbedding = lmStudioEmbedding;
+exports.meta = meta;
+exports.ollamaEmbedding = ollamaEmbedding;
+exports.ollamaLlm = ollamaLlm;
+exports.openRouterEmbedding = openRouterEmbedding;
+exports.openRouterLlm = openRouterLlm;
+exports.openaiCompatibleEmbedding = openaiCompatibleEmbedding;
+exports.openaiCompatibleLlm = openaiCompatibleLlm;
+exports.openaiEmbedding = openaiEmbedding;
+exports.openaiLlm = openaiLlm;
+exports.openaiReranker = openaiReranker;
+exports.openaiVision = openaiVision;
+exports.postgres = postgres;
+exports.postgresConfig = postgresConfig;
+exports.sqlite = sqlite;
+exports.sqliteConfig = sqliteConfig;
+exports.tesseract = tesseract;
+exports.togetherEmbedding = togetherEmbedding;
+exports.vllmEmbedding = vllmEmbedding;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map