plugmem 0.9.0 → 0.11.0

package/README.md

@@ -185,6 +185,21 @@ duplicate or contradict**. If a preflight must not write, use
 `rememberGuarded`: the database holds one write scope across its similarity
 check and conditional insertion, so concurrent preflights cannot both pass.
 
+**`entity` is what makes the guard a guard.** The detector compares the new text
+against that entity's most recent live facts and against nothing else, so a
+`rememberGuarded` call with **no** `entity` has no candidates and always returns
+`status: "stored"` - it does not fail, it simply has nothing to compare against.
+Six identical guarded writes with no entity produce six facts; the same six with
+`entity` produce one and five `blocked`.
+
+`checked` on the result says whether a comparison happened at all: `false` is a
+fact stored exactly as `remember` would have stored it. Do not read `status:
+"stored"` as "checked and clear" without it.
+
+`similar` carries `{ id, score, reason }` - the ids, not the text. Resolve a
+hit's wording with `get(id)` when you want to show the caller what it collided
+with.
+
 ```typescript
 const decision = await db.rememberGuarded({
   text: "the user prefers async-std",
@@ -218,6 +233,7 @@ only moves arguments and results across the boundary.
 | `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 |
+| `forgetMany(ids[])` | tombstone a batch: one journal sync, one post-write pass |
 | `removeTag(tag)` | remove a tag from every current fact while preserving facts/history |
 | `link(args)` | upsert a typed edge, optionally with `provenance` |
 | `unlink(args)` | close the current edge; resolves with whether one was open |
@@ -254,6 +270,23 @@ of mixing incompatible vectors. `reembed` is the deliberate transition; it
 runs on a libuv worker, leaves the JavaScript event loop responsive, keeps reads
 live and makes concurrent writes reject with `PLUGMEM_BUSY`.
 
+A mismatch does **not** stop the database opening, on a writer or a read-only
+handle, and loses nothing. What fails is exactly two things: `recall` with a
+`query` and `remember` with `text`. Everything else - `stats`, `get`, `tagsOf`,
+`listTags`, entity/graph recall, `exportPage`, `forget`, `link`, `verify`,
+`maintain`, `checkpoint`, `reembed` - keeps answering. So the content is safe
+and recovery is always available, and a consumer only finds out at its first
+lookup after the change: detect it by making the cheapest text recall and
+watching for the error, rather than from a note of what was configured last
+time.
+
+`reembed` is idempotent; it rebuilds ONE database, so a workspace needs a pass
+over every memory in it. On an EMPTY database it still makes one request whose
+input is the empty string - a provider that rejects empty input fails a rebuild
+that had nothing to rebuild. And switching an embedder on over a database built
+without one breaks nothing and warns about nothing: compare `stats().vectors`
+with `stats().facts` to notice the facts that have no vectors yet.
+
 **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
@@ -489,7 +522,7 @@ callback in the process. Anything that can do that runs on a libuv worker and
 returns a promise instead.
 
 Promises: `Plugmem.open`, `remember`, `rememberGuarded`, `rememberMany`, `revise`, `recall`,
-`forget`, `removeTag`, `listTags`, `link`, `unlink`, `export`, `exportPage`, `verify`, `maintain`,
+`forget`, `forgetMany`, `removeTag`, `listTags`, `link`, `unlink`, `export`, `exportPage`, `verify`, `maintain`,
 `checkpoint`, every database verb on `WorkspaceMemory`, and every registry
 verb on `Workspace`.
 

package/index.d.ts

@@ -218,6 +218,16 @@ export interface GuardedRememberOutcome {
   status: 'stored' | 'blocked'
   outcome?: RememberOutcome
   similar: Array<Similar>
+  /**
+   * Whether the similarity detector had anything to compare against.
+   *
+   * `false` means the fact was stored WITHOUT a duplicate check: the
+   * detector is scoped to the fact's entity, so a call carrying no
+   * `entity` has no candidate set and cannot block anything, now or after
+   * any number of later writes. Always `true` on a blocked result, which
+   * by definition compared something.
+   */
+  checked: boolean
 }
 /** One recalled fact. */
 export interface RecalledFact {
@@ -721,6 +731,15 @@ export declare class Plugmem {
    * @throws synchronously in read-only mode.
    */
   forget(id: number): Promise<boolean>
+  /**
+   * Tombstones many facts at once. Equivalent to [`forget`](Plugmem::forget)
+   * on each id in order, but under **one** journal sync and **one**
+   * post-write policy pass instead of N — the same batching
+   * [`rememberMany`](Plugmem::remember_many) does for writes. Resolves with
+   * one boolean per id, in the same order, `true` when that id was live.
+   * @throws synchronously in read-only mode.
+   */
+  forgetMany(ids: Array<number>): Promise<boolean[]>
   /**
    * Upserts a typed edge `src -rel-> dst`. **Async** for the same reason as
    * [`forget`](Plugmem::forget). @throws synchronously in read-only mode.
@@ -926,6 +945,7 @@ export declare class WorkspaceMemory {
   revise(id: number, args: RememberArgs): Promise<RememberOutcome>
   recall(args?: RecallArgs | undefined | null): Promise<RecallResult>
   forget(id: number): Promise<boolean>
+  forgetMany(ids: Array<number>): Promise<boolean[]>
   link(args: LinkArgs): Promise<void>
   unlink(args: LinkArgs): Promise<boolean>
   get(id: number): Promise<FactSnapshot | null>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plugmem",
-  "version": "0.9.0",
+  "version": "0.11.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",
@@ -43,11 +43,11 @@
     "typecheck": "tsc -p tsconfig.json"
   },
   "optionalDependencies": {
-    "plugmem-linux-x64-gnu": "0.9.0",
-    "plugmem-linux-arm64-gnu": "0.9.0",
-    "plugmem-darwin-x64": "0.9.0",
-    "plugmem-darwin-arm64": "0.9.0",
-    "plugmem-win32-x64-msvc": "0.9.0",
-    "plugmem-win32-arm64-msvc": "0.9.0"
+    "plugmem-linux-x64-gnu": "0.11.0",
+    "plugmem-linux-arm64-gnu": "0.11.0",
+    "plugmem-darwin-x64": "0.11.0",
+    "plugmem-darwin-arm64": "0.11.0",
+    "plugmem-win32-x64-msvc": "0.11.0",
+    "plugmem-win32-arm64-msvc": "0.11.0"
   }
 }