wolbarg 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -5,13 +5,41 @@ 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
+## [0.3.2] — 2026-07-18
 
 ### Changed
 
+- **npm metadata** — `repository`, `bugs`, `homepage`, and `funding` now point at [wolbarg/wolbarg](https://github.com/wolbarg/wolbarg)
+
+## [0.3.1] — 2026-07-17
+
+### Fixed
+
+- **Checkpoint rollback recovery** — a failed `rollback()` (e.g. missing checkpoint name) no longer leaves SQLite storage closed; the checkpoint is validated before close, and storage is reopened on error
+- **Import recovery** — a failed `import()` reopens storage the same way so the client stays usable after a bad export path
+
+## [0.3.0] — 2026-07-17
+
+### Added
+
+- **Telemetry system** — independent EventDatabase (never shares tables with memory). SQLite provider first; interface-ready for PostgreSQL.
+- **`wolbarg()` factory** plus `database.url` / `telemetry` configuration (additive; `storage` + `init()` still work)
+- **Trace system** — `session_id`, `trace_id`, `parent_trace_id` for waterfall debugging
+- **Telemetry schema v2** — additive organization, agent, tags, checkpoint, recall-explain, and stage-span fields with indexed queries and automatic v1 migration
+- **Recall explain mode** — `recall({ explain: true })` returns ranking diagnostics and timings
+- **Checkpoint API** — `checkpoint`, `rollback`, `deleteCheckpoint`, `listCheckpoints`, `getCheckpoint` (first-party SQLite snapshots, never overwrite)
+- **Import / export** — portable SQLite + manifest bundles
+- **Batch APIs** — `rememberBatch`, `recallBatch` with parent + child telemetry traces
+- **Actionable errors** — operation-scoped messages with reason + suggestion
+- **Internal benchmark helpers** — `runBenchmark` / `summarizeBenchmark`
+- **Wolbarg Studio** — separate Next.js app that reads telemetry databases (see `/wolbarg_studio`)
+
+### Changed
+
+- **Telemetry instrumentation** — records available organization/agent/checkpoint context, persists real recall explanations, and reports measured pipeline stages without inventing recency signals
 - **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)
+- **Links** — docs and homepage now at [wolbarg.com](https://wolbarg.com); GitHub at [wolbarg/wolbarg](https://github.com/wolbarg/wolbarg)
 - **Schema** — internal meta table renamed `agentorc_meta` → `wolbarg_meta` (new databases only; recreate or migrate existing DBs)
 
 ### Migration
@@ -22,10 +50,25 @@ npm install wolbarg
 ```
 
 ```ts
-import { Wolbarg, sqlite, openaiEmbedding } from "wolbarg";
-const ctx = new Wolbarg({ /* same options shape */ });
+import { wolbarg, openaiEmbedding } from "wolbarg";
+
+const ctx = wolbarg({
+  organization: "my-org",
+  database: { provider: "sqlite", url: "./memory.db" },
+  embedding: openaiEmbedding({
+    apiKey: process.env.OPENAI_API_KEY!,
+    model: "text-embedding-3-small",
+  }),
+  telemetry: {
+    enabled: true,
+    database: { provider: "sqlite", url: "./telemetry.db" },
+    level: "debug",
+  },
+});
 ```
 
+`new Wolbarg({ storage, embedding })` and `init({ database })` remain fully supported.
+
 ## [0.2.1] — 2026-07-15
 
 ### Fixed
@@ -83,6 +126,9 @@ const ctx = new Wolbarg({ /* same options shape */ });
 
 - 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.3.2]: https://github.com/wolbarg/wolbarg/releases/tag/v0.3.2
+[0.3.1]: https://github.com/wolbarg/wolbarg/releases/tag/v0.3.1
+[0.3.0]: https://github.com/wolbarg/wolbarg/releases/tag/v0.3.0
+[0.2.1]: https://github.com/wolbarg/wolbarg/releases/tag/v0.2.1
+[0.2.0]: https://github.com/wolbarg/wolbarg/releases/tag/v0.2.0
 [0.1.1]: https://www.npmjs.com/package/wolbarg/v/0.1.1

package/README.md

@@ -1,6 +1,10 @@
+<p align="center">
+  <img src="./assets/wolbarg-banner.png" alt="Wolbarg Logo: Memory Infrastructure for AI Agents" width="720" />
+</p>
+
 # Wolbarg
 
-**Modular, provider-agnostic semantic memory for AI agents (v0.3.0).**
+**Modular, provider-agnostic semantic memory for AI agents (v0.3.1).**
 
 [![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)
@@ -46,6 +50,45 @@ npm install pdf-parse@1.1.4 mammoth
 
 ## Quick start
 
+```ts
+import { wolbarg, openaiEmbedding, openaiLlm, bm25 } from "wolbarg";
+
+const ctx = wolbarg({
+  organization: "my-org",
+  database: { provider: "sqlite", url: "./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(),
+  telemetry: {
+    enabled: true,
+    database: { provider: "sqlite", url: "./telemetry.db" },
+    level: "debug",
+    captureQueries: true,
+    captureLatency: true,
+  },
+});
+
+await ctx.remember({
+  agent: "research",
+  content: { text: "Stripe supports recurring invoices." },
+  metadata: { topic: "billing" },
+});
+
+const hits = await ctx.recall({ query: "invoices", topK: 5 });
+const explained = await ctx.recall({ query: "invoices", explain: true });
+await ctx.checkpoint("before-compress");
+```
+
+`new Wolbarg({ storage: sqlite("./memory.db"), embedding })` remains supported for backwards compatibility.
+
+## Quick start (legacy constructor)
+
 ```ts
 import {
   Wolbarg,
@@ -84,8 +127,8 @@ const hits = await ctx.recall({
 });
 ```
 
-**Required:** `organization`, `storage`, `embedding`.  
-**Optional:** `llm`, `keywordSearch`, `reranker`, `ocr`, `vision`, `chunking`, `compression`, `retrieval`.
+**Required:** `organization`, `storage` or `database`, `embedding`.  
+**Optional:** `llm`, `telemetry`, `keywordSearch`, `reranker`, `ocr`, `vision`, `chunking`, `compression`, `retrieval`, `checkpoint`.
 
 Calling `compress` without `llm` is a TypeScript error.
 
@@ -93,28 +136,47 @@ Calling `compress` without `llm` is a TypeScript error.
 
 | Method | Description |
 | --- | --- |
-| `remember` | Store + embed |
-| `recall` | Semantic / hybrid search |
+| `remember` / `rememberBatch` | Store + embed |
+| `recall` / `recallBatch` | Semantic / hybrid search (`explain: true` for diagnostics) |
 | `ingest` | Documents → chunks → memories (**peers** for PDF/DOCX/OCR) |
 | `compress` | LLM summary (needs `llm`) |
+| `checkpoint` / `rollback` / `listCheckpoints` | First-party memory snapshots |
+| `export` / `import` | Portable SQLite memory bundles |
 | `forget` / `history` / `stats` / `clear` | Management |
 | `ready` / `close` | Lifecycle |
 
+## Studio
+
+Local telemetry dashboard (separate app — not bundled into the SDK):
+
+```bash
+cd wolbarg_studio
+npm install
+npm run dev
+```
+
+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.
+
+Telemetry SQLite files use an additive, versioned schema. On writable open, v1
+files are migrated in place to telemetry schema v2 and retain all existing
+events. V2 adds organization, agent, tags, checkpoint, persisted recall
+explanations, and measured stage spans. `SqliteEventDatabase.query()` can filter
+by `organization`, `agentId`, `tag`, and `checkpointId`; read-only access to an
+unmigrated v1 file remains supported.
+
 Full documentation: [wolbarg.com](https://wolbarg.com/docs/introduction)
 
-## Limitations (v0.2)
+## Limitations (v0.3)
 
 - **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).
+- **Postgres** memory storage needs `pg`; telemetry/checkpoints are SQLite-only in v0.3 (interfaces ready for Postgres).
 - **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
+## Migration from 0.1 / 0.2
 
-`init()` still works. Prefer constructor DI. LLM is optional. Schema auto-migrates to v2.
+`init()` and `new Wolbarg({ storage })` still work. Prefer `wolbarg({ database, telemetry })`. LLM is optional. Schema auto-migrates to v2.
 
 ## License