wolbarg 0.5.4 → 0.5.6

package/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.5.6] — 2026-07-24
+
+### Added
+
+- **`wolbarg` CLI** with `wolbarg init` — interactive (or `--yes`) project setup for database + embedding provider
+- Default SQLite path: `.wolbarg/shared-memory/memory.db`
+- Provider presets (OpenAI, Ollama, OpenRouter, LM Studio, Gemini, Together, vLLM, custom) with **visible default base URLs** the user can edit
+- Writes `.wolbarg/config.json` and optional `.wolbarg/.env` (API key); adds `.env` paths to `.gitignore`
+- **`createWolbargFromProjectConfig()`** / `loadProjectConfig()` to boot the SDK from init output
+
+### Compatibility
+
+- Additive. Existing programmatic `wolbarg({...})` usage unchanged.
+
+## [0.5.5] — 2026-07-21
+
+### Added
+
+- **Comprehensive JSDoc** across the SDK and official adapter packages — every exported function, method, class, interface, and notable helper now has descriptions with `@param` / `@returns` / `@example` where useful for IDE hover documentation
+- Provider interface docs explain how to implement custom storage, telemetry, checkpoint, graph, OCR, vision, rerank, and keyword backends
+
+### Changed
+
+- **`SDK_VERSION`** and package version bumped to **0.5.5**
+- Adapter packages peer-depend on `wolbarg >= 0.5.5`
+
+### Compatibility
+
+- Documentation-only release. No runtime API or schema changes from **0.5.4**.
+
 ## [0.5.3] — 2026-07-20
 
 ### Added

package/README.md

@@ -15,9 +15,39 @@
 npm install wolbarg
 ```
 
+### Configure with the CLI (recommended)
+
+```bash
+npx wolbarg init
+```
+
+You will be prompted (all optional — Enter accepts defaults):
+
+1. **Database** — default `.wolbarg/shared-memory/memory.db` (or a Postgres URL)
+2. **Embedding provider** — OpenAI, Ollama, OpenRouter, LM Studio, Gemini, Together, vLLM, or custom
+3. **Base URL** — always shown with that provider’s default (edit or keep)
+4. **Model** — provider default pre-filled
+5. **API key** — written to `.wolbarg/.env` (not into config JSON)
+
+Non-interactive:
+
+```bash
+npx wolbarg init --yes --provider openai --api-key "$OPENAI_API_KEY"
+npx wolbarg init --yes --skip-embedding
+```
+
+Then in code:
+
+```ts
+import { createWolbargFromProjectConfig } from "wolbarg";
+
+const ctx = createWolbargFromProjectConfig();
+await ctx.ready();
+```
+
 Wolbarg is **memory infrastructure**, not an agent framework. Agents call `remember()` / `recall()` (and optionally ingest, compress, subscribe, and link memories in a graph). You bring SQLite or PostgreSQL, any OpenAI-compatible embedding API, and optional peers for PDF/DOCX/OCR/Neo4j.
 
-**Current release: [v0.5.4](./CHANGELOG.md)** — official framework adapters (`@wolbarg/openai`, `@wolbarg/langchain`, `@wolbarg/llamaindex`, `@wolbarg/mastra`, `@wolbarg/vercel-ai`). Still includes experimental `rememberFromMessages()`, 0.5 graph memory (SQLite + Neo4j), `includeGraph` recall, and [Wolbarg Studio](https://wolbarg.com/docs/observability).
+**Current release: [v0.5.6](./CHANGELOG.md)** — `wolbarg init` CLI + project config loader. Still includes official framework adapters (`@wolbarg/openai`, `@wolbarg/langchain`, `@wolbarg/llamaindex`, `@wolbarg/mastra`, `@wolbarg/vercel-ai`), experimental `rememberFromMessages()`, 0.5 graph memory (SQLite + Neo4j), `includeGraph` recall, and [Wolbarg Studio](https://wolbarg.com/docs/observability).
 
 ---
 

package/dist/cli.js

@@ -0,0 +1,515 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
+import { isAbsolute, resolve, dirname, join } from "node:path";
+import * as readline from "node:readline/promises";
+import { stdout, stdin } from 'process';
+
+// src/version.ts
+var SDK_VERSION = "0.5.6";
+
+// src/config/providers.ts
+var EMBEDDING_PROVIDER_PRESETS = [
+  {
+    id: "openai",
+    label: "OpenAI",
+    defaultBaseUrl: "https://api.openai.com/v1",
+    defaultModel: "text-embedding-3-small",
+    apiKeyEnv: "OPENAI_API_KEY"
+  },
+  {
+    id: "ollama",
+    label: "Ollama (local)",
+    defaultBaseUrl: "http://127.0.0.1:11434/v1",
+    defaultModel: "nomic-embed-text",
+    apiKeyEnv: "OLLAMA_API_KEY",
+    apiKeyHint: "Any non-empty value works locally (e.g. ollama)"
+  },
+  {
+    id: "openrouter",
+    label: "OpenRouter",
+    defaultBaseUrl: "https://openrouter.ai/api/v1",
+    defaultModel: "openai/text-embedding-3-small",
+    apiKeyEnv: "OPENROUTER_API_KEY"
+  },
+  {
+    id: "lmstudio",
+    label: "LM Studio (local)",
+    defaultBaseUrl: "http://127.0.0.1:1234/v1",
+    defaultModel: "text-embedding-nomic-embed-text-v1.5",
+    apiKeyEnv: "LM_STUDIO_API_KEY",
+    apiKeyHint: "Often unused locally \u2014 any non-empty value is fine"
+  },
+  {
+    id: "gemini",
+    label: "Google Gemini",
+    defaultBaseUrl: "https://generativelanguage.googleapis.com/v1beta/openai",
+    defaultModel: "text-embedding-004",
+    apiKeyEnv: "GEMINI_API_KEY"
+  },
+  {
+    id: "together",
+    label: "Together AI",
+    defaultBaseUrl: "https://api.together.xyz/v1",
+    defaultModel: "togethercomputer/m2-bert-80M-8k-retrieval",
+    apiKeyEnv: "TOGETHER_API_KEY"
+  },
+  {
+    id: "vllm",
+    label: "vLLM (local/server)",
+    defaultBaseUrl: "http://127.0.0.1:8000/v1",
+    defaultModel: "text-embedding-ada-002",
+    apiKeyEnv: "VLLM_API_KEY",
+    apiKeyHint: "Only if your server requires auth"
+  },
+  {
+    id: "custom",
+    label: "Custom OpenAI-compatible",
+    defaultBaseUrl: "https://api.openai.com/v1",
+    defaultModel: "text-embedding-3-small",
+    apiKeyEnv: "WOLBARG_EMBEDDING_API_KEY"
+  }
+];
+function getEmbeddingProviderPreset(id) {
+  return EMBEDDING_PROVIDER_PRESETS.find((p) => p.id === id);
+}
+var DEFAULT_SQLITE_DB_PATH = ".wolbarg/shared-memory/memory.db";
+var DEFAULT_ORGANIZATION = "default";
+var DEFAULT_CONFIG_PATH = ".wolbarg/config.json";
+var DEFAULT_ENV_PATH = ".wolbarg/.env";
+
+// src/config/project-config.ts
+function defaultProjectConfig() {
+  return {
+    version: 1,
+    organization: DEFAULT_ORGANIZATION,
+    database: {
+      provider: "sqlite",
+      url: DEFAULT_SQLITE_DB_PATH
+    },
+    paths: {
+      config: DEFAULT_CONFIG_PATH
+    }
+  };
+}
+function resolveConfigPath(cwd = process.cwd(), configPath) {
+  const rel = configPath ?? DEFAULT_CONFIG_PATH;
+  return isAbsolute(rel) ? rel : resolve(cwd, rel);
+}
+function resolveEnvPath(cwd = process.cwd(), envPath) {
+  const rel = envPath ?? DEFAULT_ENV_PATH;
+  return isAbsolute(rel) ? rel : resolve(cwd, rel);
+}
+function saveProjectConfig(config, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const configPath = resolveConfigPath(cwd, options.configPath);
+  const dir = dirname(configPath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  if (existsSync(configPath) && options.overwrite === false) {
+    throw new Error(`Config already exists: ${configPath} (pass --force to overwrite)`);
+  }
+  const toWrite = {
+    ...config,
+    paths: {
+      config: options.configPath ?? DEFAULT_CONFIG_PATH,
+      ...options.envPath || options.apiKey ? { env: options.envPath ?? DEFAULT_ENV_PATH } : config.paths?.env ? { env: config.paths.env } : {}
+    }
+  };
+  writeFileSync(configPath, `${JSON.stringify(toWrite, null, 2)}
+`, "utf8");
+  let envPath;
+  if (options.apiKey && config.embedding?.apiKeyEnv) {
+    envPath = resolveEnvPath(cwd, options.envPath);
+    ensureParent(envPath);
+    upsertEnvVar(envPath, config.embedding.apiKeyEnv, options.apiKey);
+    ensureGitignore(cwd, [DEFAULT_ENV_PATH, ".env"]);
+  }
+  if (config.database.provider === "sqlite" && !config.database.url.includes("://")) {
+    const dbPath = isAbsolute(config.database.url) ? config.database.url : resolve(cwd, config.database.url);
+    ensureParent(dbPath);
+  }
+  return { configPath, envPath };
+}
+function ensureParent(filePath) {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+function upsertEnvVar(envPath, key, value) {
+  ensureParent(envPath);
+  let text = existsSync(envPath) ? readFileSync(envPath, "utf8") : "";
+  const line = `${key}=${shellQuoteEnv(value)}`;
+  const re = new RegExp(`^${escapeRegExp(key)}=.*$`, "m");
+  if (re.test(text)) {
+    text = text.replace(re, line);
+  } else {
+    if (text && !text.endsWith("\n")) text += "\n";
+    text += `${line}
+`;
+  }
+  writeFileSync(envPath, text, "utf8");
+}
+function shellQuoteEnv(value) {
+  if (/[\s#"']/.test(value)) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+  }
+  return value;
+}
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function ensureGitignore(cwd, entries) {
+  const gi = join(cwd, ".gitignore");
+  let text = existsSync(gi) ? readFileSync(gi, "utf8") : "";
+  let changed = false;
+  for (const entry of entries) {
+    if (text.split(/\r?\n/).some((l) => l.trim() === entry)) continue;
+    if (text && !text.endsWith("\n")) text += "\n";
+    text += `${entry}
+`;
+    changed = true;
+  }
+  if (changed) writeFileSync(gi, text, "utf8");
+}
+async function withReadline(fn) {
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  try {
+    return await fn(rl);
+  } finally {
+    rl.close();
+  }
+}
+async function askText(rl, label, defaultValue2) {
+  const hint = defaultValue2 !== void 0 && defaultValue2 !== "" ? ` [${defaultValue2}]` : "";
+  const answer = (await rl.question(`${label}${hint}: `)).trim();
+  if (answer === "") return defaultValue2 ?? "";
+  return answer;
+}
+async function askOptionalText(rl, label, defaultValue2) {
+  const hintParts = [];
+  if (defaultValue2 !== void 0 && defaultValue2 !== "") {
+    hintParts.push(`default: ${defaultValue2}`);
+  }
+  hintParts.push("Enter to accept", '"-" to skip/clear');
+  const answer = (await rl.question(`${label} (${hintParts.join(", ")}): `)).trim();
+  if (answer === "-") return void 0;
+  if (answer === "") {
+    return defaultValue2 === "" ? void 0 : defaultValue2;
+  }
+  return answer;
+}
+async function askSelect(rl, label, choices, defaultValue2, allowSkip = true) {
+  console.log(`
+${label}`);
+  choices.forEach((c, i) => {
+    const mark = c.value === defaultValue2 ? " (default)" : "";
+    console.log(`  ${i + 1}) ${c.label}${mark}`);
+  });
+  if (allowSkip) {
+    console.log(`  0) Skip`);
+  }
+  const defIndex = choices.findIndex((c) => c.value === defaultValue2) + 1 ;
+  const raw = (await rl.question(
+    `Choose [0-${choices.length}]${defIndex >= 0 ? ` (default ${defIndex})` : ""}: `
+  )).trim();
+  if (raw === "" && defIndex === 0 && allowSkip) return void 0;
+  if (raw === "" && defIndex > 0) return choices[defIndex - 1].value;
+  if (raw === "0" && allowSkip) return void 0;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 1 || n > choices.length) {
+    console.log("Invalid choice \u2014 skipped.");
+    return allowSkip ? void 0 : defaultValue2;
+  }
+  return choices[n - 1].value;
+}
+async function askConfirm(rl, label, defaultYes = true) {
+  const hint = defaultValue ? "Y/n" : "y/N";
+  const answer = (await rl.question(`${label} (${hint}): `)).trim().toLowerCase();
+  if (answer === "") return defaultValue;
+  if (answer === "y" || answer === "yes") return true;
+  if (answer === "n" || answer === "no") return false;
+  return defaultValue;
+}
+
+// src/cli/init.ts
+function printHelp() {
+  console.log(`Usage: wolbarg init [options]
+
+Configure Wolbarg for this project (database + optional embedding provider).
+
+All prompts are optional \u2014 press Enter to accept defaults, or skip embedding.
+
+Options:
+  -y, --yes                 Non-interactive; use defaults / flags
+  -f, --force               Overwrite existing .wolbarg/config.json
+  --org <name>              Organization id (default: ${DEFAULT_ORGANIZATION})
+  --db <path-or-url>        SQLite path or Postgres URL
+                            (default: ${DEFAULT_SQLITE_DB_PATH})
+  --db-provider <sqlite|postgres>
+  --provider <id>           Embedding provider preset
+                            (${EMBEDDING_PROVIDER_PRESETS.map((p) => p.id).join("|")})
+  --base-url <url>          Embedding API base URL (shown with provider default)
+  --model <id>              Embedding model id
+  --api-key <key>           Write API key into .wolbarg/.env
+  --api-key-env <NAME>      Env var name for the key
+  --skip-embedding          Do not configure embedding
+  -h, --help                Show help
+
+Examples:
+  wolbarg init
+  wolbarg init --yes
+  wolbarg init --provider ollama --model nomic-embed-text --api-key ollama
+  wolbarg init --db postgresql://user:pass@localhost:5432/wolbarg --db-provider postgres
+`);
+}
+function parseInitArgs(argv) {
+  const opts = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => {
+      const v = argv[++i];
+      if (v === void 0) throw new Error(`Missing value after ${a}`);
+      return v;
+    };
+    switch (a) {
+      case "-h":
+      case "--help":
+        return { help: true };
+      case "-y":
+      case "--yes":
+        opts.yes = true;
+        break;
+      case "-f":
+      case "--force":
+        opts.force = true;
+        break;
+      case "--org":
+        opts.organization = next();
+        break;
+      case "--db":
+        opts.db = next();
+        break;
+      case "--db-provider": {
+        const p = next();
+        if (p !== "sqlite" && p !== "postgres") {
+          throw new Error(`--db-provider must be sqlite|postgres`);
+        }
+        opts.dbProvider = p;
+        break;
+      }
+      case "--provider":
+        opts.provider = next();
+        break;
+      case "--base-url":
+        opts.baseUrl = next();
+        break;
+      case "--model":
+        opts.model = next();
+        break;
+      case "--api-key":
+        opts.apiKey = next();
+        break;
+      case "--api-key-env":
+        opts.apiKeyEnv = next();
+        break;
+      case "--skip-embedding":
+        opts.skipEmbedding = true;
+        break;
+      default:
+        throw new Error(`Unknown argument: ${a}`);
+    }
+  }
+  return opts;
+}
+function inferDbProvider(url, explicit) {
+  if (explicit) return explicit;
+  if (/^postgres(ql)?:\/\//i.test(url)) return "postgres";
+  return "sqlite";
+}
+async function runInit(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const configPath = resolveConfigPath(cwd);
+  if (existsSync(configPath) && !options.force && !options.yes) {
+    const overwrite = await withReadline(
+      (rl) => askConfirm(
+        rl,
+        `Config already exists at ${configPath}. Overwrite?`,
+        false
+      )
+    );
+    if (!overwrite) {
+      console.log("Aborted. Pass --force to overwrite.");
+      return 1;
+    }
+  } else if (existsSync(configPath) && options.yes && !options.force) {
+    console.error(
+      `Config already exists at ${configPath}. Re-run with --force to overwrite.`
+    );
+    return 1;
+  }
+  const config = defaultProjectConfig();
+  let apiKey;
+  if (options.yes) {
+    config.organization = options.organization ?? DEFAULT_ORGANIZATION;
+    const dbUrl = options.db ?? DEFAULT_SQLITE_DB_PATH;
+    config.database = {
+      provider: inferDbProvider(dbUrl, options.dbProvider),
+      url: dbUrl
+    };
+    if (!options.skipEmbedding) {
+      const providerId = options.provider ?? "openai";
+      const preset = getEmbeddingProviderPreset(providerId);
+      if (!preset) {
+        console.error(`Unknown provider: ${providerId}`);
+        return 1;
+      }
+      const baseUrl = options.baseUrl ?? preset.defaultBaseUrl;
+      const model = options.model ?? preset.defaultModel;
+      config.embedding = {
+        provider: preset.id,
+        baseUrl,
+        model,
+        apiKeyEnv: options.apiKeyEnv ?? preset.apiKeyEnv
+      };
+      apiKey = options.apiKey;
+    }
+  } else {
+    await withReadline(async (rl) => {
+      console.log("\nWolbarg init \u2014 all fields optional (Enter = default / skip).\n");
+      const org = await askOptionalText(
+        rl,
+        "Organization",
+        options.organization ?? DEFAULT_ORGANIZATION
+      );
+      config.organization = org ?? DEFAULT_ORGANIZATION;
+      const dbUrl = await askOptionalText(
+        rl,
+        "Database path or Postgres URL",
+        options.db ?? DEFAULT_SQLITE_DB_PATH
+      );
+      const resolvedDb = dbUrl ?? DEFAULT_SQLITE_DB_PATH;
+      config.database = {
+        provider: inferDbProvider(resolvedDb, options.dbProvider),
+        url: resolvedDb
+      };
+      if (options.skipEmbedding) {
+        return;
+      }
+      const providerId = options.provider ?? await askSelect(
+        rl,
+        "Embedding provider",
+        EMBEDDING_PROVIDER_PRESETS.map((p) => ({
+          value: p.id,
+          label: `${p.label} \u2014 ${p.defaultBaseUrl}`
+        })),
+        "openai",
+        true
+      );
+      if (!providerId) {
+        console.log("Skipping embedding configuration.");
+        return;
+      }
+      const preset = getEmbeddingProviderPreset(providerId);
+      if (!preset) {
+        console.log(`Unknown provider ${providerId}; skipping embedding.`);
+        return;
+      }
+      console.log(
+        `
+Provider default base URL for ${preset.label}: ${preset.defaultBaseUrl}`
+      );
+      const baseUrl = options.baseUrl ?? await askText(
+        rl,
+        "Embedding base URL",
+        preset.defaultBaseUrl
+      );
+      const model = options.model ?? await askText(rl, "Embedding model", preset.defaultModel);
+      const apiKeyEnv = options.apiKeyEnv ?? await askText(rl, "API key environment variable", preset.apiKeyEnv);
+      const keyPrompt = preset.apiKeyHint ? `API key (${preset.apiKeyHint})` : `API key (stored in ${DEFAULT_ENV_PATH} as ${apiKeyEnv})`;
+      const key = options.apiKey ?? await askOptionalText(rl, keyPrompt, void 0);
+      config.embedding = {
+        provider: preset.id,
+        baseUrl: baseUrl || preset.defaultBaseUrl,
+        model: model || preset.defaultModel,
+        apiKeyEnv: apiKeyEnv || preset.apiKeyEnv
+      };
+      if (key) apiKey = key;
+    });
+  }
+  const saved = saveProjectConfig(config, {
+    cwd,
+    overwrite: true,
+    apiKey,
+    envPath: DEFAULT_ENV_PATH
+  });
+  console.log("\nWolbarg configured.\n");
+  console.log(`  config: ${saved.configPath}`);
+  if (saved.envPath) console.log(`  env:    ${saved.envPath}`);
+  console.log(`  db:     ${config.database.provider} \u2192 ${config.database.url}`);
+  if (config.embedding) {
+    console.log(`  embed:  ${config.embedding.provider}`);
+    console.log(`  base:   ${config.embedding.baseUrl}`);
+    console.log(`  model:  ${config.embedding.model}`);
+    console.log(`  key:    $${config.embedding.apiKeyEnv}`);
+  } else {
+    console.log("  embed:  (not configured)");
+  }
+  console.log(`
+Next:
+  import { createWolbargFromProjectConfig } from "wolbarg";
+  const ctx = createWolbargFromProjectConfig();
+  await ctx.ready();
+`);
+  return 0;
+}
+async function initCommand(argv) {
+  try {
+    const parsed = parseInitArgs(argv);
+    if ("help" in parsed) {
+      printHelp();
+      return 0;
+    }
+    return await runInit(parsed);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : err);
+    return 1;
+  }
+}
+
+// src/cli/index.ts
+function printRootHelp() {
+  console.log(`wolbarg ${SDK_VERSION}
+
+Usage:
+  wolbarg init [options]    Configure project database + embedding provider
+  wolbarg --version         Print version
+  wolbarg --help            Show help
+
+Run \`wolbarg init --help\` for init options.
+`);
+}
+async function cliMain(argv) {
+  const [cmd, ...rest] = argv;
+  if (!cmd || cmd === "-h" || cmd === "--help") {
+    printRootHelp();
+    return 0;
+  }
+  if (cmd === "-V" || cmd === "--version" || cmd === "version") {
+    console.log(SDK_VERSION);
+    return 0;
+  }
+  if (cmd === "init") {
+    return initCommand(rest);
+  }
+  console.error(`Unknown command: ${cmd}`);
+  printRootHelp();
+  return 1;
+}
+cliMain(process.argv.slice(2)).then((code) => {
+  process.exit(code);
+}).catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
+
+export { cliMain };
+//# sourceMappingURL=cli.js.map
+//# sourceMappingURL=cli.js.map