plugmem 0.2.0 → 0.3.0

package/README.md

@@ -70,6 +70,7 @@ card.metadata;                // Record<string,string> — keys sorted, {} when
 
 db.revise(out.id, { text: "prefers async-std" });
 db.link({ src: "user", rel: "works_at", dst: "acme" });
+db.unlink({ src: "user", rel: "works_at", dst: "acme" }); // closes the current edge
 
 await db.checkpoint();        // async (see below)
 db.close();                   // release the file + lock explicitly
@@ -111,27 +112,114 @@ must agree. A `{ readOnly: true }` handle never auto-embeds — pass a vector.
 
 ## The verbs
 
-Method names mirror `plugmem-host`'s `Database` one-to-one.
+Every method here is the identically-named `plugmem-host` `Database` verb; the
+engine logic is entirely the host's.
 
-**Writer** (default): `remember`, `recall`, `revise(id, args)`, `forget(id)`,
-`link`, `get(id)`, `stats`, `export`, `verify`, and the two **async** verbs
-below. **Read-only** (`{ readOnly: true }`, observing another process's writer):
-`recall`, `get`, `stats`, `export`, `verify`, plus `generation()` (the pinned
-snapshot generation) and `refresh()` (advance to the writer's latest checkpoint);
-the write verbs throw.
+**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.
 
-**No `import` verb** — bulk-loading a `backup.jsonl` reads a file on disk, which
-is [`plugmem-cli import`](https://docs.rs/plugmem-cli/latest)'s job. An agent
-remembers facts one at a time as the conversation goes.
+### What the host has and this does not
 
-## Async and concurrency (no tokio)
+The list above is the whole supported `Plugmem` surface. The only host
+operation intentionally kept out of this boundary is path-level recovery:
 
-`maintain()` and `checkpoint()` do real disk I/O (compaction, HNSW build,
-fsync), so they return a **`Promise`** and run on the **libuv** thread pool —
-they never block the event loop. Every other verb is microsecond-fast in memory
-and stays synchronous (a Promise there would be pure overhead). There is no async
-runtime: the engine is CPU-bound, and the one thing that can wait — a remote
-embedder's HTTP call — happens outside the engine lock.
+| 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. |
+
+**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.
+
+## Many memories in one directory (optional)
+
+**Default: one memory, one file.** `new Plugmem(path)` and nothing here applies.
+
+A process that serves many independent memories — one per conversation, per
+tenant, per project — can point at a directory and address them by name:
+
+```ts
+import { Workspace, type DbEntry } from "plugmem";
+
+const ws = new Workspace("/srv/memories", { maxOpen: 16, idleTimeoutMs: 60_000 });
+
+// `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.
+ws.open("chat-42").remember({ text: "prefers tokio" });
+
+// 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.
+ws.describe("chat-42", { description: "release planning", owner: "ann" });
+const hits: DbEntry[] = ws.find("release planning");   // → [{ db: "chat-42", … }]
+```
+
+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.
+
+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.
+
+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.
+
+`reindex()` and `verify()` return promises: they open and read every memory in
+the directory, which is not work for the main thread.
+
+## Async and concurrency
+
+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`.
+
+For a bounded export, call `exportPage()` once, process its `facts`, then pass
+`nextCursor` to the next call until it is absent:
+
+```ts
+let cursor: number | undefined;
+do {
+  const page = await db.exportPage(cursor);
+  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.
+
+`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.
+
+`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.
+
+Small single-record and read verbs stay synchronous for a direct API. A single
+write can still wait for the configured durability policy, and a configured
+embedder can perform a remote request; use `rememberMany` when that work should
+run away from the event loop.
 
 `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()`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plugmem",
-  "version": "0.2.0",
+  "version": "0.3.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).",
   "repository": {
     "type": "git",
@@ -31,19 +31,21 @@
     "node": ">= 16"
   },
   "devDependencies": {
-    "@napi-rs/cli": "^2.18.4"
+    "@napi-rs/cli": "^2.18.4",
+    "typescript": "^5.9.3"
   },
   "scripts": {
     "build": "napi build --platform --release",
     "build:debug": "napi build --platform",
-    "test": "node --test __test__/*.test.mjs"
+    "test": "node --test __test__/*.test.mjs",
+    "typecheck": "tsc -p tsconfig.json"
   },
   "optionalDependencies": {
-    "plugmem-linux-x64-gnu": "0.2.0",
-    "plugmem-linux-arm64-gnu": "0.2.0",
-    "plugmem-darwin-x64": "0.2.0",
-    "plugmem-darwin-arm64": "0.2.0",
-    "plugmem-win32-x64-msvc": "0.2.0",
-    "plugmem-win32-arm64-msvc": "0.2.0"
+    "plugmem-linux-x64-gnu": "0.3.0",
+    "plugmem-linux-arm64-gnu": "0.3.0",
+    "plugmem-darwin-x64": "0.3.0",
+    "plugmem-darwin-arm64": "0.3.0",
+    "plugmem-win32-x64-msvc": "0.3.0",
+    "plugmem-win32-arm64-msvc": "0.3.0"
   }
 }