Install Wolbarg, optional peers, and a clean project layout that keeps providers swappable without refactoring agent code.

What is it?

The install guide for the wolbarg npm package, optional peer dependencies, and a recommended project layout so storage and embedding factories live in one place — swap backends without rewriting your agents.

Requirements

Node.js 22.5+ (uses built-in node:sqlite)
An OpenAI-compatible embedding endpoint (required for remember/recall)
An LLM endpoint only if you use compress()

Install

npm install wolbarg

pnpm add wolbarg
yarn add wolbarg
bun add wolbarg

Current release: 0.6.0 — What's New.

Looking for coding-agent project memory instead of the SDK API? Install Wolbarg Workspace (@wolbarg/workspace).

Optional peers

Install only what you need:

npm install pg              # PostgreSQL storage
npm install pdf-parse@1.1.4 # PDF ingest (text-layer PDFs)
npm install mammoth         # DOCX ingest
npm install tesseract.js    # OCR on images

Peers are not bundled

If you call ingest() on PDF or DOCX files, or use PostgreSQL storage, you must install the matching peer in the same app:

pdf-parse for .pdf
mammoth for .docx
tesseract.js and/or a vision provider for images / scan-only PDFs
pg for PostgreSQL storage

Plain text formats (.txt, .md, .csv, .json) need no extra packages. Missing peers throw when that path is used — not at import time.

Prefer pinning pdf-parse@1.1.4 for the function API Wolbarg tests against.

Project layout

Keep provider wiring out of agent / business code. When you switch SQLite → Postgres, you change files under providers/ only — not every remember / recall call site.

src/
  providers/
    storage.ts      # sqlite() | postgres()
    embedding.ts    # openaiEmbedding() | ollamaEmbedding() | …
    llm.ts          # optional — openaiLlm() | …
    telemetry.ts    # optional — sqlite telemetry config
    index.ts        # re-exports + env-based selection
  memory/
    client.ts       # wolbarg({ …providers }) — single construction site
  agents/
    support.ts      # uses client — never imports sqlite/postgres directly
    research.ts
  index.ts

Example: `providers/storage.ts`

import { sqlite, postgres } from "wolbarg";

export function createStorage() {
  if (process.env.MEMORY_BACKEND === "postgres") {
    return postgres({
      connectionString: process.env.DATABASE_URL!,
      schema: process.env.WOLBARG_SCHEMA ?? "wolbarg",
    });
  }
  return sqlite(process.env.MEMORY_PATH ?? "./data/memory.db");
}

Example: `memory/client.ts`

import { wolbarg, bm25 } from "wolbarg";
import { createStorage } from "../providers/storage.js";
import { createEmbedding } from "../providers/embedding.js";

export const memory = wolbarg({
  organization: process.env.WOLBARG_ORG ?? "my-org",
  storage: createStorage(),
  embedding: createEmbedding(),
  keywordSearch: bm25(), // required when using hybrid: true
});

Agents import memory and call remember / recall — they never branch on database type. Full option table: Configuration.

Verify

import { wolbarg, sqlite, openaiEmbedding } from "wolbarg";

const ctx = wolbarg({
  organization: "demo",
  storage: sqlite(":memory:"),
  embedding: openaiEmbedding({
    apiKey: process.env.OPENAI_API_KEY!,
    model: "text-embedding-3-small",
  }),
});

await ctx.ready();
console.log(ctx.isInitialized); // true
await ctx.close();

Installation