Wolbarg

https://wolbarg.com/docs
Admin
Wolbarg is a durable shared memory SDK for multi-agent systems and AI coding agents, providing...
Tokens:57,833
Snippets:629
Trust Score:5.2
Update:1 month ago
Show doc for...
Tokens:
Raw
### 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 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 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
```

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

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

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

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

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

### 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()
```

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

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

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

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

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

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

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

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

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

### 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.
```

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

### 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
```
Tokens:
Raw