plugmem 0.4.0 → 0.6.0

package/README.md

@@ -1,20 +1,26 @@
-# plugmem-napi
+# plugmem
 
 > ⚠️ Experimental. plugmem is mostly an AI-built experiment — written with
 > the help of a small local model (Qwen3.6-35B-A3B-UD-Q4_K_XL.gguf) and various
 > Claude models, in roughly equal measure. Expect non-professional design
 > choices, rough edges, broken behavior, or mistakes. Use it at your own risk.
 
-`plugmem-napi` is the **native Node.js addon** for the plugmem
-[temporal-memory engine](https://docs.rs/plugmem-core/latest) — it embeds
-[`plugmem-host`](https://docs.rs/plugmem-host/latest) **in the Node process**
-(real mmap, file locking, cross-process MVCC — the whole engine, unchanged) and
-exposes it to **JavaScript / TypeScript** as a `Plugmem` class. It is published
-to npm as **`plugmem`**.
+An embeddable bitemporal memory database for local-first applications and
+agents, embedded in your Node process. It stores short facts and answers a
+query with ranked facts and edges plus an optional bounded rendered block.
 
-Because it is native (not WebAssembly), there is no whole-file-in-RAM copy and no
-4 GiB ceiling: the OS pages the snapshot in and out exactly as it does for the
-Rust library. It loads in **Node, and any N-API host (Deno, Bun)**.
+File-backed on disk, no server, no daemon. It links into your process the way
+SQLite does: the engine is [`plugmem-host`](https://docs.rs/plugmem-host/latest)
+compiled to a native addon through [napi-rs](https://napi.rs), so there is no
+WebAssembly copy of the file in RAM and no 4 GiB ceiling. Runs on Node, Deno and
+Bun.
+
+**Contents:** [Install](#install) · [Quick start](#quick-start) ·
+[What it stores](#what-it-stores) · [Two clocks](#two-clocks) ·
+[How recall works](#how-recall-works) · [API](#api) · [Errors](#errors) ·
+[Configuration](#configuration-and-embeddings) ·
+[Async](#async-and-the-event-loop) · [Many memories](#many-memories-in-one-directory) ·
+[What it is not for](#what-it-is-not-for)
 
 ## Install
 
@@ -22,115 +28,324 @@ Rust library. It loads in **Node, and any N-API host (Deno, Bun)**.
 $ npm install plugmem
 ```
 
-`npm i plugmem` pulls the meta package, which through `optionalDependencies`
-installs only the prebuilt binary for your platform — one of
-`plugmem-{linux-x64-gnu, linux-arm64-gnu, darwin-x64, darwin-arm64,
-win32-x64-msvc, win32-arm64-msvc}`. No toolchain, no build step.
+That pulls a meta package which, through `optionalDependencies`, installs only
+the prebuilt binary for your platform: one of `plugmem-{linux-x64-gnu,
+linux-arm64-gnu, darwin-x64, darwin-arm64, win32-x64-msvc, win32-arm64-msvc}`.
+No toolchain, no build step.
+
+## Quick start
+
+```typescript
+import { Plugmem } from "plugmem";
+
+const db = await Plugmem.open("agent.plugmem");
+
+await db.remember({ text: "the user prefers tokio", entity: "user", tags: ["pref"] });
+await db.remember({ text: "the release ships on friday", entity: "release" });
+
+const res = await db.recall({ query: "which runtime?", k: 5 });
+console.log(res.rendered);   // paste this into the prompt
+// - [f0] user: the user prefers tokio (2026-08; active)
+
+db.close();
+```
+
+`Plugmem.open` is a static method, not a constructor, because opening replays a
+journal and maps a snapshot — work proportional to the file — and a JavaScript
+constructor has no way to hand that to a worker thread. Everything is typed:
+`index.d.ts` is generated from the Rust, so a TypeScript host gets real
+autocomplete on arguments and results.
+
+## What it stores
+
+One **fact** is one statement. It carries:
+
+| Field | Meaning |
+|---|---|
+| `text` | the statement itself, and what lexical search indexes |
+| `entity` | the subject, by name — created on first mention, shared across facts |
+| `tags` | filters, not ranking: a query asking for a tag requires it |
+| `metadata` | an opaque `Record<string,string>`. The engine stores and returns it and never looks inside — use it for a URI to the real payload elsewhere, a mime type, an external key |
+| `vector` | an optional embedding; supply your own, or let a configured embedder produce it |
+| `validFrom` | when the statement became true |
+
+Entities are joined by **typed edges**: `link({ src: "ann", rel: "hires", dst: "bob" })`.
+An edge can name the fact it follows from (`provenance`), so a later reader can
+answer "why does the memory think this" instead of trusting a bare relationship.
+
+Facts are never rewritten in place. `revise` closes the old one and chains a
+successor; `forget` tombstones a fact and the next `maintain` erases it from
+disk. `unlink` closes an edge the same way `revise` closes a fact.
 
-## Which door is this?
+## Two clocks
 
-plugmem is **embedded-first, like SQLite**. Pick the door for your language:
+This is the part worth reading, because it is the one thing that behaves
+differently from every other store.
 
-| You are… | Use | Why |
-|---|---|---|
-| **writing JavaScript / TypeScript for Node** | **`plugmem-napi`** (this, npm `plugmem`) | The engine *in your Node process*, native speed, typed for TS. |
-| **writing Rust** | [`plugmem-host`](https://docs.rs/plugmem-host/latest) | The engine in your process, like linking SQLite. |
-| **an agent, or another language** (Python, Go…) | [`plugmem-mcp`](https://docs.rs/plugmem-mcp/latest) | A long-lived stdio JSON-RPC sidecar; language-independent. |
-| a person at a **terminal / script** | [`plugmem-cli`](https://docs.rs/plugmem-cli/latest) | The human door. |
+Every fact carries **two** timestamps, not one:
 
-So: **Node/TS → napi; Rust → host; an agent or other language → MCP; a human →
-the CLI.**
+- **`validFrom` / `validTo`** — when the statement was true.
+- **`recordedAt`** — when the memory learned it. Set by the engine, never by you.
 
-## Usage (TypeScript)
+They are different questions, and one timestamp cannot hold both.
 
-Every argument and result is typed — napi generates `index.d.ts`, so a TS host
-gets full autocomplete and checking. A memory is opened with the static
-`Plugmem.open`, not `new`: opening replays a journal and maps a snapshot, and a
-JavaScript constructor has no way to hand that to a worker thread.
+Unlike the Rust library, this binding reads the system clock on every call — you
+never pass `now` — so `recordedAt` is always the moment of the write:
 
 ```typescript
-import { Plugmem } from "plugmem";
+await db.remember({ text: "lives in Moscow", entity: "kim" });
+const between = Date.now();
+await db.revise(0, { text: "lives in Berlin", entity: "kim" });
 
-const db = await Plugmem.open("agent.plugmem");    // or { readOnly: true }
+(await db.recall({ entities: ["kim"] })).rendered;
+// - [f1] kim: lives in Berlin (2026-08; active)
 
-const out = await db.remember({
-  text: "prefers tokio",
-  entity: "user",
-  tags: ["pref"],
-  links: [{ rel: "works_at", entity: "acme" }],
-  metadata: { source: "chat", uri: "s3://bucket/note.txt" }, // opaque; a pointer
-});
-out.id;                       // number
-out.similar;                  // Similar[] — the engine surfaces conflicts, you decide
+(await db.recall({ entities: ["kim"], asOf: between })).rendered;
+// - [f0] kim: lives in Moscow (2026-08 → 2026-08; closed)
+```
 
-const res = await db.recall({ query: "runtime?", k: 5 });
-res.rendered;                 // the prompt-ready block
-res.facts;                    // RecalledFact[] — { id, score, entity, recordedAt, … }
+`revise` closed the first fact's interval rather than deleting it, which is why
+the second query has something to answer with.
 
-const card = db.get(out.id);
-card.metadata;                // Record<string,string> — keys sorted, {} when none
+`asOf` moves **both** clocks: a fact answers only if it was valid at that
+instant *and* had already been recorded by then. The second half is the one
+people trip over — an `asOf` earlier than a fact's `recordedAt` sees nothing,
+because the memory genuinely knew nothing then. Answering with today's knowledge
+would be the wrong answer to "what did I hold".
 
-await db.revise(out.id, { text: "prefers async-std" });
-await db.link({ src: "user", rel: "works_at", dst: "acme" });
-db.unlink({ src: "user", rel: "works_at", dst: "acme" }); // closes the current edge
+`validFrom` is the other half: a statement that became true before you heard of
+it. Recording today that someone moved a week ago closes the previous interval a
+week ago rather than now, so a query as of three days back finds **neither** —
+the old fact had stopped being true, and the new one was not yet known. That is
+not a hole in the model; it is the honest answer for that instant, and it is
+what a single timestamp cannot express.
 
-await db.checkpoint();        // async (see below)
-db.close();                   // release the file + lock explicitly
+Two more queries over the same axes:
+
+```typescript
+await db.recall({ range: [from, to] });          // what did I record in this window
+await db.recall({ query: "kim", closed: true }); // include closed revisions
 ```
 
-## Configuration & embeddings
+Use `revise` when something changed and `forget` only when a fact was simply
+wrong: `forget` destroys the "what was true then" answer, `revise` keeps it.
+
+Edges are temporal too, so `asOf` walks the graph as it stood then — through
+relationships that have since been unlinked.
+
+## How recall works
+
+Not a vector lookup. Four sources run and are fused by
+[reciprocal-rank fusion](https://plg.uwaterloo.ca/~gvcormac/cormacksigir09-rrf.pdf)
+with a recency boost; tags filter and are not a source:
 
-The constructor resolves settings **exactly like the CLI and MCP server**: an
-explicit `config` path wins, else `$PLUGMEM_CONFIG`, else the platform config
-directory, else all defaults. The database path is resolved as an explicit
-constructor path, then `$PLUGMEM_DB`, then `[database].path`, then the platform
-data directory. See the [full settings reference](https://github.com/m62624/plugmem/blob/main/crates/plugmem-host/SETTINGS.md)
-for all fields and OS-specific paths.
+| Source | What it finds |
+|---|---|
+| **Lexical** — [BM25](https://en.wikipedia.org/wiki/Okapi_BM25) over a Unicode ([UAX #29](https://unicode.org/reports/tr29/)) tokenizer | exact terms, keyword overlap |
+| **Semantic** — int8-quantized cosine, a flat scan below a threshold and an [HNSW](https://arxiv.org/abs/1603.09320) graph above | meaning, nearest neighbours |
+| **Graph** — typed edges walked from the query's anchor entities | relational knowledge |
+| **Temporal** — range scans over the `recordedAt` index, plus the validity test | "what was true then", time windows |
+
+The sources compose. A query with no `query` string still answers from tags,
+entities and time. **Without an embedder the system is complete** — the other
+three sources need no model, no network and no API key.
+
+The result carries both a `rendered` block, selected greedily under a token
+budget and ready to paste, and the structured `facts`/`edges` behind it:
 
 ```typescript
-const db = await Plugmem.open(undefined, { config: "./plugmem.toml" });
+const res = await db.recall({
+  query: "release plans",
+  entities: ["ann"],       // graph anchors
+  tags: ["work"],          // filter: a fact must carry all of these
+  k: 10,                   // cap the number of facts
+  tokenBudget: 400,        // cap the size of the block — your context budget
+  graphDepth: 3,           // how far to walk from the anchors (default 2)
+});
+
+res.rendered;   // string, prompt-ready
+res.facts;      // { id, score, entity, recordedAt, validFrom, validTo, sources }[]
+res.edges;      // { src, rel, dst, provenance }[] — what the graph walked
+res.truncated;  // true if selection stopped at k or the budget with more left
 ```
 
-```toml
-# plugmem.toml
-[database]
-path = "/path/to/memory.plugmem" # optional example
+`remember` returns the new fact's id **plus any live facts it may duplicate or
+contradict**. The engine never merges or deletes on its own — it surfaces the
+tension and your code decides:
 
-[engine]
-dim = 768                     # embedding size (0 = vectors off)
+```typescript
+const out = await db.remember({ text: "the user prefers async-std", entity: "user" });
+for (const s of out.similar) {
+  // s.id, s.score, s.reason: "LexicalOverlap" | "VectorCosine"
+  // → revise it, forget it, or keep both. Your call.
+}
+```
 
-[embedder]                    # optional — omit for lexical/tag/graph/time only
-kind  = "ollama"              # or openai / lmstudio / vllm / llamacpp
-url   = "http://localhost:11434/v1/embeddings"
-model = "nomic-embed-text"
+## API
+
+Every method wraps the identically-named verb of the Rust `Database`; this layer
+only moves arguments and results across the boundary.
+
+**Writing** — all return promises:
+
+| Method | Does |
+|---|---|
+| `remember(args)` | store a fact; resolves with its id and similar facts |
+| `rememberMany(args[])` | store a batch: one embedding round-trip, one journal sync |
+| `revise(id, args)` | close a fact and record its successor |
+| `forget(id)` | tombstone a fact; resolves with whether it was live |
+| `link(args)` | upsert a typed edge, optionally with `provenance` |
+| `unlink(args)` | close the current edge; resolves with whether one was open |
+
+**Reading** — synchronous ones touch mapped memory and return in microseconds:
+
+| Method | Does |
+|---|---|
+| `recall(args?)` | ranked, fused, token-budgeted result (async) |
+| `get(id)` | one fact's full card, or `null` (sync) |
+| `tagsOf(id)` | that fact's tags (sync) |
+| `stats()` | engine size counters (sync) |
+| `path()` | the file this handle resolved to (sync) |
+| `export()` | every open fact as one array (async, unbounded — see below) |
+| `exportPage(cursor?)` | the same data in bounded pages of 128 (async) |
+| `exportEdges(onBatch)` | every current edge, streamed in batches (async) |
+| `configWarnings()` | anything in `config.toml` nothing claimed (sync) |
+
+**Upkeep** — all async, all on a worker thread:
+
+| Method | Does |
+|---|---|
+| `maintain(mode?)` | `"auto"` (default), `"compact"`, `"reindex-text"`, `"optimize-vectors"`, `"full"`. No mode ever drops a revision or an edge version |
+| `checkpoint()` | flush the journal into a fresh snapshot |
+| `verify()` | full content-integrity sweep; rejects on the first inconsistency |
+| `scrub(options?)` | start a resumable byte-level check of the snapshot |
+| `recover(src, dst, options?)` | module function: salvage a damaged file into a clean copy |
+
+**Read-only handles** (`{ readOnly: true }`) observe another process's writer
+over a published snapshot. The read verbs answer, the write verbs throw, and two
+more appear: `generation()` (the pinned snapshot number) and `refresh()` (adopt
+the writer's latest checkpoint, returning whether a newer one existed).
+
+`close()` releases the file and its lock; every verb afterwards throws, and
+calling it twice is a no-op.
+
+### Bringing your own embedding
+
+`remember`, `revise`, `rememberMany` and `recall` all take an optional `vector`
+whose length must equal the configured `dim`. Given one, it **replaces** the
+embedder for that call — nothing is sent to the provider:
+
+```typescript
+const own = await myEmbedder(text);
+await db.remember({ text, vector: own });
+const res = await db.recall({ query: text, vector: own });
+```
+
+Use it for vectors you already have, for a model that is not an OpenAI-shaped
+HTTP endpoint, or for a deterministic test with no network.
+
+### Backing up: facts are only half of it
+
+`export`/`exportPage` dump facts. An **edge** is a statement between two
+entities — `kim -works_on-> plugmem` — and belongs to no single fact, so a dump
+of facts alone loses the graph. `exportEdges` is the other half.
+
+It streams: the walk runs on a worker and hands your callback one batch at a
+time, so memory stays flat whether the graph has ten edges or ten million. When
+a callback is slower than the walk, the *worker* waits — never the event loop.
+
+```javascript
+const edges = [];
+const count = await db.exportEdges((batch) => edges.push(...batch));
+```
+
+`count` is `2` here, and `edges` is complete the moment the promise resolves —
+no extra tick needed:
+
+```json
+[
+  { "src": "kim", "rel": "works_on", "dst": "plugmem", "provenance": 0 },
+  { "src": "kim", "rel": "reports_to", "dst": "ann" }
+]
 ```
 
-With an `[embedder]`, a text-only `remember`/`recall` **auto-embeds** — the
-provider's HTTP call runs outside the engine lock. Without one, there is no
-embedder and vector recall is skipped (lexical, tag, graph and time recall still
-answer). The optional `dim` open option sets the embedding size when there is no
-config; if the config configured an embedder, its dimension governs and `dim`
-must agree. A `{ readOnly: true }` handle cannot auto-embed inside the engine —
-embedding into a zero-copy mapping is what read-only exists to avoid — so this
-binding embeds the query itself before the read, exactly as the CLI and the MCP
-server do. A text `recall` therefore reaches the vector source in both modes.
-
-## The verbs
-
-Every method here is the identically-named `plugmem-host` `Database` verb; the
-engine logic is entirely the host's.
-
-**Writer** (default): `remember`, `rememberMany`, `recall`, `revise(id, args)`,
-`forget(id)`, `link`, `unlink`, `get(id)`, `tagsOf(id)`, `stats`, `export`,
-`exportPage(cursor?)`, `verify`, and the async maintenance verbs below.
-**Read-only** (`{ readOnly: true }`, observing another process's writer):
-`recall`, `get`, `tagsOf`, `stats`, `export`, `exportPage(cursor?)`, `verify`,
-plus `generation()` (the pinned snapshot generation) and `refresh()` (advance
-to the writer's latest checkpoint); the write verbs throw.
-**Both**: `path()` — the file the handle resolved to, which is the only way to
-learn it when the constructor was given no path.
-
-### Errors
+`provenance` is the fact the edge follows from, when it was recorded with one.
+It is **absent** rather than zero when there is none, so it can never be
+mistaken for fact `0` — as the second edge above shows.
+
+### Checking a file has not rotted
+
+`verify()` and `scrub()` ask different questions, and neither replaces the other:
+
+- **`verify()`** — does the *content* agree with itself? Text is valid UTF-8,
+  each vector belongs to its fact, both directions of every edge match.
+- **`scrub()`** — are the *bytes* the ones that were written? It recomputes each
+  section's checksum and the whole-file hash. This is what catches a flipped bit
+  that the structure happily accepts.
+
+A scrub is paced by you rather than run in one go, so it stays affordable on a
+live database — the model ZFS uses. Each step checks up to a budget's worth of
+bytes and returns:
+
+```javascript
+const scrub = await db.scrub();          // default budget: 1 MiB per step
+let step;
+while ((step = await scrub.next()) !== null) {
+  // step.doneBytes of step.totalBytes — progress through the snapshot file
+}
+```
+
+`next()` returns a promise because a step reads from disk, not because hashing
+is slow: over a memory-mapped file the bytes are paged in as they are read, so a
+step is I/O of whatever length your storage takes. On the JS thread that would
+freeze the process.
+
+Two things to know. **Holding the object holds a lock** on the snapshot
+generation it is scanning, so run it to completion or `close()` it. And it is
+one-shot: after it returns `null`, or throws, `active()` is `false` and you ask
+the database for another.
+
+```javascript
+const partial = await db.scrub({ budget: 16 * 1024 });
+await partial.next();     // { doneBytes: 16384, totalBytes: <the file's size> }
+partial.close();          // released; further next() calls return null
+```
+
+Damage rejects with `PLUGMEM_ENGINE` naming what failed its checksum.
+
+### Repairing a damaged file
+
+`recover` is a module function, not a method: it works on **paths**, and takes
+the source's exclusive lock, so close your handle first.
+
+```javascript
+import { recover } from "plugmem";
+
+const report = await recover("memory.plugmem", "repaired.plugmem");
+// { kept: 1, droppedText: 0, droppedVector: 0, droppedMetadata: 0 }
+```
+
+**The source is never written.** It stays exactly as it was, as evidence; this
+produces a repaired copy beside it, and swapping them is your decision. `dst`
+must therefore be a different path — passing the same one throws.
+
+The three `dropped` counts are the damage: each is a fact the source could not
+produce intact. All zero means the image was content-clean and this was a
+compaction. Memory stays proportional to the record count rather than the file,
+so a database far larger than RAM can be recovered.
+
+It handles **content** damage — the kind `verify()` reports. A snapshot whose
+container will not parse at all is not salvageable here; that is what a backup
+is for.
+
+### The one thing the Rust library has and this does not
+
+`import`. The JSONL dump format is defined by
+[`plugmem-cli`](https://docs.rs/plugmem-cli/latest), not by the engine — there is
+no `import` verb to mirror. A Node program holding records already has
+`rememberMany` and `link`, which is what an importer is made of.
+
+## Errors
 
 Every failure plugmem itself decides carries a stable `code`, so a program
 branches on it instead of on wording:
@@ -149,153 +364,269 @@ try {
 `PLUGMEM_INVALID_NAME` from an argument that was refused; `PLUGMEM_CLOSED`,
 `PLUGMEM_READ_ONLY`, `PLUGMEM_WRITER_ONLY` and `PLUGMEM_BUSY` from calling a
 verb the handle cannot serve; `PLUGMEM_ENGINE` from the engine itself, carrying
-the host's own message.
+its own message.
 
 The code is there whether the verb threw or the promise rejected — the two are
 the same contract, so nothing has to be handled twice.
 
-An argument that shapes an answer is refused rather than dropped: `range` must
-be exactly `[from, to]`, and `range`, `asOf` and `validFrom` must each be a
-finite, non-negative instant. Silently ignoring one produced an answer computed
-without it — indistinguishable from a correct one.
+An argument that would shape an answer is refused rather than dropped: `range`
+must be exactly `[from, to]`, and `range`, `asOf` and `validFrom` must each be a
+finite, non-negative instant. Silently ignoring one produces an answer computed
+without it, indistinguishable from a correct one.
 
-### What the host has and this does not
+## Configuration and embeddings
 
-The list above is the whole supported `Plugmem` surface. The only host
-operation intentionally kept out of this boundary is path-level recovery:
+Settings resolve from an explicit `config` path, then `$PLUGMEM_CONFIG`, then
+the platform config directory, then defaults. The database path resolves from an
+explicit argument, then `$PLUGMEM_DB`, then `[database].path`, then the platform
+data directory.
 
-| host verb | boundary note |
-|---|---|
-| `recover` | salvaging a damaged file is a path-level operation on the disk the process is running on — [`plugmem-cli recover`](https://docs.rs/plugmem-cli/latest)'s job, like `import` and `scrub`. |
-| `remember_many` | Exposed as async `rememberMany(items)`. It writes a batch with one embedding round-trip and resolves with outcomes in input order. |
-| `export_each` | Exposed as pull-based `exportPage(cursor?)`. Each Promise returns at most 128 facts and releases the native read lock before JS processes them; this gives Node backpressure without a cross-thread callback. |
-| `tags_of` | Exposed as synchronous `tagsOf(id)`, returning one fact's tags or an empty array. |
+```typescript
+const db = await Plugmem.open(undefined, { config: "./plugmem.toml" });
+```
+
+```toml
+# plugmem.toml
+[database]
+path = "/path/to/memory.plugmem"
 
-**No `import` verb** either — bulk-loading a `backup.jsonl` reads a file on disk,
-which is the CLI's job. A Node host can use `rememberMany` for bounded batches
-when it already owns the input records.
+[engine]
+dim = 768                     # embedding size (0 = vectors off)
 
-## Many memories in one directory (optional)
+[recall]                      # optional — every key has a tuned default
+w_vec = 2.0                   # trust meaning over keywords in this memory
+half_life_days = 30           # and treat anything older than a month as stale
 
-**Default: one memory, one file.** `Plugmem.open(path)` and nothing here applies.
+[embedder]                    # optional — omit for lexical/tag/graph/time only
+kind  = "ollama"              # or openai / lmstudio / vllm / llamacpp
+url   = "http://localhost:11434/v1/embeddings"
+model = "nomic-embed-text"
 
-A process that serves many independent memories — one per conversation, per
-tenant, per project — can point at a directory and address them by name:
+[maintenance]
+fsync = "each_op"             # or "on_snapshot": faster, loses the journal tail on an OS crash
+```
 
-```ts
-import { Workspace, type DbEntry } from "plugmem";
+`[engine]` is what a database is *built* with; changing one of those on an
+existing file is refused. `[recall]` and `[index]` are the opposite — reopening
+with different weights is how you change the ranking, so tune them freely. All
+of them are in the [full settings reference](https://github.com/m62624/plugmem/blob/main/crates/plugmem-host/SETTINGS.md).
 
-const ws = new Workspace("/srv/memories", { maxOpen: 16, idleTimeoutMs: 60_000 });
+### When a key is misspelled
 
-// `open` hands back the same `Plugmem` class, so a named memory has exactly the
-// verbs a path-opened one has. A first write to an unused name creates it.
-await (await ws.open("chat-42")).remember({ text: "prefers tokio" });
+Unknown keys and sections do not stop anything, but they are not swallowed
+either — a misspelled `w_vec` changes no behaviour, and silence would leave you
+believing you had tuned something. **Read them once after opening**, because a
+native addon has nowhere sensible to print:
 
-// Do not know the name? Ask what each memory is for. Owners are searchable too,
-// even though an owner is a graph edge rather than text.
-await ws.describe("chat-42", { description: "release planning", owner: "ann" });
-const hits: DbEntry[] = await ws.find("release planning"); // → [{ db: "chat-42", … }]
+```javascript
+const db = await Plugmem.open("agent.plugmem", { config: "./plugmem.toml" });
+for (const warning of db.configWarnings()) console.warn(warning);
+// unknown setting [recall].w_vector — did you mean `w_vec`?
 ```
 
-A name is `[a-z0-9][a-z0-9_-]*` and **cannot represent a path**, so it resolves
-to exactly one file inside the directory — traversal is not filtered out, it is
-unconstructible. `open(name, false)` refuses a name that does not exist yet,
-which is what a read should do so a typo is diagnosed rather than answered with
-an empty result.
+With an `[embedder]`, a text-only `remember`/`recall` embeds automatically, and
+the provider's HTTP call happens outside the engine lock. The `dim` open option
+sets the embedding size when there is no config; if the config built an
+embedder, its dimension governs and `dim` must agree.
+
+A read-only handle cannot embed inside the engine — writing into a zero-copy
+mapping is exactly what read-only exists to avoid — so this binding embeds the
+query itself before the read. A text `recall` reaches the vector source in both
+modes.
+
+The [full settings reference](https://github.com/m62624/plugmem/blob/main/crates/plugmem-host/SETTINGS.md)
+lists every field and the OS-specific paths.
+
+## Async and the event loop
 
-The pool bounds how many stay open; `closeIdle()` releases the rest. Call it on
-a timer: an open memory holds the file's **exclusive lock**, so a long-running
-process that never let go would make its memories unreachable from anything else
-on the machine. That is what the idle timeout is for — liveness, not memory.
+Node runs all JavaScript on one thread, so a native call that waits on an
+embedder's HTTP round trip or an fsync would freeze every timer, socket and
+callback in the process. Anything that can do that runs on a libuv worker and
+returns a promise instead.
 
-Two things to know before building on it. Memories are **independent**: nothing
-searches across them and no entity links between them, so a fact filed in the
-wrong one is unreachable from the other rather than merely misplaced. And **who
-may reach which memory is not this package's responsibility** — the name comes
-from your code, so put the policy there.
+Promises: `Plugmem.open`, `remember`, `rememberMany`, `revise`, `recall`,
+`forget`, `link`, `unlink`, `export`, `exportPage`, `verify`, `maintain`,
+`checkpoint`, and every `Workspace` verb except `closeIdle`, `openCount` and
+`close`.
 
-Every `Workspace` verb that touches a database returns a promise — `open`,
-`list`, `entries`, `find`, `describe`, `archive`, `reindex`, `verify` — because
-the registry is itself a plugmem memory and a named memory is a real file being
-opened. `closeIdle()` and `openCount()` stay synchronous.
+Synchronous: `path`, `get`, `stats`, `tagsOf`, `generation`, `refresh`, `close`.
+These touch mapped memory and return in microseconds, where a promise would be
+pure ceremony.
 
-`reindex()` and `verify()` return promises: they open and read every memory in
-the directory, which is not work for the main thread.
+Arguments are still checked on your thread: a refused one **throws** at the call
+site rather than rejecting later, so a mistake in your code and a failure in the
+engine never arrive the same way.
 
-## Async and concurrency
+### Two costs a promise does not hide
 
-Operations with unbounded storage or batch work use napi-rs `AsyncTask`: they
-return a **`Promise`** and run on Node's **libuv** worker pool, keeping the event
-loop available for application code. This includes `rememberMany`,
-`exportPage`, `maintain`, `checkpoint`, `reindex` and `verify`.
+**The worker pool is shared, and it has four threads by default.** libuv runs
+`fs`, `dns.lookup`, `zlib` and `crypto.pbkdf2` on the same pool this addon uses.
+The event loop stays free either way, but four concurrent plugmem tasks fill the
+default pool and everything else queues behind them. Measured on one machine, a
+4 MiB `fs.readFile` in the same process:
 
-For a bounded export, call `exportPage()` once, process its `facts`, then pass
-`nextCursor` to the next call until it is absent:
+| | `fs.readFile` |
+|---|---|
+| idle pool | 1.7 ms |
+| 4 plugmem tasks in flight | 29 577 ms |
+| the same, `UV_THREADPOOL_SIZE=8` | 1.4 ms |
+
+plugmem's tasks are unusually long — `maintain('full')` is minutes on a large
+memory — so raise `UV_THREADPOOL_SIZE` if the process does anything else with
+libuv while maintenance runs.
+
+The pool is also the ceiling on **concurrent embedding**. With an `[embedder]`
+configured, each `remember`/`recall` occupies one worker for its HTTP round
+trip, so at the default four, four is as parallel as it gets. Against a mock
+provider with a fixed 100 ms latency, 16 concurrent recalls took 404 ms on the
+default pool and 101 ms at `UV_THREADPOOL_SIZE=16` — the same 16 requests, four
+waves or one. If a process issues many concurrent recalls against a remote
+provider, size the pool for that, not for the CPU.
+
+**`export()` builds its whole result on your thread.** The scan is on a worker,
+but every fact becomes a JavaScript object during the promise's resolution, and
+that part is main-thread work by definition. On 100 000 facts it holds the
+thread for about 244 ms of the call's 289 ms. `exportPage()` over the same
+memory holds it for **0 ms**, in 128-fact pages:
 
 ```ts
 let cursor: number | undefined;
 do {
   const page = await db.exportPage(cursor);
-  for (const fact of page.facts) {
-    await destination.write(fact);
-  }
+  for (const fact of page.facts) await destination.write(fact);
   cursor = page.nextCursor;
 } while (cursor !== undefined);
 ```
 
-The Promise is the completion boundary for that page: no callback remains
-queued, and no database lock is held while the loop body runs. Each page has at
-most 128 facts. A read-only handle pages one immutable checkpoint; when paging a
-writer for a snapshot-style backup, do not mutate it between calls.
+Each promise owns exactly one page and resolves only after its native scan
+completed; no database lock is held while your loop body runs. A writer may
+change between pages, so do not mutate it during a snapshot-style dump — a
+read-only handle pages one immutable checkpoint and is stable.
 
-`rememberMany(items)` performs one batch embedding pass and one journal sync,
-then resolves with outcomes in input order. A maintenance call may also return
-a no-op report when there is nothing to purge, reindex or optimize.
+### Concurrency
 
-`maintain(mode?)` takes `"auto"` (the default), `"compact"`, `"reindex-text"`,
-`"optimize-vectors"` or `"full"`. No mode ever drops a fact revision or an edge
-version; the heavier ones buy bytes and index freshness. `"full"` is the only
-one that repacks the edge arenas, which a relink-heavy workload fragments.
+A `Plugmem` handle is safe to use from anywhere in your process. Reads run
+concurrently; writes serialize behind the engine's lock for the microseconds
+they take. A second *process* opening the same file for writing is refused with
+`PLUGMEM_LOCKED` rather than corrupting it, while any number of read-only
+handles map the same file at once — a writer and its readers coexist across
+processes, sharing the OS page cache.
 
-### What is async, and why
+## Many memories in one directory
 
-`remember`, `revise`, `recall`, `rememberMany`, `exportPage`, `maintain` and
-`checkpoint` return promises. Everything else — `get`, `stats`, `tagsOf`,
-`forget`, `link`, `unlink`, `verify`, `export`, `path`, `generation`,
-`refresh` — is synchronous.
+**Default: one logical memory backed by a local database layout.** `Plugmem.open(path)` and nothing here
+applies.
 
-The line is drawn at blocking work. Node runs all JavaScript on **one** thread,
-so a native call that waits on an embedder's HTTP round trip or on an fsync
-freezes every timer, socket and callback in the process for as long as it takes.
-The verbs above can do exactly that — with an `[embedder]` configured,
-`remember` and a text `recall` each cost a request to the provider — so they run
-on a libuv worker and hand JavaScript a promise. The rest touch only mapped
-memory and return in microseconds, where a promise would be pure ceremony.
+The problem this solves: a process serving many conversations, tenants or
+projects wants each to have its **own** memory — nothing from one surfacing in
+another — without managing a pile of file paths by hand. Give a name, get a
+memory:
 
-Arguments are still checked on your thread: a refused one **throws** at the call
-site rather than rejecting later, so a mistake in your code and a failure in the
-engine never arrive the same way.
+```ts
+import { Workspace, type DbEntry } from "plugmem";
 
-### Bringing your own embedding
+const ws = new Workspace("/srv/memories");
 
-`remember`, `revise`, `rememberMany` and `recall` all take an optional
-`vector` — a precomputed embedding whose length must equal the configured `dim`:
+// The same `Plugmem` class comes back, so a named memory has exactly the verbs
+// a path-opened one has. A first write to an unused name creates it.
+const chat = await ws.open("chat-42");
+await chat.remember({ text: "prefers tokio" });
 
-```typescript
-const own = await myEmbedder(text);          // your model, your pipeline
-await db.remember({ text, vector: own });    // nothing is sent to `[embedder]`
-const res = await db.recall({ query: text, vector: own });
+// Another name is another memory. They cannot see each other.
+const other = await ws.open("chat-99");
+(await other.recall({ query: "tokio" })).facts.length;   // 0
+```
+
+Memories are **independent by design**: nothing searches across them and no
+entity links between them. A fact filed under the wrong name is not merely
+misplaced, it is unreachable from the other memory.
+
+If you do not know the name, ask what each memory is for. Descriptions are
+searchable, and so are owners, even though an owner is stored as a graph edge
+rather than as text:
+
+```ts
+await ws.describe("chat-42", { description: "release planning", owner: "ann" });
+
+const hits: DbEntry[] = await ws.find("release planning");  // → [{ db: "chat-42", … }]
+const byOwner: DbEntry[] = await ws.find("ann");            // → the same memory
 ```
 
-Given one, it **replaces** the embedder for that call — the engine embeds only
-when the field is absent. Use it for vectors you already have, for a model that
-is not an OpenAI-shaped HTTP endpoint, or for a deterministic test with no
-network. The CLI (`--vector`) and the MCP tools (`vector`) take the same thing.
+A name is `[a-z0-9][a-z0-9_-]*` and **cannot express a path**, so it resolves to
+exactly one named database inside the directory — traversal is not filtered out, it is
+unconstructible. `ws.open(name, false)` refuses a name that does not exist yet,
+which is what a read should do so a typo is diagnosed rather than answered with
+an empty result.
+
+**Who may reach which memory is not this package's job.** The name comes from
+your code, so the policy belongs there.
+
+### Running it
+
+| Method | Does |
+|---|---|
+| `open(name, create?)` | open (default: create if missing) and hand back a `Plugmem` |
+| `list()` | every memory in the directory, from the filesystem — including undescribed ones |
+| `entries()` | every described memory, from the registry |
+| `find(query, k?)` | memories whose description or owner best matches |
+| `describe(name, args)` | record what a memory is for; revises rather than duplicating |
+| `archive(name)` | label it archived, keeping its description. Nothing is moved or deleted |
+| `reindex()` | rebuild the registry from the memories' own descriptions |
+| `verify()` | report disagreements between registry and directory; repairs nothing |
+| `closeIdle()` | close memories unused past the idle timeout (sync) |
+| `openCount()` | how many are open right now (sync) |
+| `close()` | close every pooled memory and the registry |
+
+`closeIdle()` matters more than it looks. An open memory holds its file's
+exclusive lock, so a long-running process that never lets go makes its memories
+unreachable from anything else on the machine. Call it on a timer — that is what
+the idle timeout is for, liveness rather than memory. The pool bounds how many
+stay open at once (`maxOpen`, default 16, least-recently-used closed to make
+room):
+
+```ts
+const ws = new Workspace("/srv/memories", { maxOpen: 16, idleTimeoutMs: 60_000 });
+setInterval(() => ws.closeIdle(), 30_000);
+```
+
+A `Plugmem` handed out by `open()` is **not** closed by `ws.close()`: it is its
+own handle holding its own lock until you close it or it is garbage collected.
+
+`verify()` reports and never repairs, because a workspace is a directory a
+person can edit, and guessing at their intent is how a consistency check loses
+data.
+
+## What it is not for
+
+plugmem is for local-first application and agent memory: one process, one local database,
+no service to operate. Its design centre is around 100 000 active facts on one machine, and
+the benchmarks track 1M-operation profiles to show how the same engine behaves
+under heavier local load.
+
+It is **not** a vector database and not built for multi-million vector
+workloads, cluster sharding, multi-tenant serving or managed nearest-neighbour
+search. For those, use a dedicated system — [Qdrant](https://qdrant.tech),
+[Milvus](https://milvus.io), [Weaviate](https://weaviate.io),
+[Pinecone](https://www.pinecone.io) or
+[pgvector](https://github.com/pgvector/pgvector).
+
+## Other ways in
+
+The same engine ships four ways. This package is the Node one.
+
+| You are | Use |
+|---|---|
+| writing JavaScript / TypeScript for Node | **this package** |
+| writing Rust | [`plugmem-host`](https://docs.rs/plugmem-host/latest) — the engine in your process |
+| an agent, or another language | [`plugmem-mcp`](https://docs.rs/plugmem-mcp/latest) — a stdio JSON-RPC sidecar |
+| a person at a terminal | [`plugmem-cli`](https://docs.rs/plugmem-cli/latest) |
 
-`close()` releases the file and its lock; every verb afterwards throws, and it is
-idempotent (the handle is also released on garbage collection, but `close()`
-makes the moment explicit — e.g. before reopening the same file read-only).
+**Working with an LLM agent?** There is a companion
+[skill](https://github.com/m62624/plugmem/blob/main/skill/SKILL.md) describing
+the remember/recall loop, the contradiction workflow and the verbs. This package
+ships it: `skill()` returns the text and `skillVersion()` the version it was
+written against.
 
 ## License
 
-MIT.
+MIT. Source: <https://github.com/m62624/plugmem>

package/index.d.ts

@@ -86,6 +86,28 @@ export interface RecallArgs {
   k?: number
   /** Include closed revisions (default false). */
   closed?: boolean
+  /**
+   * Token budget of the `rendered` block (default 512). That block is what
+   * goes into a prompt, so this is the knob deciding how much of the
+   * context window a recall may spend.
+   */
+  tokenBudget?: number
+  /**
+   * HNSW beam width for the vector source (default: the configured
+   * `hnsw_ef_search`). Higher is more accurate and slower; ignored while
+   * the engine is still in the flat regime, below `flat_to_hnsw`.
+   */
+  ef?: number
+  /**
+   * How many edges the graph source may follow from an anchor entity
+   * (default: the configured `graph_depth`). `0` asks for the anchors' own
+   * facts and no neighbours.
+   *
+   * Per call for the same reason `k` and `tokenBudget` are: how wide a net
+   * to cast belongs to the question. "What is known around this person"
+   * wants more hops than "what is this person's stated preference".
+   */
+  graphDepth?: number
   /**
    * A precomputed embedding. Its length must equal the configured `dim`.
    *
@@ -104,6 +126,59 @@ export interface LinkArgs {
   rel: string
   /** Destination entity name. */
   dst: string
+  /**
+   * The fact this edge follows from, recorded on the edge and returned by
+   * graph recall — the answer to "why is this edge here". Ignored by
+   * `unlink`, which closes an edge rather than opening one.
+   */
+  provenance?: number
+}
+/** Options for [`recover`]. */
+export interface RecoverOptions {
+  /**
+   * Embedding dimension, as `OpenOptions.dim`. It must match what the source
+   * database stores, so a memory with vectors needs this (or a `config`
+   * naming the embedder) or the salvage cannot open it.
+   */
+  dim?: number
+  /** Path to a `config.toml`; the standard discovery applies when omitted. */
+  config?: string
+}
+/**
+ * Salvages a content-corrupt memory: reads `src`, drops the facts that fail
+ * the content checks, and writes a clean, compacted image to `dst`.
+ *
+ * **`src` is never written.** The damaged file stays exactly as it was, as
+ * evidence — this produces a repaired copy beside it, and swapping them is
+ * your decision, not this function's. `dst` must therefore be a different
+ * path.
+ *
+ * **It handles *content* damage**, the kind `verify` reports: text that is not
+ * valid UTF-8, a vector slot that disagrees with its fact, metadata that will
+ * not decode. *Structural* damage — a snapshot whose container will not parse
+ * at all — is not salvageable here and rejects; that is what a backup is for.
+ *
+ * Memory stays proportional to the record count rather than the image: the
+ * two large pools are streamed through temp files, so a database far bigger
+ * than RAM can be recovered as long as its graph fits.
+ *
+ * **Async**: it opens, sweeps and rewrites a whole database.
+ *
+ * @throws `PLUGMEM_LOCKED` if either path is open elsewhere; `PLUGMEM_ENGINE`
+ * if `dst` resolves to the same file as `src`, or the source will not parse;
+ * `PLUGMEM_OPEN` for an IO failure on either path.
+ */
+export declare function recover(src: string, dst: string, options?: RecoverOptions | undefined | null): Promise<RecoverReport>
+/** Options for `Plugmem#scrub`. */
+export interface ScrubOptions {
+  /**
+   * Bytes to hash per step, at most. Default: the engine's own (1 MiB).
+   *
+   * This is the knob trading responsiveness for throughput: smaller steps
+   * return to JavaScript more often, larger ones spend less time crossing
+   * back and forth. It changes no answer, only the grain.
+   */
+  budget?: number
 }
 /** One similar / potentially-conflicting live fact surfaced by `remember`. */
 export interface Similar {
@@ -226,6 +301,12 @@ export interface FactSnapshot {
 }
 /** One exported fact — the id-free, import-ready shape. */
 export interface ExportedFact {
+  /**
+   * The fact's id in the database it came from. Informational: an import
+   * assigns fresh ids. Present because edges name their provenance fact by
+   * id, so a dump carrying edges needs something for them to point at.
+   */
+  id: number
   /** The fact text. */
   text: string
   /** Subject entity name, if any. */
@@ -239,6 +320,52 @@ export interface ExportedFact {
   /** Validity start (unix ms; preserved on import). */
   validFrom: number
 }
+/**
+ * One exported edge — the shape `exportEdges` streams, and the same fields the
+ * CLI's JSONL dump writes for an edge.
+ *
+ * Edges are not part of a fact's dump: a fact names its tags and metadata, but
+ * an edge is a statement *between* two entities and outlives any single fact.
+ * That is why a complete backup is the two streams together.
+ */
+export interface ExportedEdge {
+  /** Source entity name. */
+  src: string
+  /** The relation, verbatim. */
+  rel: string
+  /** Destination entity name. */
+  dst: string
+  /**
+   * The fact this edge follows from, if it was recorded with one. Absent
+   * rather than a sentinel, so "no provenance" cannot be mistaken for fact 0.
+   */
+  provenance?: number
+}
+/**
+ * What a `recover` salvaged, and what it had to leave behind.
+ *
+ * The three `dropped` counts are the damage: each is a fact the source could
+ * not produce intact, so a non-zero total means the recovered copy is smaller
+ * than the original claimed to be. Zeroes across the board mean the image was
+ * content-clean and this was a compaction.
+ */
+export interface RecoverReport {
+  /** Facts written to the destination — the survivors. */
+  kept: number
+  /** Dropped: the stored text was not valid UTF-8. */
+  droppedText: number
+  /** Dropped: the vector slot was out of range or disagreed with the fact. */
+  droppedVector: number
+  /** Dropped: the metadata blob did not decode to a well-formed map. */
+  droppedMetadata: number
+}
+/** How far a `Scrub` has got. */
+export interface ScrubProgress {
+  /** Bytes checksummed so far; equals `totalBytes` on the last step. */
+  doneBytes: number
+  /** The generation file's length — the total to checksum. */
+  totalBytes: number
+}
 /** One bounded page returned by `exportPage`. */
 export interface ExportPage {
   /** Open facts in fact-id order; never longer than the native page bound. */
@@ -474,6 +601,18 @@ export declare class Plugmem {
    * snapshot (`PLUGMEM_NEEDS_CHECKPOINT`), or on an IO error.
    */
   static open(path?: string | undefined | null, options?: OpenOptions | undefined | null): Promise<Plugmem>
+  /**
+   * What `config.toml` said that nothing claimed — a misspelled key, a
+   * misspelled section — one human-readable line each, empty when the file
+   * was clean.
+   *
+   * It is a value rather than a printed warning because a native addon has
+   * nowhere sensible to print: stderr belongs to the host application, which
+   * may be a server that logs as JSON. **Read it once after opening and log
+   * it your own way** — ignoring it puts you back where a typo silently
+   * changes nothing.
+   */
+  configWarnings(): Array<string>
   /**
    * The file this memory is open on.
    *
@@ -549,10 +688,14 @@ export declare class Plugmem {
   /**
    * Every currently-open fact, as one array (id-free, import-ready).
    *
-   * **Async, but still unbounded**: the scan is off the JS thread, yet the
-   * whole memory is materialized into a single array before it resolves, so
-   * the peak memory is the whole export. `exportPage` is the same data in
-   * bounded pages — prefer it for anything but a small memory or a script.
+   * **Async, but still unbounded, in two ways.** The scan runs on a worker,
+   * yet the whole memory is materialized into a single array before it
+   * resolves, so peak memory is the whole export. And `resolve` runs on the
+   * JS thread by definition, so building one JavaScript object per fact
+   * stalls it: measured at ~244 ms of a 289 ms call over 100 000 facts,
+   * against 0 ms for the same data through `exportPage`. A promise hides
+   * neither cost. Prefer `exportPage` for anything but a small memory or a
+   * script.
    */
   export(): Promise<ExportedFact[]>
   /**
@@ -566,6 +709,50 @@ export declare class Plugmem {
    * mutate it during a snapshot-style backup; a read-only handle is stable.
    */
   exportPage(cursor?: number | undefined | null): Promise<ExportPage>
+  /**
+   * Streams every current edge to `onBatch`, in batches, and resolves with
+   * the number streamed.
+   *
+   * **The other half of a backup.** `export`/`exportPage` dump facts; an edge
+   * is a statement between two entities and belongs to no single fact, so a
+   * dump of facts alone silently loses the graph.
+   *
+   * **Async and bounded.** The walk runs on a libuv worker; batches reach
+   * `onBatch` on the JS thread through a threadsafe function with a queue of
+   * four. When the callback is slower than the walk, the *worker* waits — the
+   * event loop never does, and peak memory is four batches whatever the
+   * database's size.
+   *
+   * **When the promise resolves, every batch has been delivered.** Worth
+   * saying because a threadsafe-function call only queues work for the JS
+   * thread, so the natural implementation resolves early and hands you a
+   * half-filled accumulator on some runs and a full one on others. Each
+   * batch is acknowledged from the JS thread and the worker waits for the
+   * receipts, so reading your results straight after the `await` is correct.
+   *
+   * `onBatch` throwing is not caught here: it surfaces as an uncaught error,
+   * as it would from any callback Node invokes on your behalf.
+   */
+  exportEdges(onBatch: (edges: ExportedEdge[]) => void): Promise<number>
+  /**
+   * Starts a resumable byte-level check of the current published snapshot,
+   * and resolves with the [`Scrub`](crate::scrub::Scrub) that paces it.
+   *
+   * The counterpart to `verify`, not a replacement: `verify` asks whether
+   * the *content* agrees with itself, this asks whether the *bytes* are the
+   * ones that were written. Only the second catches a flipped bit that the
+   * structure accepts.
+   *
+   * Available on a writer as well as a read-only handle: a scrub reads the
+   * published generation from disk and has no opinion about which handle
+   * asked. It does need something published — checkpoint once first.
+   *
+   * **The returned object holds a shared lock** on the generation it scans
+   * for as long as it lives, so run it to completion or `close()` it.
+   *
+   * @throws `PLUGMEM_NEEDS_CHECKPOINT` when nothing has been published yet.
+   */
+  scrub(options?: ScrubOptions | undefined | null): Promise<Scrub>
   /** One fact's tags, or an empty array for an unknown or tombstoned id. */
   tagsOf(id: number): Array<string>
   /**
@@ -610,6 +797,46 @@ export declare class Plugmem {
    */
   close(): void
 }
+/**
+ * A resumable byte-level check of one snapshot generation.
+ *
+ * **Holding this object holds a lock.** It pins the generation it is scanning
+ * with a shared lock for its whole life, so the writer's garbage collection
+ * cannot reclaim that generation under it. Finish the scan, or `close()` it —
+ * do not park one indefinitely.
+ *
+ * One-shot: once it has returned `null`, or thrown, it is done. Ask the
+ * database for another to scan again.
+ */
+export declare class Scrub {
+  /**
+   * Hashes the next slice and resolves with the progress so far, or `null`
+   * when the scan is complete.
+   *
+   * **Async**: see the module note — a step is disk I/O, not arithmetic.
+   *
+   * Concurrent calls are serialized rather than refused: the cursor has one
+   * position, so two overlapping steps would be two different slices of the
+   * same scan, which is what a caller pacing it from two places asked for.
+   *
+   * @throws on the first mismatch, naming what failed its checksum. The
+   * scrub is finished at that point; a further call resolves `null`.
+   */
+  next(): Promise<ScrubProgress | null>
+  /**
+   * Releases the pinned generation now, abandoning an unfinished scan.
+   *
+   * Idempotent, and the same bargain as `Plugmem#close`: waiting for the
+   * garbage collector to do it means the writer cannot reclaim that
+   * generation until it happens.
+   */
+  close(): void
+  /**
+   * Whether this scrub still has work — `false` once it finished, failed or
+   * was closed. Cheap: it inspects the handle, not the file.
+   */
+  active(): boolean
+}
 /**
  * A directory of named memories — the napi mirror of
  * [`plugmem_host::Workspace`].

package/index.js

@@ -310,9 +310,11 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { Plugmem, MaintainMode, Workspace, version, about, settingsHelp, skill, skillFull, skillVersion } = nativeBinding
+const { Plugmem, recover, Scrub, MaintainMode, Workspace, version, about, settingsHelp, skill, skillFull, skillVersion } = nativeBinding
 
 module.exports.Plugmem = Plugmem
+module.exports.recover = recover
+module.exports.Scrub = Scrub
 module.exports.MaintainMode = MaintainMode
 module.exports.Workspace = Workspace
 module.exports.version = version

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "plugmem",
-  "version": "0.4.0",
-  "description": "Native Node.js addon for plugmem: an embedded long-term memory engine for LLM agents (remember / recall / revise / forget over one local file).",
+  "version": "0.6.0",
+  "description": "Native Node.js addon for plugmem: an embedded bitemporal memory and retrieval engine for local-first applications and agents (remember / recall / revise / forget over one local database).",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/m62624/plugmem.git"
@@ -41,11 +41,11 @@
     "typecheck": "tsc -p tsconfig.json"
   },
   "optionalDependencies": {
-    "plugmem-linux-x64-gnu": "0.4.0",
-    "plugmem-linux-arm64-gnu": "0.4.0",
-    "plugmem-darwin-x64": "0.4.0",
-    "plugmem-darwin-arm64": "0.4.0",
-    "plugmem-win32-x64-msvc": "0.4.0",
-    "plugmem-win32-arm64-msvc": "0.4.0"
+    "plugmem-linux-x64-gnu": "0.6.0",
+    "plugmem-linux-arm64-gnu": "0.6.0",
+    "plugmem-darwin-x64": "0.6.0",
+    "plugmem-darwin-arm64": "0.6.0",
+    "plugmem-win32-x64-msvc": "0.6.0",
+    "plugmem-win32-arm64-msvc": "0.6.0"
   }
 }