wolbarg 0.5.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +210 -106
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,59 +1,131 @@
1
- <p align="center">
2
- <img src="./assets/wolbarg-banner.png" alt="Wolbarg Logo: Memory Infrastructure for AI Agents" width="720" />
3
- </p>
1
+ ![Wolbarg — Memory Infrastructure for AI Agents](./assets/wolbarg-banner.png)
4
2
 
5
3
  # Wolbarg
6
4
 
7
- **Modular, provider-agnostic semantic memory for AI agents (v0.5.0).**
5
+ **Modular, provider-agnostic semantic memory for AI agents.**
8
6
 
9
7
  [![npm version](https://img.shields.io/npm/v/wolbarg.svg)](https://www.npmjs.com/package/wolbarg)
10
8
  [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
9
+ [![Node.js](https://img.shields.io/badge/node-%3E%3D22.5-brightgreen.svg)](https://nodejs.org)
11
10
  [![Docs](https://img.shields.io/badge/docs-wolbarg.com-black)](https://wolbarg.com)
12
- [![Benchmarks](https://img.shields.io/badge/benchmarks-Storage%20suite-black)](https://wolbarg.com/benchmarks)
11
+ [![Benchmarks](https://img.shields.io/badge/benchmarks-v0.4%20stress-black)](https://wolbarg.com/benchmarks)
13
12
 
14
- ## What's new in 0.5.0
13
+ ```bash
14
+ npm install wolbarg
15
+ ```
16
+
17
+ 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.
18
+
19
+ **Current release: [v0.5.0](./CHANGELOG.md)** — optional graph memory (SQLite + Neo4j), `includeGraph` recall, cascade forget, graph-aware checkpoints, and [Wolbarg Studio](https://wolbarg.com/docs/observability) graph canvas.
20
+
21
+ ---
22
+
23
+ ## Why Wolbarg?
24
+
25
+ | Problem | What Wolbarg does |
26
+ | --- | --- |
27
+ | Agents forget between sessions | Durable semantic memory on **your** disk or Postgres |
28
+ | Vendor lock-in | Pluggable embeddings, LLM, rerankers, OCR, vision, storage, graph |
29
+ | Vectors alone are not enough | Hybrid search (semantic + BM25), metadata filters, MMR, optional rerank |
30
+ | Multi-agent writes collide | SQLite `BEGIN IMMEDIATE` + retries; Postgres row-level locking |
31
+ | Duplicate facts pile up | Opt-in write-time dedupe / upsert |
32
+ | Repeated embeds cost money | Transparent embedding cache (default on) |
33
+ | Need structure, not only similarity | Optional **graph** — `linkMemories` / `getRelated` (SQLite ↔ Neo4j) |
34
+ | Hard to debug memory | Telemetry + **Wolbarg Studio** (local, read-only) |
35
+
36
+ ---
37
+
38
+ ## Features
39
+
40
+ - **Storage** — SQLite (`node:sqlite` + sqlite-vec) or PostgreSQL (+ optional pgvector)
41
+ - **Recall** — semantic, hybrid, metadata filters, MMR, rerank, `explain: true`
42
+ - **Ingest** — text / markdown / PDF / DOCX / images (peers for PDF/DOCX/OCR)
43
+ - **Compress** — optional LLM summarization with archive lineage
44
+ - **`subscribe()`** — real-time change events (SQLite in-process; Postgres LISTEN/NOTIFY)
45
+ - **Concurrency** — multi-writer SQLite hardening (`WOLBARG_STORAGE_LOCKED`)
46
+ - **Embedding cache** — `hash(content) + model`
47
+ - **Dedupe / upsert** — opt-in exact / near / exact-or-near
48
+ - **Graph memory (0.5)** — `sqliteGraph` / `neo4jGraph`, `linkMemories`, `getRelated`, `includeGraph`
49
+ - **Checkpoints / export** — file-backed SQLite snapshots (+ graph file when applicable)
50
+ - **Telemetry** — independent event DB; Studio dashboard, Trace Explorer, graph canvas
51
+
52
+ Docs: [Getting started](https://wolbarg.com/docs/getting-started) · [What's new in 0.5](https://wolbarg.com/docs/guides/whats-new) · [Graph memory](https://wolbarg.com/docs/graph-memory) · [Studio](https://wolbarg.com/docs/observability)
53
+
54
+ ---
55
+
56
+ ## Benchmarks (v0.4.0 stress · mock embeddings)
57
+
58
+ Published dual-backend **v4-stress** suite (2026-07-18 · Node v24.13.1 · win32/arm64 · 8 CPUs). Mock embeddings isolate SDK + database cost — not LIVE provider latency.
59
+
60
+ ### Headlines
15
61
 
16
- Optional **graph memory** (`sqliteGraph` / `neo4jGraph`), `linkMemories` / `getRelated`, `recall({ includeGraph: true })`, cascade forget, graph-aware checkpoints, and **Wolbarg Studio** graph canvas.
62
+ | Metric | SQLite | PostgreSQL |
63
+ | --- | --- | --- |
64
+ | Cold `ready()` | **16.18 ms** | **91.39 ms** |
65
+ | Batch remember (200) | **5,795 ops/s** | **2,795 ops/s** |
66
+ | Bulk insert 2k | **7,509 ops/s** | **4,085 ops/s** |
67
+ | Recall p95 @ 2k | **4.83 ms** | **141.5 ms** |
68
+ | 16 writers throughput | **8,660 ops/s** | **3,335 ops/s** |
69
+ | Embedding cache speedup | **1.47×** | **1.18×** |
70
+ | Suite result | 25 pass / 0 fail | 21 pass / 0 fail / 4 skip\* |
17
71
 
18
- Full notes: [CHANGELOG](./CHANGELOG.md) · [Docs — What's New](https://wolbarg.com/docs/guides/whats-new) · [Graph memory](https://wolbarg.com/docs/graph-memory) · [Studio](https://wolbarg.com/docs/observability)
72
+ \*Postgres skips SQLite-only paths (telemetry EventDatabase, file checkpoints, export/import).
19
73
 
20
- ## Benchmarks
74
+ ### SQLite — stress & concurrency
21
75
 
22
- **v0.2.1 Storage suite** (mock embeddings · scale quick) — dual-backend SQLite + PostgreSQL:
76
+ | Case | Result |
77
+ | --- | --- |
78
+ | Bulk insert 2k + search | 7,509 insert ops/s · recall p50 **4.12 ms** · p95 **4.83 ms** |
79
+ | 8 writers × 20 ops | **6,084** ops/s · p95 **3.05 ms** · 0 failures |
80
+ | 16 writers × 20 ops | **8,660** ops/s · p95 **2.46 ms** · 0 failures |
81
+ | 32 writers × 20 ops | **6,798** ops/s · p95 **22.94 ms** · 0 failures |
82
+ | Mixed read/write storm | 0 failures |
83
+
84
+ ### PostgreSQL — stress & concurrency
23
85
 
24
- | Metric | Result |
86
+ | Case | Result |
25
87
  | --- | --- |
26
- | SQLite search @ 1k | **2.02 ms** |
27
- | SQLite insert @ 1k | **1.72k ops/sec** |
28
- | SQLite cold start | **7.91 ms** |
29
- | Postgres 16 writers | **1.12k ops/sec** |
88
+ | Bulk insert 2k + search | 4,085 insert ops/s · recall p50 **23.29 ms** · p95 **141.5 ms** |
89
+ | 8 writers × 20 ops | **2,555** ops/s · p95 **8.51 ms** · 0 failures |
90
+ | 16 writers × 20 ops | **3,335** ops/s · p95 **9.48 ms** · 0 failures |
91
+ | 32 writers × 20 ops | **3,802** ops/s · p95 **14.77 ms** · 0 failures |
92
+ | Mixed read/write storm | 0 failures |
93
+
94
+ **Artifacts:** [SQLite JSON](https://wolbarg.com/benchmarks/version-0.4.0-sqlite-benchmark.json) · [SQLite MD](https://wolbarg.com/benchmarks/version-0.4.0-sqlite-benchmark.md) · [Postgres JSON](https://wolbarg.com/benchmarks/version-0.4.0-postgres-benchmark.json) · [Postgres MD](https://wolbarg.com/benchmarks/version-0.4.0-postgres-benchmark.md) · [Interactive page](https://wolbarg.com/benchmarks) · [Methodology](https://wolbarg.com/docs/benchmarks)
30
95
 
31
- Storage (mock) ≠ LIVE (real providers). Full page: [wolbarg.com/benchmarks](https://wolbarg.com/benchmarks) · [methodology](https://wolbarg.com/docs/benchmarks) · [raw JSON](https://wolbarg.com/benchmarks/benchmark.json).
96
+ Also published: [embedding-cache](https://wolbarg.com/benchmarks/embedding-cache.json) · [multiprocess concurrency](https://wolbarg.com/benchmarks/multiprocess-concurrency.json)
97
+
98
+ ---
32
99
 
33
100
  ## Installation
34
101
 
35
102
  ```bash
36
103
  npm install wolbarg
104
+ # or: pnpm add wolbarg · yarn add wolbarg · bun add wolbarg
37
105
  ```
38
106
 
39
- Node.js **22.5+**.
107
+ **Requires Node.js 22.5+** (built-in `node:sqlite`).
108
+
109
+ ### Optional peers
40
110
 
41
- ### Optional peers (install when you use the feature)
111
+ Install only what you use:
42
112
 
43
113
  | Peer | Required for |
44
114
  | --- | --- |
45
- | `pg` | `postgres({ … })` storage |
46
- | `neo4j-driver` | `neo4jGraph({ … })` graph backend |
47
- | `pdf-parse` (pin `@1.1.4`) | `ingest()` of `.pdf` files |
48
- | `mammoth` | `ingest()` of `.docx` files |
49
- | `tesseract.js` | OCR provider for images |
115
+ | `pg` | PostgreSQL storage |
116
+ | `neo4j-driver` | `neo4jGraph(...)` |
117
+ | `pdf-parse@1.1.4` | PDF ingest |
118
+ | `mammoth` | DOCX ingest |
119
+ | `tesseract.js` | OCR |
50
120
 
51
121
  ```bash
52
- # Example: PDF + DOCX ingest
53
- npm install pdf-parse@1.1.4 mammoth
122
+ npm install pg neo4j-driver # production storage + graph
123
+ npm install pdf-parse@1.1.4 mammoth # document ingest
54
124
  ```
55
125
 
56
- **Important:** these packages are **not** bundled with `Wolbarg`. If you call `ingest()` on PDF/DOCX without the matching peer, Wolbarg throws a configuration error at use time (not at import). Plain `.txt` / `.md` / `.csv` / `.json` need no extras.
126
+ Peers are **not** bundled. Missing peers fail at use time for that path — not at import. Plain `.txt` / `.md` / `.csv` / `.json` and SQLite graph need no extras.
127
+
128
+ ---
57
129
 
58
130
  ## Quick start
59
131
 
@@ -72,66 +144,83 @@ const ctx = wolbarg({
72
144
  model: "gpt-4.1-mini",
73
145
  }),
74
146
  keywordSearch: bm25(),
147
+ concurrency: { maxRetries: 5 },
148
+ embeddingCache: { enabled: true },
149
+ memory: { dedupe: { enabled: true, strategy: "exact-or-near" } },
75
150
  telemetry: {
76
151
  enabled: true,
77
152
  database: { provider: "sqlite", url: "./telemetry.db" },
78
153
  level: "debug",
79
- captureQueries: true,
80
- captureLatency: true,
81
154
  },
82
155
  });
83
156
 
84
- await ctx.remember({
157
+ await ctx.ready();
158
+
159
+ const saved = await ctx.remember({
85
160
  agent: "research",
86
161
  content: { text: "Stripe supports recurring invoices." },
87
162
  metadata: { topic: "billing" },
88
163
  });
164
+ // saved.action === "created" | "updated"
165
+
166
+ const hits = await ctx.recall({
167
+ query: "How do recurring invoices work?",
168
+ topK: 5,
169
+ hybrid: true,
170
+ });
171
+
172
+ ctx.subscribe({ organization: "my-org" }, (e) => {
173
+ console.log(e.event, e.memoryId);
174
+ });
89
175
 
90
- const hits = await ctx.recall({ query: "invoices", topK: 5 });
91
- const explained = await ctx.recall({ query: "invoices", explain: true });
92
176
  await ctx.checkpoint("before-compress");
177
+ await ctx.close();
93
178
  ```
94
179
 
95
- ### Optional graph (0.5)
180
+ ### Graph memory (0.5)
181
+
182
+ Same typed API locally and in production — swap only the factory:
96
183
 
97
184
  ```ts
98
- import { wolbarg, openaiEmbedding, sqliteGraph } from "wolbarg";
185
+ import { wolbarg, openaiEmbedding, sqliteGraph, neo4jGraph } from "wolbarg";
99
186
 
100
- const ctx = wolbarg({
101
- organization: "my-org",
102
- database: { provider: "sqlite", url: "./memory.db" },
103
- embedding: openaiEmbedding({
104
- apiKey: process.env.OPENAI_API_KEY!,
105
- model: "text-embedding-3-small",
106
- }),
107
- graph: sqliteGraph({ path: "./graph.db" }),
108
- });
187
+ // Local
188
+ graph: sqliteGraph({ path: "./graph.db" })
189
+
190
+ // Production
191
+ graph: neo4jGraph({
192
+ url: process.env.NEO4J_URL!,
193
+ username: process.env.NEO4J_USER!,
194
+ password: process.env.NEO4J_PASSWORD!,
195
+ })
196
+ ```
109
197
 
198
+ ```ts
110
199
  const a = await ctx.remember({
111
- agent: "research",
200
+ agent: "support",
112
201
  content: { text: "Refunds take 5 business days." },
113
202
  });
114
203
  const b = await ctx.remember({
115
- agent: "research",
204
+ agent: "support",
116
205
  content: { text: "Chargebacks escalate to risk." },
117
206
  });
207
+
118
208
  await ctx.linkMemories(a.id, b.id, "related_to");
119
- const related = await ctx.getRelated(a.id);
209
+ const related = await ctx.getRelated(a.id, { depth: 1 });
210
+
211
+ const withGraph = await ctx.recall({
212
+ query: "refunds",
213
+ includeGraph: true,
214
+ });
215
+ // withGraph[0].related — neighbors from the graph
120
216
  ```
121
217
 
122
- `new Wolbarg({ storage: sqlite("./memory.db"), embedding })` remains supported for backwards compatibility.
218
+ Guide: [Graph memory](https://wolbarg.com/docs/graph-memory) · Prefer a [provider-isolated project layout](https://wolbarg.com/docs/installation#project-layout) so backend swaps stay one-file.
123
219
 
124
- ## Quick start (legacy constructor)
220
+ ### Constructor DI (still supported)
125
221
 
126
222
  ```ts
127
- import {
128
- Wolbarg,
129
- sqlite,
130
- openaiEmbedding,
131
- openaiLlm,
132
- bm25,
133
- meta,
134
- } from "wolbarg";
223
+ import { Wolbarg, sqlite, openaiEmbedding } from "wolbarg";
135
224
 
136
225
  const ctx = new Wolbarg({
137
226
  organization: "my-org",
@@ -140,78 +229,93 @@ const ctx = new Wolbarg({
140
229
  apiKey: process.env.OPENAI_API_KEY!,
141
230
  model: "text-embedding-3-small",
142
231
  }),
143
- llm: openaiLlm({
144
- apiKey: process.env.OPENAI_API_KEY!,
145
- model: "gpt-4.1-mini",
146
- }),
147
- keywordSearch: bm25(),
148
- });
149
-
150
- await ctx.remember({
151
- agent: "research",
152
- content: { text: "Stripe supports recurring invoices." },
153
- metadata: { topic: "billing" },
154
- });
155
-
156
- const hits = await ctx.recall({
157
- query: "recurring invoices",
158
- topK: 5,
159
- hybrid: true,
160
- filter: { metadata: meta.eq("topic", "billing") },
161
232
  });
162
233
  ```
163
234
 
164
235
  **Required:** `organization`, `storage` or `database`, `embedding`.
165
- **Optional:** `llm`, `telemetry`, `keywordSearch`, `reranker`, `ocr`, `vision`, `chunking`, `compression`, `retrieval`, `checkpoint`.
236
+ **Optional:** `llm`, `keywordSearch`, `reranker`, `ocr`, `vision`, `chunking`, `telemetry`, `concurrency`, `embeddingCache`, `memory.dedupe`, `graph`, `checkpoint` / `checkpointDirectory`.
166
237
 
167
- Calling `compress` without `llm` is a TypeScript error.
238
+ ---
168
239
 
169
- ## API
240
+ ## API surface
170
241
 
171
- | Method | Description |
242
+ | Method | Role |
172
243
  | --- | --- |
173
- | `remember` / `rememberBatch` | Store + embed |
174
- | `recall` / `recallBatch` | Semantic / hybrid search (`explain: true` for diagnostics) |
175
- | `ingest` | Documents → chunks → memories (**peers** for PDF/DOCX/OCR) |
176
- | `compress` | LLM summary (needs `llm`) |
177
- | `checkpoint` / `rollback` / `listCheckpoints` | First-party memory snapshots |
178
- | `export` / `import` | Portable SQLite memory bundles |
179
- | `forget` / `history` / `stats` / `clear` | Management |
180
- | `ready` / `close` | Lifecycle |
244
+ | `remember` / `rememberBatch` | Embed + store (`RememberResult` includes `action`) |
245
+ | `update` | Edit an existing memory by id |
246
+ | `recall` / `recallBatch` | Semantic / hybrid search; `explain` · `includeGraph` |
247
+ | `ingest` | Documents → chunks → memories |
248
+ | `compress` | LLM summary (requires `llm`) |
249
+ | `linkMemories` / `getRelated` | Graph edges / traversal (requires `graph`) |
250
+ | `subscribe` | Real-time change callbacks |
251
+ | `checkpoint` / `rollback` / `listCheckpoints` / … | SQLite snapshots (+ graph file when SQLite graph) |
252
+ | `export` / `import` | Portable SQLite + manifest |
253
+ | `forget` / `history` / `stats` / `clear` | Lifecycle (forget/clear cascade graph when configured) |
254
+ | `ready` / `close` / `flushTelemetry` | Lifecycle |
255
+
256
+ Full reference: [wolbarg.com/docs/api](https://wolbarg.com/docs/api)
181
257
 
182
- ## Studio
258
+ ---
183
259
 
184
- Local telemetry dashboard (separate app — not bundled into the SDK):
260
+ ## Wolbarg Studio
261
+
262
+ Local observability dashboard — **not** bundled in the npm package. The SDK writes telemetry; Studio reads it (and can open memory / graph files for the canvas).
185
263
 
186
264
  ```bash
187
- cd wolbarg_studio
265
+ git clone https://github.com/Atharvmunde11/wolbarg-studio
266
+ cd wolbarg-studio
188
267
  npm install
189
- npm run dev
268
+ npm run dev # http://localhost:3100
190
269
  ```
191
270
 
192
- Open http://localhost:3100 and connect to your `./telemetry.db`. Connections persist under the user config directory (`~/.wolbarg/studio.json` / AppData), never inside the project.
271
+ Connect telemetry (`./telemetry.db`), optional memory DB, checkpoint directory, and graph backend. Screenshots and setup: [Observability & Studio](https://wolbarg.com/docs/observability).
193
272
 
194
- Telemetry SQLite files use an additive, versioned schema. On writable open, v1
195
- files are migrated in place to telemetry schema v2 and retain all existing
196
- events. V2 adds organization, agent, tags, checkpoint, persisted recall
197
- explanations, and measured stage spans. `SqliteEventDatabase.query()` can filter
198
- by `organization`, `agentId`, `tag`, and `checkpointId`; read-only access to an
199
- unmigrated v1 file remains supported.
273
+ ---
200
274
 
201
- Full documentation: [wolbarg.com](https://wolbarg.com/docs/introduction)
275
+ ## Documentation
202
276
 
203
- ## Limitations (v0.3)
277
+ | Topic | Link |
278
+ | --- | --- |
279
+ | Getting started | https://wolbarg.com/docs/getting-started |
280
+ | Installation & project layout | https://wolbarg.com/docs/installation |
281
+ | Configuration | https://wolbarg.com/docs/configuration |
282
+ | Graph memory | https://wolbarg.com/docs/graph-memory |
283
+ | Observability & Studio | https://wolbarg.com/docs/observability |
284
+ | Concurrency | https://wolbarg.com/docs/concurrency |
285
+ | Real-time events | https://wolbarg.com/docs/realtime-events |
286
+ | Embedding cache | https://wolbarg.com/docs/embedding-cache |
287
+ | Memory upsert | https://wolbarg.com/docs/memory-upsert |
288
+ | What's new in 0.5 | https://wolbarg.com/docs/guides/whats-new |
289
+ | Migration | https://wolbarg.com/docs/migration |
290
+ | Limitations | https://wolbarg.com/docs/guides/limitations |
291
+ | Changelog | [CHANGELOG.md](./CHANGELOG.md) |
292
+
293
+ ---
294
+
295
+ ## Limitations
296
+
297
+ - **Node 22.5+** required (`node:sqlite`).
298
+ - **Ingest peers** required for PDF / DOCX / OCR paths.
299
+ - **PDF** text-layer via `pdf-parse`; scan PDFs need OCR/vision.
300
+ - **Telemetry** is SQLite-only today (Postgres typed but not implemented).
301
+ - **SQLite `subscribe()`** is in-process only; Postgres uses LISTEN/NOTIFY.
302
+ - **Checkpoints / export** require file-backed SQLite memory (not `:memory:` / not Postgres).
303
+ - **Neo4j** checkpoint / export / import throw `GraphCheckpointNotSupportedError` (refuse, don't skip).
304
+ - **Cypher `query()`** is Neo4j-only; SQLite graph uses typed methods.
305
+ - Not an agent framework, chat UI, or hosted vector SaaS.
306
+
307
+ ---
308
+
309
+ ## Upgrade
204
310
 
205
- - **Ingest peers are opt-in but required for those formats** — see table above.
206
- - **PDF text layer only** via `pdf-parse`; scan/image PDFs need OCR/vision (or a text PDF). Older pdf.js in `pdf-parse@1.1.4` may reject some modern PDFs.
207
- - **Node `node:sqlite` is experimental**; Node **22.5+** required.
208
- - **Postgres** memory storage needs `pg`; telemetry/checkpoints are SQLite-only in v0.3 (interfaces ready for Postgres).
209
- - **Not** an agent framework, chat UI, or hosted vector SaaS.
311
+ ```bash
312
+ npm install wolbarg@^0.5.0
313
+ ```
210
314
 
211
- ## Migration from 0.1 / 0.2
315
+ 0.5 is **additive**. Omitting `graph` keeps 0.4 behavior. See [Migration](https://wolbarg.com/docs/migration) and [CHANGELOG](./CHANGELOG.md).
212
316
 
213
- `init()` and `new Wolbarg({ storage })` still work. Prefer `wolbarg({ database, telemetry })`. LLM is optional. Schema auto-migrates to v2.
317
+ ---
214
318
 
215
319
  ## License
216
320
 
217
- MIT
321
+ MIT © [Atharv Munde](https://github.com/Atharvmunde11)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "wolbarg",
3
- "version": "0.5.0",
3
+ "version": "0.5.1",
4
4
  "description": "Wolbarg — modular, provider-agnostic semantic memory SDK for AI agents. SQLite + PostgreSQL, optional graph memory (SQLite / Neo4j), hybrid search, ingest, and rerankers.",
5
5
  "license": "MIT",
6
6
  "author": {