Construct Wolbarg, remember facts, recall them, and optionally use hybrid search and document ingest.

What is it?

A minimal path from zero to working semantic memory: construct, remember, recall, then optionally hybrid search and document ingest.

For production apps, put factories under providers/ so you can swap SQLite ↔ Postgres without touching agent code — see Project layout.

Coding with Cursor / Claude / Codex?

Use Wolbarg Workspace instead: npx @wolbarg/workspace init. This Quick Start is the SDK path for custom agents.

No API key? Point embeddings at local Ollama (nomic-embed-text) — see the SDK README or use npx wolbarg init and pick Ollama as the provider.

Projects (recommended)

npx wolbarg init

import { createWolbargFromProjectConfig } from "wolbarg";

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

Then continue with remember / recall below using that ctx.

1. Construct

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

const ctx = wolbarg({
  organization: "my-org",
  storage: sqlite("./data/memory.db"),
  embedding: openaiEmbedding({
    apiKey: process.env.OPENAI_API_KEY!,
    model: "text-embedding-3-small",
  }),
  // Optional — enables compress()
  llm: openaiLlm({
    apiKey: process.env.OPENAI_API_KEY!,
    model: "gpt-4.1-mini",
  }),
  // Required when using hybrid: true (fail-closed since 0.6.0)
  keywordSearch: bm25(),
});

2. Remember

const result = await ctx.remember({
  agent: "research",
  content: { text: "Stripe supports recurring invoices." },
  metadata: { topic: "billing", source: "docs" },
});

From a chat transcript (experimental — default needs no LLM):

await ctx.rememberFromMessages(
  [
    { role: "user", content: "Stripe supports recurring invoices." },
    { role: "assistant", content: "Noted." },
  ],
  { agent: "research", mode: "raw" },
);

3. Recall

const results = await ctx.recall({
  query: "How do recurring invoices work?",
  topK: 5,
  threshold: 0.3,
  filter: { agent: "research" },
});

console.log(results[0]?.content.text, results[0]?.similarity);

4. Hybrid + filters (optional)

Since 0.6.0, hybrid: true throws ValidationError if keywordSearch is not configured. There is no silent semantic-only fallback.

import { meta } from "wolbarg";

const hits = await ctx.recall({
  query: "recurring invoices",
  topK: 5,
  hybrid: true,
  filter: {
    agent: "research",
    metadata: meta.eq("topic", "billing"),
  },
});

5. Ingest a document (optional)

Markdown / TXT ingest works out of the box. For PDF or DOCX install peers first (pdf-parse@1.1.4, mammoth). See Document Ingestion.

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

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

When should you use this pattern?

Start here for every new project. Add hybrid search, rerankers, and ingest only when you need them. Switch backends via Project layout instead of scattering factory calls.

To debug what agents remembered and how recall ranked results, enable telemetry and open Wolbarg Studio.

Quick Start

On this page