wolbarg 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.3.0] — 2026-07-16
+
+### Changed
+
+- **Rebrand** — product renamed from AgentOrc / `agentorc` to **Wolbarg** / `wolbarg`
+- **API** — `AgentOrc` → `Wolbarg`, `AgentOrcOptions` → `WolbargOptions`, `AgentOrcError` → `WolbargError`
+- **Links** — docs and homepage now at [wolbarg.com](https://wolbarg.com); GitHub at [Atharvmunde11/wolbarg](https://github.com/Atharvmunde11/wolbarg)
+- **Schema** — internal meta table renamed `agentorc_meta` → `wolbarg_meta` (new databases only; recreate or migrate existing DBs)
+
+### Migration
+
+```bash
+npm uninstall agentorc
+npm install wolbarg
+```
+
+```ts
+import { Wolbarg, sqlite, openaiEmbedding } from "wolbarg";
+const ctx = new Wolbarg({ /* same options shape */ });
+```
+
+## [0.2.1] — 2026-07-15
+
+### Fixed
+
+- **SQLite production hardening** — WAL-safe pragmas, prepared statements, crash-safe batch inserts, and FTS5 kept in the same ACID transaction as semantic writes
+- **PostgreSQL production hardening** — named prepared statements, concurrent insert coalescing / unnest batches, COPY for large ingest, org-scoped ANN with adaptive overfetch, deferred HNSW build
+- **FTS correctness** — archived memories removed from FTS so hybrid/keyword search never returns archived rows; rebuild path when FTS diverges
+- **Multi-tenant isolation** — organization filters enforced on ANN / HNSW query paths so tenants cannot leak across shared Postgres instances
+- **HNSW lifecycle** — index created lazily before first KNN (keeps bulk inserts fast); soft org reset does not drop unrelated indexes incorrectly
+- **Compression correctness** — active-set reduction and archive bookkeeping aligned with recall filters
+- **Vector index paths** — SQLite blob vector index initialization and overfetch handling fixed for recall correctness
+
+### Improved
+
+- **Performance** — batched transactions (SQLite), insert coalescing (Postgres), adaptive overfetch for filtered ANN
+- **Benchmark suite** — dual-backend mock stress + separate LIVE spot suite; clearer methodology separating storage latency from embedding-provider latency
+- **Docs / website** — v0.2.1 release notes, dual-backend benchmark page with SQLite and PostgreSQL sections
+
+### Notes
+
+- Storage benchmarks use mock embeddings to isolate SDK + database performance
+- LIVE spot benchmarks use real embedding providers for end-to-end latency — these are separate suites; do not mix the numbers
+- Node.js **22.5+** still required
+
+## [0.2.0] — 2026-07-14
+
+### Added
+
+- Constructor dependency injection with factory helpers (`sqlite`, `postgres`, `openaiEmbedding`, `openaiLlm`, `bm25`, …)
+- PostgreSQL storage provider (`pg` peer) with optional pgvector
+- Document `ingest()` for TXT/MD/CSV/JSON, PDF (`pdf-parse`), DOCX (`mammoth`), and images (OCR/vision)
+- Hybrid recall (semantic + BM25), metadata filters (`meta.*`), MMR, pluggable rerankers
+- Pluggable chunking strategies and optional vision / OCR providers
+- Website docs for v0.2 including Limitations and What’s New
+- Dual-backend (SQLite + Postgres) test harness
+
+### Changed
+
+- LLM / `compress()` is optional (typed `Wolbarg<true>` when configured)
+- Schema migrates to v2; storage moved behind `StorageProvider`
+- Prefer constructor DI; `init()` remains as a compatibility shim
+
+### Fixed
+
+- Clearer configuration errors when optional ingest peers are missing
+- PDF parser compatibility with `pdf-parse` v1 function API and v2 `PDFParse` class
+
+### Notes / limitations
+
+- PDF/DOCX/OCR require optional peers installed in the consumer app (not bundled)
+- Scan/image-only PDFs need OCR/vision or a text-layer PDF
+- Node `node:sqlite` is experimental; Node.js **22.5+** required
+
+## [0.1.1] — previous
+
+- Initial npm release path (pre–modular storage / ingest)
+
+[0.2.1]: https://github.com/Atharvmunde11/wolbarg/releases/tag/v0.2.1
+[0.2.0]: https://github.com/Atharvmunde11/wolbarg/releases/tag/v0.2.0
+[0.1.1]: https://www.npmjs.com/package/wolbarg/v/0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wolbarg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# Wolbarg
+
+**Modular, provider-agnostic semantic memory for AI agents (v0.3.0).**
+
+[![npm version](https://img.shields.io/npm/v/wolbarg.svg)](https://www.npmjs.com/package/wolbarg)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![Docs](https://img.shields.io/badge/docs-wolbarg.com-black)](https://wolbarg.com)
+[![Benchmarks](https://img.shields.io/badge/benchmarks-Storage%20suite-black)](https://wolbarg.com/benchmarks)
+
+## Benchmarks
+
+**v0.2.1 Storage suite** (mock embeddings · scale quick) — dual-backend SQLite + PostgreSQL:
+
+| Metric | Result |
+| --- | --- |
+| SQLite search @ 1k | **2.02 ms** |
+| SQLite insert @ 1k | **1.72k ops/sec** |
+| SQLite cold start | **7.91 ms** |
+| Postgres 16 writers | **1.12k ops/sec** |
+
+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).
+
+## Installation
+
+```bash
+npm install wolbarg
+```
+
+Node.js **22.5+**.
+
+### Optional peers (install when you use the feature)
+
+| Peer | Required for |
+| --- | --- |
+| `pg` | `postgres({ … })` storage |
+| `pdf-parse` (pin `@1.1.4`) | `ingest()` of `.pdf` files |
+| `mammoth` | `ingest()` of `.docx` files |
+| `tesseract.js` | OCR provider for images |
+
+```bash
+# Example: PDF + DOCX ingest
+npm install pdf-parse@1.1.4 mammoth
+```
+
+**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.
+
+## Quick start
+
+```ts
+import {
+  Wolbarg,
+  sqlite,
+  openaiEmbedding,
+  openaiLlm,
+  bm25,
+  meta,
+} from "wolbarg";
+
+const ctx = new 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(),
+});
+
+await ctx.remember({
+  agent: "research",
+  content: { text: "Stripe supports recurring invoices." },
+  metadata: { topic: "billing" },
+});
+
+const hits = await ctx.recall({
+  query: "recurring invoices",
+  topK: 5,
+  hybrid: true,
+  filter: { metadata: meta.eq("topic", "billing") },
+});
+```
+
+**Required:** `organization`, `storage`, `embedding`.  
+**Optional:** `llm`, `keywordSearch`, `reranker`, `ocr`, `vision`, `chunking`, `compression`, `retrieval`.
+
+Calling `compress` without `llm` is a TypeScript error.
+
+## API
+
+| Method | Description |
+| --- | --- |
+| `remember` | Store + embed |
+| `recall` | Semantic / hybrid search |
+| `ingest` | Documents → chunks → memories (**peers** for PDF/DOCX/OCR) |
+| `compress` | LLM summary (needs `llm`) |
+| `forget` / `history` / `stats` / `clear` | Management |
+| `ready` / `close` | Lifecycle |
+
+Full documentation: [wolbarg.com](https://wolbarg.com/docs/introduction)
+
+## Limitations (v0.2)
+
+- **Ingest peers are opt-in but required for those formats** — see table above.
+- **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.
+- **Node `node:sqlite` is experimental**; Node **22.5+** required.
+- **Postgres** needs `pg`; `pgvector` is optional (falls back to byte embeddings + in-process distance).
+- **Not** an agent framework, chat UI, or hosted vector SaaS.
+
+See [Limitations (v0.2)](https://wolbarg.com/docs/guides/limitations) for the full list.
+
+## Migration from 0.1
+
+`init()` still works. Prefer constructor DI. LLM is optional. Schema auto-migrates to v2.
+
+## License
+
+MIT