### Run streaming and tools examples

Source: https://wolbarg.com/docs/examples/vercel-ai-memory

Run the streaming and tools examples from the examples/adapters/vercel-ai directory. start:stream uses streamText, start:tools demonstrates multi-step tools with final-step remember.

```bash
cd examples/adapters/vercel-ai
npm run start:stream   # streamText
npm run start:tools    # multi-step tools, final-step remember
```

--------------------------------

### Reproduce benchmark environment

Source: https://wolbarg.com/docs/benchmarks

Setup steps to install dependencies, configure environment variables (DATABASE_URL for Postgres, API keys for live mode), and run the three 0.4 benchmark scripts. Record date, SDK version, Node version, CPU/RAM, mode, backends, and git SHA.

```bash
cd benchmark
npm install
cp .env.example .env   # DATABASE_URL for postgres; API keys for --live
npx tsx v4-stress.ts
npx tsx embedding-cache-bench.ts
npx tsx multiprocess-levels.ts
```

--------------------------------

### Full configuration example

Source: https://wolbarg.com/docs/configuration

A complete example demonstrating the initialization of the Wolbarg context with various components and settings.

```ts
import {
  wolbarg, sqlite, openaiEmbedding, openaiLlm,
  bm25, jinaReranker, tesseract, geminiVision,
} from "wolbarg";

const ctx = wolbarg({
  organization: "my-org",
  storage: sqlite("./memory.db"),
  embedding: openaiEmbedding({
    apiKey: process.env.OPENAI_API_KEY!,
    model: "text-embedding-3-small",
  }),
  llm: openaiLlm({
    apiKey: process.env.OPENAI_API_KEY!,
    model: "gpt-4.1-mini",
  }),
  keywordSearch: bm25(),
  reranker: jinaReranker({ apiKey: process.env.JINA_API_KEY! }),
  ocr: tesseract(),
  vision: geminiVision({ apiKey: process.env.GEMINI_API_KEY! }),
  retrieval: {
    overFetchFactor: 4,
    hybrid: { semanticWeight: 0.7, keywordWeight: 0.3 },
  },
  concurrency: { maxRetries: 5, lockTimeoutMs: 5000 },
  embeddingCache: { enabled: true, maxEntries: 10_000 },
  memory: {
    dedupe: { enabled: true, strategy: "exact-or-near" },
  },
});
```

--------------------------------

### Install dependencies

Source: https://wolbarg.com/docs/integrations/langchain

Install the required packages for Wolbarg and LangChain integration.

```bash
npm install wolbarg @wolbarg/langchain @langchain/core @langchain/langgraph
```

--------------------------------

### Clone and run Wolbarg Studio

Source: https://wolbarg.com/docs/observability

Commands to clone the Wolbarg Studio repository, install dependencies, and start the development server on http://localhost:3100. Studio is a standalone Next.js dashboard, not bundled with the SDK.

```bash
git clone https://github.com/Atharvmunde11/wolbarg-studio
cd wolbarg-studio
npm install
npm run dev   # http://localhost:3100
```

--------------------------------

### Install @wolbarg/mastra

Source: https://wolbarg.com/docs/integrations/mastra

Install the required packages using npm.

```bash
npm install wolbarg @wolbarg/mastra @mastra/core
```

--------------------------------

### Install wolbarg via alternative package managers

Source: https://wolbarg.com/docs/installation

Installation commands for pnpm, yarn, and bun.

```bash
pnpm add wolbarg
yarn add wolbarg
bun add wolbarg
```

--------------------------------

### Install @wolbarg/llamaindex

Source: https://wolbarg.com/docs/integrations/llamaindex

Install the necessary packages to use Wolbarg with LlamaIndex.

```bash
npm install wolbarg @wolbarg/llamaindex llamaindex
```

--------------------------------

### Install wolbarg via npm

Source: https://wolbarg.com/docs/installation

Standard installation command for the wolbarg package.

```bash
npm install wolbarg
```

--------------------------------

### Initialize WolbargStore

Source: https://wolbarg.com/docs/integrations/langchain

Demonstrates how to create a Wolbarg store and perform basic operations like put, get, and search.

```ts
import { createWolbargStore } from "@wolbarg/langchain";

const store = createWolbargStore({
  memory,
  agent: "assistant",
});

await store.put(["users", "u1"], "prefs", { text: "dark mode" });
const item = await store.get(["users", "u1"], "prefs");
const hits = await store.search(["users"], {
  query: "theme preference",
  limit: 5,
});
```

--------------------------------

### Install @wolbarg/openai dependencies

Source: https://wolbarg.com/docs/integrations/openai

Install the required packages for the Wolbarg OpenAI integration.

```bash
npm install wolbarg @wolbarg/openai @openai/agents
```

--------------------------------

### Verify installation

Source: https://wolbarg.com/docs/installation

A script to verify that the wolbarg client initializes correctly using an in-memory SQLite database.

```ts
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();
```

--------------------------------

### Install optional peer dependencies

Source: https://wolbarg.com/docs/installation

Commands to install specific dependencies for PostgreSQL storage, PDF/DOCX ingestion, and OCR capabilities.

```bash
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
```

--------------------------------

### Example: memory/client.ts

Source: https://wolbarg.com/docs/installation

Centralized client construction using the provider factories.

```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
});
```

--------------------------------

### Install and initialize Wolbarg Workspace

Source: https://wolbarg.com/docs/workspace

Run inside your project folder (not global). The init wizard asks for storage and embedding provider; press Enter to keep defaults (SQLite + Ollama, fully local).

```bash
npm install @wolbarg/workspace
npx @wolbarg/workspace init
```

--------------------------------

### Install Wolbarg SDK

Source: https://wolbarg.com

Install the Wolbarg package via npm to begin integrating persistent memory into your agent workflows.

```bash
$ npm install wolbarg
```

--------------------------------

### Example: providers/storage.ts

Source: https://wolbarg.com/docs/installation

A provider factory that switches between SQLite and PostgreSQL based on environment variables.

```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");
}
```

--------------------------------

### Install pg dependency

Source: https://wolbarg.com/docs/examples/postgresql

Install the required pg peer dependency for PostgreSQL storage.

```bash
npm install pg
```

--------------------------------

### Install peer dependencies for PDF and DOCX

Source: https://wolbarg.com/docs/document-ingestion

Install pdf-parse@1.1.4 for .pdf files and mammoth for .docx files. These peers are not bundled with Wolbarg; missing peers throw when that format is used.

```bash
npm install pdf-parse@1.1.4   # required for .pdf
```

```bash
npm install mammoth           # required for .docx
```

--------------------------------

### Quick start with wolbargBlock

Source: https://wolbarg.com/docs/integrations/llamaindex

Initialize a Wolbarg client and configure a LlamaIndex memory instance using the wolbargBlock.

```ts
import { createMemory } from "llamaindex";
import { wolbarg, sqlite, openaiEmbedding } from "wolbarg";
import { wolbargBlock } from "@wolbarg/llamaindex";

const client = wolbarg({
  organization: "my-app",
  storage: sqlite("./memory.db"),
  embedding: openaiEmbedding({
    apiKey: process.env.OPENAI_API_KEY!,
    model: "text-embedding-3-small",
  }),
});
await client.ready();

const memory = createMemory({
  memoryBlocks: [
    wolbargBlock({
      memory: client,
      agent: "assistant",
      sessionId: "demo-session",
    }),
  ],
});

await memory.add({ role: "user", content: "I prefer dark mode." });
await memory.manageMemoryBlocks();

const messages = await memory.getLLM();
```

--------------------------------

### subscribe() Usage Example

Source: https://wolbarg.com/docs/api/subscribe

Demonstrates how to subscribe to memory events, perform an action, and then stop the subscription.

```ts
const stop = ctx.subscribe(
  { organization: "my-org", event: ["remember", "update"] },
  (e) => console.log(e.event, e.memoryId),
);

await ctx.remember({
  agent: "assistant",
  content: { text: "Ships prefer express checkout" },
});

stop();
await ctx.close(); // also clears remaining subscriptions
```

--------------------------------

### update() example

Source: https://wolbarg.com/docs/api/update

Example usage of update() to change memory content and metadata. Logs the action, which will be 'updated'.

```typescript
const result = await ctx.update({
  id: memoryId,
  content: { text: "User prefers dark mode (confirmed)" },
  metadata: { editedBy: "admin", editedAt: new Date().toISOString() },
});

console.log(result.action); // "updated"
```

--------------------------------

### Quick start with generateText

Source: https://wolbarg.com/docs/integrations/vercel-ai

Sets up Wolbarg memory with SQLite storage and OpenAI embeddings, wraps the model with wolbargMiddleware, and calls generateText. The system message is preserved.

```ts
import { generateText, wrapLanguageModel } from "ai";
import { openai } from "@ai-sdk/openai";
import { wolbarg, sqlite, openaiEmbedding } from "wolbarg";
import { wolbargMiddleware } from "@wolbarg/vercel-ai";

const memory = wolbarg({
  organization: "my-app",
  storage: sqlite("./memory.db"),
  embedding: openaiEmbedding({
    apiKey: process.env.OPENAI_API_KEY!,
    model: "text-embedding-3-small",
  }),
});
await memory.ready();

const model = wrapLanguageModel({
  model: openai("gpt-4.1-mini"),
  middleware: wolbargMiddleware({
    memory,
    agent: "assistant",
  }),
});

const { text } = await generateText({
  model,
  system: "You are a concise assistant.", // preserved
  messages: [{ role: "user", content: "What do I prefer?" }],
});
```

--------------------------------

### Install Tesseract.js dependency

Source: https://wolbarg.com/docs/examples/image-memory

Install the required Tesseract.js package for OCR functionality.

```bash
npm install tesseract.js
```

--------------------------------

### Install optional ingest dependencies

Source: https://wolbarg.com/docs/guides/limitations

Install required packages for PDF, DOCX, OCR, and PostgreSQL storage. PDF extraction requires pdf-parse@1.1.4; DOCX requires mammoth; OCR requires tesseract.js; PostgreSQL storage requires pg.

```bash
npm install pdf-parse@1.1.4   # PDF
npm install mammoth           # DOCX
npm install tesseract.js      # OCR
npm install pg                # PostgreSQL storage
```

--------------------------------

### Install Wolbarg 0.6.0

Source: https://wolbarg.com/docs/guides/whats-new

Use npm to install the 0.6.0 version of the Wolbarg package.

```bash
npm install wolbarg@0.6.0
```

--------------------------------

### Wolbarg Configuration Options

Source: https://wolbarg.com/docs/api/wolbarg

Example of initializing a Wolbarg instance with organization, storage, embedding, keyword search, concurrency, cache, and memory deduplication settings.

```ts
import { wolbarg, sqlite, openaiEmbedding, bm25 } from "wolbarg";

const ctx = wolbarg({
  organization: "my-org",
  storage: sqlite("./memory.db"),
  embedding: openaiEmbedding({ /* … */ }),
  keywordSearch: bm25(), // required when using hybrid: true
  concurrency: {
    maxRetries: 5,
    baseBackoffMs: 50,
    maxBackoffMs: 2000,
    lockTimeoutMs: 5000,
  },
  embeddingCache: {
    enabled: true,
    ttlMs: undefined,
    maxEntries: 10_000,
  },
  memory: {
    dedupe: {
      enabled: false, // default — opt in for upsert
      strategy: "exact-or-near",
      nearThreshold: 0.92,
      nearCandidateLimit: 8,
    },
  },
});
```

--------------------------------

### Configure Embedding Providers

Source: https://wolbarg.com/docs/providers

Examples of importing and initializing various embedding providers using the Wolbarg SDK.

```ts
import {
  openaiEmbedding,
  ollamaEmbedding,
  openRouterEmbedding,
  lmStudioEmbedding,
  geminiEmbedding,
  togetherEmbedding,
  vllmEmbedding,
  openaiCompatibleEmbedding,
} from "wolbarg";

embedding: openaiEmbedding({
  apiKey: process.env.OPENAI_API_KEY!,
  model: "text-embedding-3-small",
})

embedding: ollamaEmbedding({
  apiKey: "ollama",
  model: "nomic-embed-text",
})
```

--------------------------------

### Install dependencies for Vercel AI memory

Source: https://wolbarg.com/docs/examples/vercel-ai-memory

Install the required packages for using the Vercel AI middleware with Wolbarg. Requires AI SDK v7+.

```bash
npm install wolbarg @wolbarg/vercel-ai ai @ai-sdk/openai
```

--------------------------------

### Ingest documents

Source: https://wolbarg.com/docs/quick-start

Install necessary dependencies and ingest files like Markdown, TXT, PDF, or DOCX.

```bash
npm install pdf-parse@1.1.4   # required for .pdf ingest
npm install mammoth           # required for .docx ingest
```

```ts
const result = await ctx.ingest({
  agent: "docs",
  source: { path: "./guide.md" },
  chunking: { strategy: "markdown", chunkSize: 800, overlap: 100 },
});
console.log(result.chunkCount);
```

--------------------------------

### Basic memory storage with remember()

Source: https://wolbarg.com/docs/api/remember

An example of storing a memory with an agent, content, and metadata.

```ts
const result = await ctx.remember({
  agent: "research",
  content: { text: "Acme raised Series B at $50M." },
  metadata: { company: "Acme", year: 2024 },
});

console.log(result.id, result.action);
```

--------------------------------

### Install Wolbarg 0.4.0

Source: https://wolbarg.com/docs/migration

Install the 0.4.0 version of Wolbarg using npm. This version is additive and requires no code changes.

```bash
npm install wolbarg@^0.4.0
```

--------------------------------

### Configure OCR with tesseract provider

Source: https://wolbarg.com/docs/ocr

Import the tesseract provider from wolbarg and set it as the OCR option. Requires tesseract.js to be installed.

```ts
import { tesseract } from "wolbarg";

ocr: tesseract()
```

--------------------------------

### Run storage backend benchmarks

Source: https://wolbarg.com/docs/benchmarks

Commands to start PostgreSQL and run the 0.4 stress, embedding cache, and multiprocess benchmarks. Assumes pgvector/HNSW for Postgres and sqlite-vec for SQLite; missing extensions fall back to exact cosine scanning.

```bash
cd benchmark
npm run postgres:up
npx tsx v4-stress.ts          # or your package script wrapping it
npx tsx embedding-cache-bench.ts
npx tsx multiprocess-levels.ts
```

--------------------------------

### Install pdf-parse dependency

Source: https://wolbarg.com/docs/examples/pdf-memory

Install the required pdf-parse package version 1.1.4 to enable PDF text extraction.

```bash
npm install pdf-parse@1.1.4
```

--------------------------------

### Example — raw (no LLM)

Source: https://wolbarg.com/docs/api/remember-from-messages

Demonstrates storing user messages in raw mode without requiring an LLM. The default rawStrategy is last_user.

```ts
const saved = await ctx.rememberFromMessages(
  [
    { role: "user", content: "I prefer dark mode" },
    { role: "assistant", content: "Noted." },
    { role: "user", content: "Deploy only on Fridays" },
  ],
  { agent: "assistant" },
);

// Default rawStrategy is last_user → one memory:
console.log(saved[0]?.content.text); // "Deploy only on Fridays"
```

--------------------------------

### Install Wolbarg 0.5.0

Source: https://wolbarg.com/docs/migration

Install the 0.5.0 version of Wolbarg using npm. This version introduced optional graph memory, which was removed in 0.6.0.

```bash
npm install wolbarg@^0.5.0
```

--------------------------------

### recall() usage example with hybrid, MMR, rerank, and filters

Source: https://wolbarg.com/docs/api/recall

Example of calling recall() with hybrid weights, MMR lambda, rerank enabled, and a filter using meta.and and meta.eq/meta.gte. Uses AbortSignal.timeout for cancellation.

```typescript
import { meta } from "wolbarg";

const hits = await ctx.recall({
  query: "billing invoices",
  topK: 8,
  threshold: 0.25,
  hybrid: { semanticWeight: 0.7, keywordWeight: 0.3 },
  mmr: { lambda: 0.6 },
  rerank: true,
  filter: {
    agent: "research",
    metadata: meta.and(
      meta.eq("topic", "billing"),
      meta.gte("priority", 1),
    ),
  },
  signal: AbortSignal.timeout(10_000),
});
```

--------------------------------

### Quick start with createWolbargProcessor

Source: https://wolbarg.com/docs/integrations/mastra

Initialize the Wolbarg memory instance and register the processor in both inputProcessors and outputProcessors of a Mastra Agent.

```ts
import { Agent } from "@mastra/core/agent";
import { wolbarg, sqlite, openaiEmbedding } from "wolbarg";
import { createWolbargProcessor } from "@wolbarg/mastra";

const memory = wolbarg({
  organization: "my-app",
  storage: sqlite("./memory.db"),
  embedding: openaiEmbedding({
    apiKey: process.env.OPENAI_API_KEY!,
    model: "text-embedding-3-small",
  }),
});
await memory.ready();

// One instance for both input + output hooks
const wolbargMem = createWolbargProcessor({
  memory,
  agent: "assistant",
  sessionId: "optional-session",
});

const agent = new Agent({
  id: "assistant",
  name: "Assistant",
  instructions: "You are a helpful assistant.",
  model: "openai/gpt-4.1-mini",
  inputProcessors: [wolbargMem],
  outputProcessors: [wolbargMem],
});

const result = await agent.generate("What UI theme do I prefer?");
console.log(result.text);
```

--------------------------------

### ingest() example with markdown chunking

Source: https://wolbarg.com/docs/api/ingest

Example call to ingest() that parses a markdown file from a path, using markdown chunking with chunkSize 800 and overlap 100. Requires the agent to be set to "docs".

```typescript
await ctx.ingest({
  agent: "docs",
  source: { path: "./guide.md" },
  chunking: { strategy: "markdown", chunkSize: 800, overlap: 100 },
});
```

--------------------------------

### Example — extract (optional LLM)

Source: https://wolbarg.com/docs/api/remember-from-messages

Demonstrates using extract mode to pull facts from messages, which requires an LLM configuration. Throws ProviderNotConfiguredError if no LLM is provided.

```ts
import { wolbarg, sqlite, openaiEmbedding, openaiLlm } from "wolbarg";

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

const facts = await ctx.rememberFromMessages(
  [
    { role: "user", content: "I live in Berlin and prefer tea over coffee." },
    { role: "assistant", content: "Got it." },
  ],
  { agent: "assistant", mode: "extract" },
);
```

--------------------------------

### Basic memory example with Wolbarg, SQLite, and OpenAI embeddings

Source: https://wolbarg.com/docs/examples/basic-memory

Creates a Wolbarg context with SQLite storage and OpenAI embeddings, remembers a fact, recalls it with a query, and closes the context. Requires an OPENAI_API_KEY environment variable.

```TypeScript
import { Wolbarg, sqlite, openaiEmbedding } from "wolbarg";

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

await ctx.remember({
  agent: "assistant",
  content: { text: "The deploy window is Fridays at 16:00 UTC." },
});

const hits = await ctx.recall({ query: "when can we deploy?", topK: 3 });
console.log(hits[0]?.content.text);

await ctx.close();
```

--------------------------------

### forget() usage examples

Source: https://wolbarg.com/docs/api/forget

Two usage examples: one deletes a memory by id, the other uses a metadata/agent filter with an AbortSignal timeout. The optional signal cancels with CancellationError.

```typescript
await ctx.forget({ id: record.id });
```

```typescript
await ctx.forget({
  filter: { agent: "research" },
  signal: AbortSignal.timeout(5_000),
});
```

--------------------------------

### Upgrade Wolbarg 0.5 to 0.6

Source: https://wolbarg.com/docs/migration

Commands to install the 0.6.0 version and remove the neo4j-driver dependency if it was only used for the Wolbarg graph.

```bash
npm install wolbarg@0.6.0
# remove if you only used it for Wolbarg graph
npm uninstall neo4j-driver
```

--------------------------------

### Configure Wolbarg with LLM and call compress()

Source: https://wolbarg.com/docs/compression

Requires the 'llm' option on the constructor. Without it, TypeScript rejects compress and runtime throws ProviderNotConfiguredError. The example uses openaiLlm with gpt-4.1-mini and sqlite storage.

```TypeScript
import { Wolbarg, sqlite, openaiEmbedding, openaiLlm } from "wolbarg";

const ctx = new Wolbarg({
  organization: "my-org",
  storage: sqlite("./memory.db"),
  embedding: openaiEmbedding({ /* … */ }),
  llm: openaiLlm({
    apiKey: process.env.OPENAI_API_KEY!,
    model: "gpt-4.1-mini",
  }),
});

const result = await ctx.compress({
  agent: "research",
  // filter / ids / strategy options per CompressOptions
});
```

--------------------------------

### Check Workspace health and status

Source: https://wolbarg.com/docs/workspace

Runs doctor, status, and review commands to verify the installation and project state.

```bash
npx @wolbarg/workspace doctor
npx @wolbarg/workspace status
npx @wolbarg/workspace review
```

--------------------------------

### Migrate dependencies from AgentOrc to Wolbarg

Source: https://wolbarg.com/docs/migration

Use these commands to remove the deprecated agentorc package and install the new wolbarg package.

```bash
npm uninstall agentorc
npm install wolbarg
```

--------------------------------

### Enable MMR diversification in recall

Source: https://wolbarg.com/docs/rerankers

Shows how to enable MMR with default lambda 0.5, or customize lambda to 0.7 for more relevance and less diversity. Use MMR when agents repeatedly get near-duplicate snippets.

```ts
await ctx.recall({
  query: "…",
  topK: 5,
  mmr: true,              // lambda = 0.5
  // mmr: { lambda: 0.7 } // higher = more relevance, less diversity
});
```

--------------------------------

### recall() with metadata filter

Source: https://wolbarg.com/docs/metadata-filtering

Apply a metadata filter during recall() to scope retrieval. This example combines an equality and a greater-than-or-equal filter with meta.and(), and also sets the agent scope to "sales".

```ts
await ctx.recall({
  query: "pricing",
  filter: {
    agent: "sales",
    metadata: meta.and(
      meta.eq("region", "eu"),
      meta.gte("priority", 2),
    ),
  },
});
```

--------------------------------

### Initialize a new Wolbarg project

Source: https://wolbarg.com/docs/quick-start

Use the CLI to initialize a project or import the configuration factory in your code.

```bash
npx wolbarg init
```

```ts
import { createWolbargFromProjectConfig } from "wolbarg";

const ctx = createWolbargFromProjectConfig();
await ctx.ready();
```

--------------------------------

### Recall explain mode usage

Source: https://wolbarg.com/docs/observability

Use ctx.recall with explain: true to get ranking reasons for each hit. The results include memory.id, score, and rankingReason, and the response provides searchTime, rankingTime, and traceId.

```TypeScript
const explained = await ctx.recall({ query: "recurring invoices", explain: true });

for (const hit of explained.results) {
  console.log(hit.memory.id, hit.score, hit.rankingReason);
}
console.log(explained.searchTime, explained.rankingTime, explained.traceId);
```

--------------------------------

### ready()

Source: https://wolbarg.com/docs/api/wolbarg

Opens storage (and telemetry when configured) and probes embedding dimensions. Called automatically by other methods; use explicitly to fail fast at startup.

```APIDOC
## ready()

### Description
Opens storage (and telemetry when configured) and probes embedding dimensions. Called automatically by other methods; use explicitly to fail fast at startup.

### Method
ready

### Signature
```ts
await ctx.ready();
```

### Parameters
None

### Returns
Promise that resolves when ready.

### Example
```ts
await ctx.ready();
```
```

--------------------------------

### Skip the init wizard with --yes

Source: https://wolbarg.com/docs/workspace

Runs initialization without interactive prompts, using default settings.

```bash
npx @wolbarg/workspace init --yes
```

--------------------------------

### Wolbarg ready() Method

Source: https://wolbarg.com/docs/api/wolbarg

Explicitly opens storage and probes embedding dimensions. Use this to fail fast at startup.

```ts
await ctx.ready();
```

--------------------------------

### init() shim

Source: https://wolbarg.com/docs/api/wolbarg

Compatibility shim for v0.1. Prefer constructor / wolbarg() options. Initializes the instance with provided options.

```APIDOC
## init() shim

### Description
Compatibility shim for v0.1. Prefer constructor / wolbarg() options. Initializes the instance with provided options.

### Method
init

### Signature
```ts
const ctx = new Wolbarg();
await ctx.init({
  organization: "my-org",
  database: { provider: "sqlite", connectionString: "./memory.db" },
  embedding: { baseUrl, apiKey, model },
  llm: { baseUrl, apiKey, model }, // optional
});
```

### Parameters
#### Options
- **organization** (string) - Required - Organization identifier.
- **database** (object) - Required - Database configuration.
  - **provider** (string) - Required - Database provider, e.g., "sqlite".
  - **connectionString** (string) - Required - Connection string.
- **embedding** (object) - Required - Embedding configuration.
  - **baseUrl** (string) - Required - Base URL.
  - **apiKey** (string) - Required - API key.
  - **model** (string) - Required - Model name.
- **llm** (object) - Optional - LLM configuration.
  - **baseUrl** (string) - Required - Base URL.
  - **apiKey** (string) - Required - API key.
  - **model** (string) - Required - Model name.

### Example
```ts
const ctx = new Wolbarg();
await ctx.init({
  organization: "my-org",
  database: { provider: "sqlite", connectionString: "./memory.db" },
  embedding: { baseUrl, apiKey, model },
  llm: { baseUrl, apiKey, model }, // optional
});``` n
### Notes
- Prefer constructor / wolbarg() options.
- See init() Compatibility for more details.
```

--------------------------------

### Compress memories with compress()

Source: https://wolbarg.com/docs/examples/compression

Initializes a Wolbarg context with SQLite storage, OpenAI embedding (text-embedding-3-small), and OpenAI LLM (gpt-4.1-mini), then calls compress() to summarize memories for the 'research' agent. Requires OPENAI_API_KEY environment variable.

```ts
import { Wolbarg, sqlite, openaiEmbedding, openaiLlm } from "wolbarg";

const ctx = new Wolbarg({
  organization: "demo",
  storage: sqlite("./memory.db"),
  embedding: openaiEmbedding({
    apiKey: process.env.OPENAI_API_KEY!,
    model: "text-embedding-3-small",
  }),
  llm: openaiLlm({
    apiKey: process.env.OPENAI_API_KEY!,
    model: "gpt-4.1-mini",
  }),
});

await ctx.compress({ agent: "research" });
```

--------------------------------

### Initialize and connect Wolbarg Workspace

Source: https://wolbarg.com/docs/connectors

Commands to initialize the Wolbarg Workspace and connect it to the Cursor editor.

```bash
npx @wolbarg/workspace init
npx @wolbarg/workspace connect cursor
```

--------------------------------

### Initialize WolbargSession

Source: https://wolbarg.com/docs/integrations/openai

Constructs a new WolbargSession instance with memory, agent configuration, and optional session parameters. The ready() method must be awaited to ensure soft-fail hydration.

```ts
import { WolbargSession } from "@wolbarg/openai";

const session = new WolbargSession({
  memory,
  agent: "assistant",
  sessionId: "chat-1", // omit to auto-generate (no hydrate)
  semanticRemember: true, // default
  userId: "u1",
  tags: ["support"],
  onError: (err, phase) => console.warn(phase, err),
});
await session.ready(); // await soft-fail hydration
```

--------------------------------

### Wolbarg init() Compatibility Shim

Source: https://wolbarg.com/docs/api/wolbarg

Legacy initialization method for v0.1 compatibility. Prefer using the constructor or factory options instead.

```ts
const ctx = new Wolbarg();
await ctx.init({
  organization: "my-org",
  database: { provider: "sqlite", connectionString: "./memory.db" },
  embedding: { baseUrl, apiKey, model },
  llm: { baseUrl, apiKey, model }, // optional
});
```

--------------------------------

### new Wolbarg(options) / wolbarg(options)

Source: https://wolbarg.com/docs/api/wolbarg

Creates a Wolbarg instance. The factory function wolbarg() is recommended. When llm is present, the instance type allows compress; otherwise calling compress is a compile-time error.

```APIDOC
## new Wolbarg(options) / wolbarg(options)

### Description
Creates a Wolbarg instance. The factory function wolbarg() is recommended. When llm is present, the instance type allows compress; otherwise calling compress is a compile-time error.

### Method
Constructor / Factory

### Signature
```ts
new Wolbarg(options)  // preferred
wolbarg(options)      // factory (recommended in docs)
new Wolbarg()         // then init() for v0.1 compat
```

### Parameters
#### Options
- **organization** (string) - Required - Organization identifier.
- **storage** (object) - Required - Storage configuration, e.g., sqlite("./memory.db").
- **embedding** (object) - Required - Embedding configuration, e.g., openaiEmbedding({ ... }).
- **keywordSearch** (object) - Optional - Required when using hybrid: true, e.g., bm25().
- **concurrency** (object) - Optional - Concurrency settings.
  - **maxRetries** (number) - Optional - Maximum retries.
  - **baseBackoffMs** (number) - Optional - Base backoff in milliseconds.
  - **maxBackoffMs** (number) - Optional - Maximum backoff in milliseconds.
  - **lockTimeoutMs** (number) - Optional - Lock timeout in milliseconds.
- **embeddingCache** (object) - Optional - Embedding cache settings.
  - **enabled** (boolean) - Optional - Enable cache.
  - **ttlMs** (number) - Optional - Time-to-live in milliseconds.
  - **maxEntries** (number) - Optional - Maximum cache entries.
- **memory** (object) - Optional - Memory settings.
  - **dedupe** (object) - Optional - Deduplication settings.
    - **enabled** (boolean) - Optional - Enable dedupe (default false).
    - **strategy** (string) - Optional - Dedupe strategy, e.g., "exact-or-near".
    - **nearThreshold** (number) - Optional - Threshold for near matches.
    - **nearCandidateLimit** (number) - Optional - Candidate limit for near matches.

### Example
```ts
import { wolbarg, sqlite, openaiEmbedding, bm25 } from "wolbarg";

const ctx = wolbarg({
  organization: "my-org",
  storage: sqlite("./memory.db"),
  embedding: openaiEmbedding({ /* … */ }),
  keywordSearch: bm25(), // required when using hybrid: true
  concurrency: {
    maxRetries: 5,
    baseBackoffMs: 50,
    maxBackoffMs: 2000,
    lockTimeoutMs: 5000,
  },
  embeddingCache: {
    enabled: true,
    ttlMs: undefined,
    maxEntries: 10_000,
  },
  memory: {
    dedupe: {
      enabled: false, // default — opt in for upsert
      strategy: "exact-or-near",
      nearThreshold: 0.92,
      nearCandidateLimit: 8,
    },
  },
});
```

### Notes
- See Configuration for the full option table (including Postgres schema / SSL / maxPoolSize).
- Isolate factories with Project layout.
```

--------------------------------

### Recommended project layout

Source: https://wolbarg.com/docs/installation

A directory structure that isolates provider wiring from agent business logic.

```text
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
```

--------------------------------

### Initialize Wolbarg with init()

Source: https://wolbarg.com/docs/reference/init-compat

Configures the Wolbarg instance using the init() method, including database, embedding, and optional LLM settings.

```ts
const ctx = new Wolbarg();
await ctx.init({
  organization: "my-org",
  database: {
    provider: "sqlite", // or "postgres"
    connectionString: "./memory.db",
  },
  embedding: {
    baseUrl: "https://api.openai.com/v1",
    apiKey: process.env.OPENAI_API_KEY!,
    model: "text-embedding-3-small",
  },
  llm: { // optional in 0.2
    baseUrl: "https://api.openai.com/v1",
    apiKey: process.env.OPENAI_API_KEY!,
    model: "gpt-4.1-mini",
  },
});
```

--------------------------------

### SQLite configuration with provider object

Source: https://wolbarg.com/docs/guides/production

Alternative configuration using a provider object with 'sqlite' provider and URL pointing to the database file.

```ts
{ provider: "sqlite", url: "./data/memory.db" }
```

--------------------------------

### Per-call dedupe overrides for remember()

Source: https://wolbarg.com/docs/memory-upsert

Shows three per-call overrides: force on with default strategy, force exact-only, and force off even if constructor enabled. Each example uses a different content and agent.

```typescript
// Force on for one write
await ctx.remember({
  agent: "assistant",
  content: { text: "User prefers dark mode" },
  dedupe: true,
});

// Exact-only for one write
await ctx.remember({
  agent: "assistant",
  content: { text: "Timezone is IST" },
  dedupe: { strategy: "exact" },
});

// Force off even if constructor enabled
await ctx.remember({
  agent: "logger",
  content: { text: "Heartbeat at T+60s" },
  dedupe: false,
});
```

--------------------------------

### Initialize WolbargMemory

Source: https://wolbarg.com/docs/integrations/langchain

Configure Wolbarg memory with storage and embedding, then create a chat memory instance for LangChain.

```typescript
import { wolbarg, sqlite, openaiEmbedding } from "wolbarg";
import { createWolbargMemory } from "@wolbarg/langchain";

const memory = wolbarg({
  organization: "my-app",
  storage: sqlite("./memory.db"),
  embedding: openaiEmbedding({
    apiKey: process.env.OPENAI_API_KEY!,
    model: "text-embedding-3-small",
  }),
});
await memory.ready();

const chatMemory = createWolbargMemory({
  memory,
  agent: "assistant",
  memoryKey: "history",
  sessionId: "chat-1",
});

const vars = await chatMemory.loadMemoryVariables({
  input: "What UI theme do I prefer?",
});
// vars.history — formatted string (or BaseMessage[] when returnMessages: true)

await chatMemory.saveContext(
  { input: "I prefer dark mode" },
  { output: "Noted — dark mode it is." },
);
```

--------------------------------

### Configure Wolbarg with PostgreSQL

Source: https://wolbarg.com/docs/examples/postgresql

Initialize the Wolbarg context using PostgreSQL storage and OpenAI embeddings. Ensure DATABASE_URL and OPENAI_API_KEY environment variables are set.

```ts
import { Wolbarg, postgres, openaiEmbedding } from "wolbarg";

const ctx = new Wolbarg({
  organization: "prod",
  storage: postgres({
    connectionString: process.env.DATABASE_URL!,
    schema: "wolbarg",
    // maxPoolSize defaults to 20; remote TLS defaults to require
  }),
  embedding: openaiEmbedding({
    apiKey: process.env.OPENAI_API_KEY!,
    model: "text-embedding-3-small",
  }),
});

await ctx.ready();
```

--------------------------------

### Initialize Wolbarg Workspace

Source: https://wolbarg.com

Initialize the Wolbarg workspace in your repository to enable shared, reconciled project truth across different AI agents.

```bash
$ npx @wolbarg/workspace init
```

--------------------------------

### Worked example: preference convergence with dedupe

Source: https://wolbarg.com/docs/memory-upsert

Demonstrates dedupe behavior: two remember() calls with identical content but different metadata. The first creates a record, the second updates it, preserving the same id and merging metadata.

```typescript
const a = await ctx.remember({
  agent: "assistant",
  content: { text: "User prefers dark mode" },
  metadata: { source: "onboarding" },
  dedupe: true,
});
// a.action === "created"

const b = await ctx.remember({
  agent: "assistant",
  content: { text: "User prefers dark mode" },
  metadata: { source: "settings", confirmed: true },
  dedupe: true,
});
// b.action === "updated"
// b.id === a.id
// metadata merged: { source: "settings", confirmed: true }
```

--------------------------------

### Use metadata for relationships instead of graph memory

Source: https://wolbarg.com/docs/graph-memory

Replaces the removed graph memory APIs with metadata-based tagging and filtering. The example stores related IDs in metadata and filters recall results using meta.eq. Requires Wolbarg 0.6.0 or later.

```TypeScript
await ctx.remember({
  agent: "support",
  content: { text: "Refund SLA is 5 business days." },
  metadata: { topic: "billing", relatedTo: ["pref-email"] },
});

const hits = await ctx.recall({
  query: "refund timeline",
  filter: { metadata: meta.eq("topic", "billing") },
});
```

--------------------------------

### Configure Wolbarg and ingest image

Source: https://wolbarg.com/docs/examples/image-memory

Initialize the Wolbarg context with SQLite storage, OpenAI embeddings, Tesseract OCR, and Gemini vision, then ingest a local PNG file.

```ts
import { Wolbarg, sqlite, openaiEmbedding, tesseract, geminiVision } from "wolbarg";

const ctx = new Wolbarg({
  organization: "demo",
  storage: sqlite("./memory.db"),
  embedding: openaiEmbedding({
    apiKey: process.env.OPENAI_API_KEY!,
    model: "text-embedding-3-small",
  }),
  ocr: tesseract(),
  vision: geminiVision({ apiKey: process.env.GEMINI_API_KEY! }),
});

await ctx.ingest({
  agent: "vision",
  source: { path: "./screenshot.png" },
});
```

--------------------------------

### Configure SQLite storage

Source: https://wolbarg.com/docs/storage/sqlite

Initialize the SQLite backend with a file path or in-memory database. Use `sqlite("./memory.db")` for persistent storage or `sqlite(":memory:")` for a temporary in-memory database.

```typescript
import { sqlite } from "wolbarg";

storage: sqlite("./memory.db")
// or
storage: sqlite(":memory:")
```

--------------------------------

### Configure LLM Providers

Source: https://wolbarg.com/docs/providers

Initialize an LLM provider. Note that omitting the LLM configuration will cause a ProviderNotConfiguredError at runtime if compression is attempted.

```ts
import { openaiLlm, ollamaLlm, openRouterLlm } from "wolbarg";

llm: openaiLlm({
  apiKey: process.env.OPENAI_API_KEY!,
  model: "gpt-4.1-mini",
})
```

--------------------------------

### Retrieve system statistics with stats()

Source: https://wolbarg.com/docs/api/lifecycle

Use the stats() method to retrieve memory counts, models, and storage information. Note that llmModel may be null if no LLM is configured.

```ts
const s = await ctx.stats();
// memory counts, models, storage info
```

--------------------------------

### SQLite configuration with sqlite() function

Source: https://wolbarg.com/docs/guides/production

Configure Wolbarg to use SQLite with the sqlite() helper. This is the primary way to specify the database file path.

```ts
sqlite("./data/memory.db")
```

--------------------------------

### Initialize Wolbarg Tools

Source: https://wolbarg.com/docs/integrations/langchain

Creates Wolbarg tools for recall and memory functions within an agent.

```ts
import { createWolbargTools } from "@wolbarg/langchain";

const tools = createWolbargTools({ memory, agent: "assistant" });
// [wolbarg_recall, wolbarg_remember]
```

--------------------------------

### Initialize OpenAI Agent with Wolbarg Session

Source: https://wolbarg.com/docs/integrations/openai

Configure a Wolbarg memory instance and use it to create a session and input callback for an OpenAI Agent.

```ts
import { Agent, run } from "@openai/agents";
import { wolbarg, sqlite, openaiEmbedding } from "wolbarg";
import {
  createWolbargSession,
  createWolbargSessionInputCallback,
} from "@wolbarg/openai";

const memory = wolbarg({
  organization: "my-app",
  storage: sqlite("./memory.db"),
  embedding: openaiEmbedding({
    apiKey: process.env.OPENAI_API_KEY!,
    model: "text-embedding-3-small",
  }),
});
await memory.ready();

const session = await createWolbargSession({
  memory,
  agent: "assistant",
  sessionId: "chat-1",
});

const agent = new Agent({
  name: "Assistant",
  instructions: "Be concise.",
});

await run(agent, "What UI theme do I prefer?", {
  session,
  sessionInputCallback: createWolbargSessionInputCallback({
    memory,
    agent: "assistant",
  }),
});
```

--------------------------------

### Configure hybrid search with BM25 and recall with semantic/keyword weights

Source: https://wolbarg.com/docs/examples/hybrid-search

Sets up a Wolbarg context with SQLite storage, OpenAI embeddings, and BM25 keyword search. Stores a memory about an incident, then recalls it using a hybrid query with semanticWeight 0.6 and keywordWeight 0.4.

```TypeScript
import { Wolbarg, sqlite, openaiEmbedding, bm25 } from "wolbarg";

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

await ctx.remember({
  agent: "ops",
  content: { text: "Incident INC-2048: Redis failover completed." },
});

const hits = await ctx.recall({
  query: "INC-2048 failover",
  hybrid: { semanticWeight: 0.6, keywordWeight: 0.4 },
});
```

--------------------------------

### Update API initialization from 0.1 to 0.2

Source: https://wolbarg.com/docs/migration

The 0.2+ version introduces a factory-based configuration pattern using specific storage and model providers, though init() remains available for compatibility.

```ts
// 0.1
const ctx = new Wolbarg();
await ctx.init({ organization, database, embedding, llm });

// 0.2+ (recommended)
import { wolbarg, sqlite, openaiEmbedding, openaiLlm } from "wolbarg";

const ctx = wolbarg({
  organization,
  storage: sqlite("./memory.db"),
  embedding: openaiEmbedding({ /* … */ }),
  llm: openaiLlm({ /* … */ }), // optional
});

// init() still works for compatibility
```

--------------------------------

### Store and recall conversation messages with rememberFromMessages

Source: https://wolbarg.com/docs/examples/conversation-memory

Initializes a Wolbarg context with SQLite storage and OpenAI embeddings, then demonstrates storing messages using both default and 'all_user' strategies before performing a recall query.

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

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

const messages = [
  { role: "user", content: "I prefer dark mode in the IDE." },
  { role: "assistant", content: "I'll remember that." },
  { role: "user", content: "Also, only deploy on Fridays." },
];

// Store the last user turn (default)
await ctx.rememberFromMessages(messages, {
  agent: "assistant",
  mode: "raw",
});

// Or store every user turn:
await ctx.rememberFromMessages(messages, {
  agent: "assistant",
  mode: "raw",
  rawStrategy: "all_user",
});

const hits = await ctx.recall({
  query: "When can we deploy?",
  topK: 3,
  filter: { agent: "assistant" },
});

console.log(hits.map((h) => h.content.text));

await ctx.close();
```

--------------------------------

### Wolbarg Constructor Patterns

Source: https://wolbarg.com/docs/api/wolbarg

Shows the preferred instantiation methods for the Wolbarg class, including the factory function and the legacy constructor pattern.

```ts
new Wolbarg(options)  // preferred
wolbarg(options)      // factory (recommended in docs)
new Wolbarg()         // then init() for v0.1 compat
```