wolbarg 0.3.2 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,46 @@ 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.5.0] — 2026-07-19
+
+### Added
+
+- **Optional graph memory** — `graph` constructor option with `sqliteGraph({ path })` (local) and `neo4jGraph({ url, username, password })` (networked); optional peer `neo4j-driver`
+- **Typed graph API** — `linkMemories()`, `getRelated()` on the facade; provider surface also includes `unlinkMemories`, `upsertEntity`, `linkEntityToMemory`, `deleteMemory`
+- **`recall({ includeGraph: true })`** — attaches `related` neighbor memories from the graph
+- **Cascade deletes** — `forget` / `clear` remove graph memory nodes and incident edges when graph is configured
+- **Graph-aware checkpoints / export** — file-backed SQLite graph snapshots alongside memory DB; Neo4j refuses with `GraphCheckpointNotSupportedError` (`GRAPH_CHECKPOINT_NOT_SUPPORTED`)
+- **Schema v4** — memory DB index / ANN housekeeping migration on open (graph tables live in a separate SQLite file or Neo4j)
+- **Wolbarg Studio** — graph canvas, Connect for memory/telemetry/checkpoints/graph, ops filters for graph methods, stream / checkpoints / explain polish
+- **Docs** — Graph memory, What's New 0.5, Observability screenshots, provider-isolated project layout
+
+### Compatibility
+
+- Graph is **optional** and **additive**. Omitting `graph` leaves 0.4 behavior unchanged.
+- No required constructor changes for upgrades from **0.4.x**.
+- Raw Cypher `query()` is Neo4j-only; SQLite graph hard-errors (use typed methods for portable code).
+
+## [0.4.0] — 2026-07-18
+
+### Added
+
+- **`subscribe()`** — real-time memory change events (SQLite in-process EventEmitter; Postgres LISTEN/NOTIFY with reconnect)
+- **Multi-writer SQLite concurrency** — `BEGIN IMMEDIATE`, exponential backoff retry, `concurrency` constructor config, stable error code `WOLBARG_STORAGE_LOCKED`
+- **Embedding cache** — transparent `hash(content)+model` cache with optional LRU/TTL (`embeddingCache` config); additive `cacheHit` path via cache wrapper stats
+- **Memory upsert / dedupe** — opt-in write-time exact and near-duplicate detection updates existing active memories instead of inserting (`memory.dedupe`); `RememberResult.action`; history event `"updated"`; public `update()`
+- **Schema v3** — `content_hash` column, unique active hash index, `embedding_cache` table, history CHECK allows `'updated'`
+- **Docs** — Concurrency, Real-time events, Embedding cache, Memory upsert pages
+- **Benchmarks** — `benchmark/multiprocess-levels.ts`, `benchmark/embedding-cache-bench.ts`
+
+### Changed
+
+- SQLite mutating transactions use `BEGIN IMMEDIATE` instead of deferred `BEGIN`
+- `remember()` / `rememberBatch()` return `RememberResult` (MemoryRecord + `action`) — additive field
+
+### Compatibility
+
+- All features are additive. Dedupe defaults **off**. Embedding cache defaults **on**. No required constructor changes for upgrades from 0.3.x.
+
 ## [0.3.2] — 2026-07-18
 
 ### Changed
@@ -126,6 +166,8 @@ const ctx = wolbarg({
 
 - Initial npm release path (pre–modular storage / ingest)
 
+[0.5.0]: https://github.com/wolbarg/wolbarg/releases/tag/v0.5.0
+[0.4.0]: https://github.com/wolbarg/wolbarg/releases/tag/v0.4.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

package/README.md

@@ -4,13 +4,19 @@
 
 # Wolbarg
 
-**Modular, provider-agnostic semantic memory for AI agents (v0.3.1).**
+**Modular, provider-agnostic semantic memory for AI agents (v0.5.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)
 
+## What's new in 0.5.0
+
+Optional **graph memory** (`sqliteGraph` / `neo4jGraph`), `linkMemories` / `getRelated`, `recall({ includeGraph: true })`, cascade forget, graph-aware checkpoints, and **Wolbarg Studio** graph canvas.
+
+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)
+
 ## Benchmarks
 
 **v0.2.1 Storage suite** (mock embeddings · scale quick) — dual-backend SQLite + PostgreSQL:
@@ -37,6 +43,7 @@ Node.js **22.5+**.
 | Peer | Required for |
 | --- | --- |
 | `pg` | `postgres({ … })` storage |
+| `neo4j-driver` | `neo4jGraph({ … })` graph backend |
 | `pdf-parse` (pin `@1.1.4`) | `ingest()` of `.pdf` files |
 | `mammoth` | `ingest()` of `.docx` files |
 | `tesseract.js` | OCR provider for images |
@@ -85,6 +92,33 @@ const explained = await ctx.recall({ query: "invoices", explain: true });
 await ctx.checkpoint("before-compress");
 ```
 
+### Optional graph (0.5)
+
+```ts
+import { wolbarg, openaiEmbedding, sqliteGraph } 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",
+  }),
+  graph: sqliteGraph({ path: "./graph.db" }),
+});
+
+const a = await ctx.remember({
+  agent: "research",
+  content: { text: "Refunds take 5 business days." },
+});
+const b = await ctx.remember({
+  agent: "research",
+  content: { text: "Chargebacks escalate to risk." },
+});
+await ctx.linkMemories(a.id, b.id, "related_to");
+const related = await ctx.getRelated(a.id);
+```
+
 `new Wolbarg({ storage: sqlite("./memory.db"), embedding })` remains supported for backwards compatibility.
 
 ## Quick start (legacy constructor)