plugmem 0.8.0 → 0.10.0

package/README.md

@@ -1,6 +1,6 @@
 # plugmem
 
-> ⚠️ Experimental. plugmem is mostly an AI-built experiment — written with
+> ⚠️ 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.
@@ -9,11 +9,11 @@ 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.
 
-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.
+File-backed on disk, no server, no daemon. The
+[`plugmem-host`](https://docs.rs/plugmem-host/latest) engine is compiled to a
+native addon through [napi-rs](https://napi.rs) and linked directly into the
+process, 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) ·
@@ -47,11 +47,15 @@ const res = await db.recall({ query: "tokio", k: 5 });
 console.log(res.rendered);   // paste this into the prompt
 // - [f0] user: the user prefers tokio (2026-08; active) #pref
 
+const tags = await db.listTags({ prefix: "pre", limit: 64 });
+console.log(tags.items);     // [{ name: "pref", count: 1 }]
+// await db.removeTag("pref"); // global: revises every current fact carrying it
+
 db.close();
 ```
 
-The query is `"tokio"` and not `"which runtime?"` for a reason worth knowing up
-front: with no embedder configured, recall matches on **words**, and "runtime"
+The query is `"tokio"` rather than `"which runtime?"` because recall matches on
+**words** when no embedder is configured, and "runtime"
 appears nowhere in that fact, so the more natural question returns nothing.
 Reach it through the graph instead with `entities: ["user"]`, or configure an
 [embedder](#configuration-and-embeddings) and the meaning matches too. Only one
@@ -116,16 +120,16 @@ the second query has something to answer with.
 
 `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
+people trip over: an `asOf` earlier than a fact's `recordedAt` sees nothing,
+because the memory had not recorded the fact yet. Answering with today's knowledge
 would be the wrong answer to "what did I hold".
 
 `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.
+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
+result follows directly from the two clocks; a single timestamp cannot express
+it.
 
 Two more queries over the same axes:
 
@@ -176,18 +180,45 @@ res.edges;      // { src, rel, dst, provenance }[] — what the graph walked
 res.truncated;  // true if selection stopped at k or the budget with more left
 ```
 
-`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:
+`remember` stores the new fact and returns its id **plus any live facts it may
+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 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.
+const decision = await db.rememberGuarded({
+  text: "the user prefers async-std",
+  entity: "user",
+});
+if (decision.status === "blocked") {
+  for (const s of decision.similar) {
+    // revise/forget an old fact, or use ordinary remember to keep both
+    console.log(s.id, s.score, s.reason);
+  }
 }
 ```
 
+`blocked` has no `outcome`: it allocated no id and changed neither indexes nor
+journal. Ordinary `remember` is also a safe complete write; it simply never rejects
+one. Do not use `recall` for this check. Recall returns ranked context and can
+return a weak nearest vector; its fused score is not cosine similarity or a
+conflict threshold.
+
 ## API
 
 Every method wraps the identically-named verb of the Rust `Database`; this layer
@@ -198,9 +229,11 @@ only moves arguments and results across the boundary.
 | Method | Does |
 |---|---|
 | `remember(args)` | store a fact; resolves with its id and similar facts |
+| `rememberGuarded(args)` | check similarity and store only if clear, without a check/write race |
 | `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 |
+| `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 |
 
@@ -211,6 +244,7 @@ only moves arguments and results across the boundary.
 | `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) |
+| `listTags(options?)` | bounded lexical page of current tags and counts (async) |
 | `stats()` | engine size counters (sync) |
 | `path()` | the file this handle resolved to (sync) |
 | `export()` | every open fact as one array (async, unbounded — see below) |
@@ -223,11 +257,35 @@ only moves arguments and results across the boundary.
 | Method | Does |
 |---|---|
 | `maintain(mode?)` | `"auto"` (default), `"compact"`, `"reindex-text"`, `"optimize-vectors"`, `"full"`. No mode ever drops a revision or an edge version |
+| `reembed(batchSize?)` | explicitly recompute every retained vector with the configured model and publish atomically; never invoked by `maintain('auto')` |
 | `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 |
 
+The snapshot stores the model's readable vector-space identity, not only its
+dimension. A changed model makes ordinary automatic embedding reject instead
+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
@@ -408,6 +466,7 @@ half_life_days = 30           # and treat anything older than a month as stale
 enabled = true                # false keeps settings but makes no embedder calls
 url   = "http://localhost:11434/v1/embeddings"
 model = "nomic-embed-text"
+space_id = "nomic-embed-text@v1" # optional; defaults to model
 api_key_env = "OPENAI_API_KEY" # env var holding the bearer token
 
 [maintenance]
@@ -440,7 +499,9 @@ embedder, its dimension governs and `dim` must agree.
 The host uses one `OpenAiCompatEmbedder` implementation for OpenAI, Ollama,
 LM Studio, vLLM and other OpenAI-compatible servers. `url` is the complete
 embeddings endpoint exactly as provided (nothing is appended), and `model` is
-the model name understood by that server. Set `enabled = false` to keep the
+the model name understood by that server. `space_id` optionally identifies the
+exact semantic space and defaults to `model`; it is never discovered over the
+network. Set `enabled = false` to keep the
 settings without creating or calling the embedder; `$PLUGMEM_EMBEDDER_ENABLED`
 overrides it with `true` or `false`.
 
@@ -459,14 +520,15 @@ 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.
 
-Promises: `Plugmem.open`, `remember`, `rememberMany`, `revise`, `recall`,
-`forget`, `link`, `unlink`, `export`, `exportPage`, `verify`, `maintain`,
-`checkpoint`, and every `Workspace` verb except `closeIdle`, `openCount` and
-`close`.
+Promises: `Plugmem.open`, `remember`, `rememberGuarded`, `rememberMany`, `revise`, `recall`,
+`forget`, `removeTag`, `listTags`, `link`, `unlink`, `export`, `exportPage`, `verify`, `maintain`,
+`checkpoint`, every database verb on `WorkspaceMemory`, and every registry
+verb on `Workspace`.
 
-Synchronous: `path`, `get`, `stats`, `tagsOf`, `generation`, `refresh`, `close`.
-These touch mapped memory and return in microseconds, where a promise would be
-pure ceremony.
+Synchronous: the direct handle's `path`, `get`, `stats`, `tagsOf`, `generation`,
+`refresh`, `close`; and `Workspace.memory`, `release`, `closeIdle`, `openCount`,
+`close`. Creating a logical reference touches no file. Its own database verbs
+are promises because acquiring a cold lease may open and replay a file.
 
 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
@@ -542,13 +604,13 @@ import { Workspace, type DbEntry } from "plugmem";
 
 const ws = new Workspace("/srv/memories");
 
-// 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");
+// This is only a name plus a weak reference to `ws`: no file is opened and no
+// writer lock is held until a verb runs. A first write creates the memory.
+const chat = ws.memory("chat-42");
 await chat.remember({ text: "prefers tokio" });
 
 // Another name is another memory. They cannot see each other.
-const other = await ws.open("chat-99");
+const other = ws.memory("chat-99");
 (await other.recall({ query: "tokio" })).facts.length;   // 0
 ```
 
@@ -568,10 +630,10 @@ const byOwner: DbEntry[] = await ws.find("ann");            // → the same memo
 ```
 
 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.
+exactly one named database inside the directory — traversal is not filtered out,
+it is unconstructible. `memory(name)` itself creates nothing. A write verb creates
+an unused name; a read verb refuses it, 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.
@@ -580,7 +642,8 @@ your code, so the policy belongs there.
 
 | Method | Does |
 |---|---|
-| `open(name, create?)` | open (default: create if missing) and hand back a `Plugmem` |
+| `memory(name)` | return a lock-free logical `WorkspaceMemory` reference |
+| `release(name)` | evict one inactive pooled handle; references remain valid |
 | `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 |
@@ -592,20 +655,47 @@ your code, so the policy belongs there.
 | `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
+`closeIdle()` matters more than it looks. A pooled database 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):
+the idle timeout is for, liveness rather than memory. The pool is a hard bound on
+open databases (`maxOpen`, default 16): an inactive least-recently-used entry is
+closed to make room. If every slot belongs to an active verb, a different memory
+gets `PLUGMEM_BUSY` immediately instead of waiting or opening a hidden extra
+handle:
 
 ```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.
+Each `WorkspaceMemory` verb takes a scoped lease. While it runs, `release`,
+`closeIdle` and LRU eviction cannot take that entry; after it returns, the entry
+is eligible immediately. `ws.close()` invalidates every logical reference.
+Garbage collection of a `WorkspaceMemory` neither opens nor closes anything.
+
+This lifecycle applies only to workspaces. A direct `Plugmem.open(path)` still
+returns an explicitly owned native handle, and `close()` remains how its writer
+lock is released.
+
+### Migration from the handle-returning workspace API
+
+This is a breaking ownership change:
+
+```ts
+// before: a second native owner whose lifetime depended on JavaScript GC
+const memory = await ws.open("chat-42");
+memory.close();
+
+// now: a stable logical reference; each verb owns one scoped lease
+const memory = ws.memory("chat-42");
+ws.release("chat-42"); // optional: release an inactive pooled lock now
+```
+
+There is no `WorkspaceMemory.close()`: it owns nothing to close. Database reads
+such as `get`, `stats` and `tagsOf` are promises on this class because a cold
+call may have to reopen and replay the file. The same methods on a direct
+`Plugmem` remain synchronous.
 
 `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
@@ -627,7 +717,7 @@ search. For those, use a dedicated system — [Qdrant](https://qdrant.tech),
 
 ## Other ways in
 
-The same engine ships five ways. This package is the Node one.
+plugmem also ships interfaces for Rust, Python, agents and the terminal.
 
 | You are | Use |
 |---|---|
@@ -638,7 +728,7 @@ The same engine ships five ways. This package is the Node one.
 | a person at a terminal | [`plugmem-cli`](https://docs.rs/plugmem-cli/latest) |
 
 **Working with an LLM agent?** There is a companion
-[skill](https://github.com/m62624/plugmem/blob/main/skill/SKILL.md) describing
+[skill](https://github.com/m62624/plugmem/blob/main/skills/plugmem/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.

package/index.d.ts

@@ -133,6 +133,15 @@ export interface LinkArgs {
    */
   provenance?: number
 }
+/** Bounded tag-catalog options. Omitted fields select the first 64 entries. */
+export interface TagListOptions {
+  /** Exact, case-sensitive prefix. */
+  prefix?: string
+  /** Opaque cursor returned by the previous page. */
+  cursor?: string
+  /** Page size (maximum 256). */
+  limit?: number
+}
 /** Options for [`recover`]. */
 export interface RecoverOptions {
   /**
@@ -201,6 +210,25 @@ export interface RememberOutcome {
    */
   similar: Array<Similar>
 }
+/**
+ * Result of `rememberGuarded`. Blocked results have no `outcome` because no
+ * fact id was allocated.
+ */
+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 {
   /** The fact id. */
@@ -373,6 +401,31 @@ export interface ExportPage {
   /** Pass this opaque cursor to the next call; absent when the scan is done. */
   nextCursor?: number
 }
+/** One active tag and the number of current facts carrying it. */
+export interface TagSummary {
+  name: string
+  count: number
+}
+/** One bounded, stable page of current tags. */
+export interface TagPage {
+  items: Array<TagSummary>
+  nextCursor?: string
+}
+/** Result of removing one tag from all current facts. */
+export interface RemoveTagReport {
+  affected: number
+}
+/** The report of an explicit complete vector-axis replacement. */
+export interface ReembedReport {
+  previousSpace?: string
+  newSpace: string
+  previousDim: number
+  newDim: number
+  embedded: number
+  tombstonesSkipped: number
+  vectorBytes: number
+  hnswIndexed: number
+}
 /** The report of a `maintain` pass. */
 export interface MaintainReport {
   /** Tombstoned facts physically removed by this pass. */
@@ -448,7 +501,7 @@ export const enum MaintainMode {
  * round-trip it would be the wrong direction of dependency.
  */
 export interface DbEntry {
-  /** The memory's name — its identity, and what `Workspace.open` takes. */
+  /** The memory's name — its identity, and what `Workspace.memory` takes. */
   db: string
   /** What it is for. */
   description: string
@@ -636,6 +689,14 @@ export declare class Plugmem {
    * @throws synchronously in read-only mode.
    */
   remember(args: RememberArgs): Promise<RememberOutcome>
+  /**
+   * Stores only when the same bounded Jaccard/cosine detector used by
+   * `remember().similar` finds no candidate. No other write can slip between
+   * the check and possible write; a blocked result performs no mutation.
+   * Runs on a libuv worker because
+   * automatic embedding and durable writes are blocking work.
+   */
+  rememberGuarded(args: RememberArgs): Promise<GuardedRememberOutcome>
   /**
    * Stores a batch of facts and resolves with one outcome per input.
    *
@@ -755,6 +816,17 @@ export declare class Plugmem {
   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>
+  /**
+   * One bounded page of current tags. Runs on a libuv worker so neither a
+   * mapped-page fault nor host locking can pause the JavaScript event loop.
+   */
+  listTags(options?: TagListOptions | undefined | null): Promise<TagPage>
+  /**
+   * Removes a tag from every current fact by creating successor revisions.
+   * The bulk write and journal sync run on a libuv worker.
+   * @throws synchronously in read-only mode.
+   */
+  removeTag(tag: string): Promise<RemoveTagReport>
   /**
    * Content-integrity check; rejects on the first inconsistency found.
    *
@@ -774,6 +846,16 @@ export declare class Plugmem {
    * the only mode that reclaims edge-history page slack.
    */
   maintain(mode?: 'auto' | 'compact' | 'reindex-text' | 'optimize-vectors' | 'full'): Promise<MaintainReport>
+  /**
+   * Explicitly recomputes every retained fact with the configured embedder
+   * and atomically replaces the complete vector axis. This is never invoked
+   * by `maintain('auto')`.
+   *
+   * **Async**: provider and snapshot work runs on a libuv worker; the event
+   * loop remains responsive. Reads continue while it runs and writes reject
+   * with `PLUGMEM_BUSY` instead of waiting.
+   */
+  reembed(batchSize?: number | undefined | null): Promise<ReembedReport>
   /**
    * Flushes the journal into a fresh snapshot. **Async** (returns a `Promise`):
    * it writes and fsyncs a snapshot file, so it runs on a libuv worker thread.
@@ -838,9 +920,38 @@ export declare class Scrub {
   active(): boolean
 }
 /**
- * A directory of named memories — the napi mirror of
- * [`plugmem_host::Workspace`].
+ * A logical reference to one named memory.
+ *
+ * It owns no open database and no file lock. Each verb obtains a scoped
+ * workspace lease on a libuv worker, and dropping this JavaScript object has
+ * no resource-management meaning. The workspace is the owner; closing it
+ * invalidates every reference.
  */
+export declare class WorkspaceMemory {
+  /** The stable workspace name this reference addresses. */
+  name(): string
+  remember(args: RememberArgs): Promise<RememberOutcome>
+  rememberGuarded(args: RememberArgs): Promise<GuardedRememberOutcome>
+  rememberMany(args: Array<RememberArgs>): Promise<RememberOutcome[]>
+  revise(id: number, args: RememberArgs): Promise<RememberOutcome>
+  recall(args?: RecallArgs | undefined | null): Promise<RecallResult>
+  forget(id: number): Promise<boolean>
+  link(args: LinkArgs): Promise<void>
+  unlink(args: LinkArgs): Promise<boolean>
+  get(id: number): Promise<FactSnapshot | null>
+  stats(): Promise<Stats>
+  export(): Promise<ExportedFact[]>
+  exportPage(cursor?: number | undefined | null): Promise<ExportPage>
+  exportEdges(onBatch: (edges: ExportedEdge[]) => void): Promise<number>
+  scrub(options?: ScrubOptions | undefined | null): Promise<Scrub>
+  tagsOf(id: number): Promise<string[]>
+  listTags(options?: TagListOptions | undefined | null): Promise<TagPage>
+  removeTag(tag: string): Promise<RemoveTagReport>
+  verify(): Promise<void>
+  maintain(mode?: 'auto' | 'compact' | 'reindex-text' | 'optimize-vectors' | 'full'): Promise<MaintainReport>
+  reembed(batchSize?: number | undefined | null): Promise<ReembedReport>
+  checkpoint(): Promise<void>
+}
 export declare class Workspace {
   /**
    * Opens the workspace rooted at `root`. Creates nothing: the directories
@@ -850,22 +961,22 @@ export declare class Workspace {
    */
   constructor(root: string, options?: WorkspaceOptions | undefined | null)
   /**
-   * Opens the memory named `db` and returns it as a [`Plugmem`] — the same
-   * class, and the same verbs, as a memory opened by path.
+   * Returns a logical reference to the memory named `db`.
    *
-   * `create` defaults to `true`: a first use of an unused name brings that
-   * memory into being, which is what makes a new conversation need no
-   * registration step. Pass `false` to require that it already exists, which
-   * is what a read should do so a misspelled name is diagnosed rather than
-   * answered with nothing.
+   * This does not open a file, acquire a lock or create the memory. Read
+   * verbs require it to exist; write verbs create it on first use. The
+   * returned object stays valid across pool eviction and `release()` and
+   * transparently reopens the memory on its next verb.
+   */
+  memory(db: string): WorkspaceMemory
+  /**
+   * Evicts one inactive memory from the pool and releases its file lock.
    *
-   * @throws if the name is not a usable memory name, if it does not exist and
-   * `create` is false, or if another process holds it.
-   * **Async**: a first open replays the memory's journal and maps its
-   * snapshot, and making room in the pool closes another memory — file work
-   * that the one thread running JavaScript must not be holding.
+   * Logical references remain valid. A later verb reopens the memory. If a
+   * verb is currently using it, this throws a typed `BUSY` error instead of
+   * waiting.
    */
-  open(db: string, create?: boolean | undefined | null): Promise<Plugmem>
+  release(db: string): boolean
   /**
    * Every memory in the directory, sorted by name.
    *
@@ -934,12 +1045,10 @@ export declare class Workspace {
   /** How many memories are open right now. */
   openCount(): number
   /**
-   * Closes every pooled memory and the registry, releasing their file locks,
-   * and closes the workspace. Every method then throws.
-   *
-   * A [`Plugmem`] handed out by `open()` is **not** closed by this: it is its
-   * own handle and holds its own lock until it is closed or garbage
-   * collected.
+   * Invalidates every [`WorkspaceMemory`] reference, closes inactive pooled
+   * memories and the registry, and closes the workspace. A verb already in
+   * flight finishes with its scoped handle; its lock is released when that
+   * verb returns. Every later call throws `CLOSED`.
    */
   close(): void
 }

package/index.js

@@ -310,12 +310,13 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { Plugmem, recover, Scrub, MaintainMode, Workspace, version, about, settingsHelp, skill, skillFull, skillVersion } = nativeBinding
+const { Plugmem, recover, Scrub, MaintainMode, WorkspaceMemory, 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.WorkspaceMemory = WorkspaceMemory
 module.exports.Workspace = Workspace
 module.exports.version = version
 module.exports.about = about

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plugmem",
-  "version": "0.8.0",
+  "version": "0.10.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.8.0",
-    "plugmem-linux-arm64-gnu": "0.8.0",
-    "plugmem-darwin-x64": "0.8.0",
-    "plugmem-darwin-arm64": "0.8.0",
-    "plugmem-win32-x64-msvc": "0.8.0",
-    "plugmem-win32-arm64-msvc": "0.8.0"
+    "plugmem-linux-x64-gnu": "0.10.0",
+    "plugmem-linux-arm64-gnu": "0.10.0",
+    "plugmem-darwin-x64": "0.10.0",
+    "plugmem-darwin-arm64": "0.10.0",
+    "plugmem-win32-x64-msvc": "0.10.0",
+    "plugmem-win32-arm64-msvc": "0.10.0"
   }
 }