plugmem 0.3.0 → 0.5.0

package/README.md

@@ -1,20 +1,25 @@
-# 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`**.
+A memory database for LLM agents, embedded in your Node process. It stores short
+facts and answers a query with a ranked block of text ready to put in a prompt.
 
-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)**.
+One file 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,77 +27,269 @@ 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" });
 
-## Which door is this?
+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)
 
-plugmem is **embedded-first, like SQLite**. Pick the door for your language:
+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 |
 
-| 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. |
+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.
 
-So: **Node/TS → napi; Rust → host; an agent or other language → MCP; a human →
-the CLI.**
+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.
 
-## Usage (TypeScript)
+## Two clocks
 
-Every argument and result is typed — napi generates `index.d.ts`, so a TS host
-gets full autocomplete and checking:
+This is the part worth reading, because it is the one thing that behaves
+differently from every other store.
+
+Every fact carries **two** timestamps, not one:
+
+- **`validFrom` / `validTo`** — when the statement was true.
+- **`recordedAt`** — when the memory learned it. Set by the engine, never by you.
+
+They are different questions, and one timestamp cannot hold both.
+
+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" });
+
+(await db.recall({ entities: ["kim"] })).rendered;
+// - [f1] kim: lives in Berlin (2026-08; active)
 
-const db = new Plugmem("agent.plugmem");          // or { readOnly: true }
+(await db.recall({ entities: ["kim"], asOf: between })).rendered;
+// - [f0] kim: lives in Moscow (2026-08 → 2026-08; closed)
+```
+
+`revise` closed the first fact's interval rather than deleting it, which is why
+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
+would be the wrong answer to "what did I hold".
 
-const out = 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
+`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.
+
+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
+```
+
+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:
+
+| 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 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
 });
-out.id;                       // number
-out.similar;                  // Similar[] — the engine surfaces conflicts, you decide
 
-const res = db.recall({ query: "runtime?", k: 5 });
-res.rendered;                 // the prompt-ready block
-res.facts;                    // RecalledFact[] — { id, score, entity, recordedAt, … }
+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
+```
+
+`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:
+
+```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.
+}
+```
+
+## 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) |
+
+**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 |
+
+**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).
 
-const card = db.get(out.id);
-card.metadata;                // Record<string,string> — keys sorted, {} when none
+`close()` releases the file and its lock; every verb afterwards throws, and
+calling it twice is a no-op.
 
-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
+### Bringing your own embedding
 
-await db.checkpoint();        // async (see below)
-db.close();                   // release the file + lock explicitly
+`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 });
 ```
 
-## Configuration & embeddings
+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.
+
+### What the Rust library has and this does not
+
+| Not here | Why |
+|---|---|
+| `recover` | salvaging a damaged file is a path-level operation on the host's disk — the CLI's job |
+| `import` | the JSONL file format lives in [`plugmem-cli`](https://docs.rs/plugmem-cli/latest). A Node program holding records already uses `rememberMany` |
+| `scrub` | byte-level container integrity, likewise CLI-side; `verify()` covers content |
+
+## Errors
+
+Every failure plugmem itself decides carries a stable `code`, so a program
+branches on it instead of on wording:
+
+```js
+try {
+  db = await Plugmem.open("agent.plugmem");
+} catch (err) {
+  if (err.code === "PLUGMEM_LOCKED") retryLater();
+  else throw err;
+}
+```
+
+`PLUGMEM_LOCKED`, `PLUGMEM_NEEDS_CHECKPOINT`, `PLUGMEM_CONFIG` and
+`PLUGMEM_OPEN` come from opening; `PLUGMEM_INVALID_ARG` and
+`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
+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 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.
 
-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.
+## Configuration and embeddings
+
+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.
 
 ```typescript
-const db = new Plugmem(undefined, { config: "./plugmem.toml" });
+const db = await Plugmem.open(undefined, { config: "./plugmem.toml" });
 ```
 
 ```toml
 # plugmem.toml
 [database]
-path = "/path/to/memory.plugmem" # optional example
+path = "/path/to/memory.plugmem"
 
 [engine]
 dim = 768                     # embedding size (0 = vectors off)
@@ -101,130 +298,214 @@ dim = 768                     # embedding size (0 = vectors off)
 kind  = "ollama"              # or openai / lmstudio / vllm / llamacpp
 url   = "http://localhost:11434/v1/embeddings"
 model = "nomic-embed-text"
+
+[maintenance]
+fsync = "each_op"             # or "on_snapshot": faster, loses the journal tail on an OS crash
 ```
 
-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 never auto-embeds — pass a vector.
+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
+
+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.
 
-## The verbs
+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 method here is the identically-named `plugmem-host` `Database` verb; the
-engine logic is entirely the host's.
+Synchronous: `path`, `get`, `stats`, `tagsOf`, `generation`, `refresh`, `close`.
+These touch mapped memory and return in microseconds, where a promise would be
+pure ceremony.
 
-**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.
+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.
 
-### What the host has and this does not
+### Two costs a promise does not hide
 
-The list above is the whole supported `Plugmem` surface. The only host
-operation intentionally kept out of this boundary is path-level recovery:
+**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:
 
-| host verb | boundary note |
+| | `fs.readFile` |
 |---|---|
-| `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. |
+| 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:
 
-**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.
+```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);
+```
+
+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.
+
+### Concurrency
 
-## Many memories in one directory (optional)
+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.
 
-**Default: one memory, one file.** `new Plugmem(path)` and nothing here applies.
+## Many memories in one directory
 
-A process that serves many independent memories — one per conversation, per
-tenant, per project — can point at a directory and address them by name:
+**Default: one memory, one file.** `Plugmem.open(path)` and nothing here
+applies.
+
+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:
 
 ```ts
 import { Workspace, type DbEntry } from "plugmem";
 
-const ws = new Workspace("/srv/memories", { maxOpen: 16, idleTimeoutMs: 60_000 });
+const ws = new Workspace("/srv/memories");
 
-// `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" });
+// 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" });
 
-// 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", … }]
+// 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
 ```
 
-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.
+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:
 
-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.
+```ts
+await ws.describe("chat-42", { description: "release planning", owner: "ann" });
 
-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.
+const hits: DbEntry[] = await ws.find("release planning");  // → [{ db: "chat-42", … }]
+const byOwner: DbEntry[] = await ws.find("ann");            // → the same memory
+```
 
-`reindex()` and `verify()` return promises: they open and read every memory in
-the directory, which is not work for the main thread.
+A name is `[a-z0-9][a-z0-9_-]*` and **cannot express a path**, so it resolves to
+exactly one file 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.
 
-## Async and concurrency
+**Who may reach which memory is not this package's job.** The name comes from
+your code, so the policy belongs there.
 
-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`.
+### Running it
 
-For a bounded export, call `exportPage()` once, process its `facts`, then pass
-`nextCursor` to the next call until it is absent:
+| 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
-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);
+const ws = new Workspace("/srv/memories", { maxOpen: 16, idleTimeoutMs: 60_000 });
+setInterval(() => ws.closeIdle(), 30_000);
 ```
 
-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.
+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
 
-`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.
+plugmem is for a local agent's memory: one process, one file, 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.
 
-`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.
+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).
 
-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.
+## 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>