plugmem 0.3.0 → 0.4.0

package/README.md

@@ -44,14 +44,16 @@ the CLI.**
 ## Usage (TypeScript)
 
 Every argument and result is typed — napi generates `index.d.ts`, so a TS host
-gets full autocomplete and checking:
+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.
 
 ```typescript
 import { Plugmem } from "plugmem";
 
-const db = new Plugmem("agent.plugmem");          // or { readOnly: true }
+const db = await Plugmem.open("agent.plugmem");    // or { readOnly: true }
 
-const out = db.remember({
+const out = await db.remember({
   text: "prefers tokio",
   entity: "user",
   tags: ["pref"],
@@ -61,15 +63,15 @@ const out = db.remember({
 out.id;                       // number
 out.similar;                  // Similar[] — the engine surfaces conflicts, you decide
 
-const res = db.recall({ query: "runtime?", k: 5 });
+const res = await db.recall({ query: "runtime?", k: 5 });
 res.rendered;                 // the prompt-ready block
 res.facts;                    // RecalledFact[] — { id, score, entity, recordedAt, … }
 
 const card = db.get(out.id);
 card.metadata;                // Record<string,string> — keys sorted, {} when none
 
-db.revise(out.id, { text: "prefers async-std" });
-db.link({ src: "user", rel: "works_at", dst: "acme" });
+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
 
 await db.checkpoint();        // async (see below)
@@ -86,7 +88,7 @@ data directory. See the [full settings reference](https://github.com/m62624/plug
 for all fields and OS-specific paths.
 
 ```typescript
-const db = new Plugmem(undefined, { config: "./plugmem.toml" });
+const db = await Plugmem.open(undefined, { config: "./plugmem.toml" });
 ```
 
 ```toml
@@ -108,7 +110,10 @@ 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.
+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
 
@@ -122,6 +127,37 @@ engine logic is entirely the host's.
 `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
+
+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
+the host's 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.
 
 ### What the host has and this does not
 
@@ -141,7 +177,7 @@ 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.
+**Default: one memory, one file.** `Plugmem.open(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:
@@ -153,12 +189,12 @@ 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" });
+await (await 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", … }]
+await ws.describe("chat-42", { description: "release planning", owner: "ann" });
+const hits: DbEntry[] = await ws.find("release planning"); // → [{ db: "chat-42", … }]
 ```
 
 A name is `[a-z0-9][a-z0-9_-]*` and **cannot represent a path**, so it resolves
@@ -178,6 +214,11 @@ 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.
 
+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.
+
 `reindex()` and `verify()` return promises: they open and read every memory in
 the directory, which is not work for the main thread.
 
@@ -216,10 +257,40 @@ a no-op report when there is nothing to purge, reindex or optimize.
 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.
+### What is async, and why
+
+`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.
+
+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.
+
+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.
+
+### Bringing your own embedding
+
+`remember`, `revise`, `rememberMany` and `recall` all take an optional
+`vector` — a precomputed embedding whose length must equal the configured `dim`:
+
+```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 });
+```
+
+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.
 
 `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/index.d.ts

@@ -0,0 +1,718 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/** Options for [`Plugmem::new`]. */
+export interface OpenOptions {
+  /**
+   * Embedding dimension (`Config::dim`). Omit or 0 to keep vectors off. When
+   * the config file configures an `[embedder]`, that embedder's dimension is
+   * authoritative and this — if given — must agree with it.
+   */
+  dim?: number
+  /**
+   * Open read-only over another process's writer (requires a checkpointed
+   * database). The write verbs then throw; `generation`/`refresh` appear.
+   *
+   * A text `recall` still reaches the vector source: the engine cannot embed
+   * on a read-only handle (replaying into it would defeat the zero-copy
+   * open), so this binding embeds the query itself before asking — the same
+   * thing the CLI and the MCP server do for their read-only paths.
+   */
+  readOnly?: boolean
+  /**
+   * Path to a `config.toml` (`[database]` / `[engine]` / `[embedder]` /
+   * `[maintenance]`). When the constructor path is omitted, `[database].path`
+   * participates in database-path resolution.
+   * Omitted, the standard discovery applies — `$PLUGMEM_CONFIG`, then
+   * `$XDG_CONFIG_HOME/plugmem/config.toml` — exactly as the CLI and MCP
+   * server resolve it. The `[embedder]` section is what makes a text-only
+   * `remember`/`recall` auto-embed; with no config there is no embedder
+   * (lexical, tag, graph and time recall still answer).
+   */
+  config?: string
+}
+/** One typed edge on a remembered fact: `entity` gains relation `rel`. */
+export interface LinkRef {
+  /** The relation name. */
+  rel: string
+  /** The target entity name. */
+  entity: string
+}
+/** Arguments for [`Plugmem::remember`] / [`Plugmem::revise`]. */
+export interface RememberArgs {
+  /** The fact text (required). */
+  text: string
+  /** Subject entity name. */
+  entity?: string
+  /** Tag strings. */
+  tags?: Array<string>
+  /** Typed edges to attach. */
+  links?: Array<LinkRef>
+  /**
+   * Opaque metadata as a key→value map (a URI to the real payload, a mime
+   * type, an external key). The engine never interprets it.
+   */
+  metadata?: Record<string, string>
+  /** Validity start, unix milliseconds (default: the fact's record time). */
+  validFrom?: number
+  /**
+   * A precomputed embedding. Its length must equal the configured `dim`.
+   *
+   * Given, it **replaces** the embedder: nothing is sent to the provider.
+   * That is the host's own precedence — it embeds only when this is absent —
+   * and it is the route for a vector you already have, or for a model that
+   * is not an OpenAI-shaped HTTP endpoint.
+   */
+  vector?: Array<number>
+}
+/**
+ * Arguments for [`Plugmem::recall`] — every field optional; lexical/tag/graph/
+ * time still answer with no query vector.
+ */
+export interface RecallArgs {
+  /** Free-text query (embedded by the engine when an embedder is configured). */
+  query?: string
+  /** Restrict to facts carrying all these tags. */
+  tags?: Array<string>
+  /** Anchor entities for the graph source. */
+  entities?: Array<string>
+  /** "What was true at" this instant, unix milliseconds (bitemporal as-of). */
+  asOf?: number
+  /** Time window `[from, to)` over `recorded_at`, unix milliseconds. */
+  range?: Array<number>
+  /** Max facts to return (0 = engine default). */
+  k?: number
+  /** Include closed revisions (default false). */
+  closed?: boolean
+  /**
+   * A precomputed embedding. Its length must equal the configured `dim`.
+   *
+   * Given, it **replaces** the embedder: nothing is sent to the provider.
+   * That is the host's own precedence — it embeds only when this is absent —
+   * and it is the route for a vector you already have, or for a model that
+   * is not an OpenAI-shaped HTTP endpoint.
+   */
+  vector?: Array<number>
+}
+/** Arguments for [`Plugmem::link`]. */
+export interface LinkArgs {
+  /** Source entity name. */
+  src: string
+  /** Relation name. */
+  rel: string
+  /** Destination entity name. */
+  dst: string
+}
+/** One similar / potentially-conflicting live fact surfaced by `remember`. */
+export interface Similar {
+  /** The existing fact's id. */
+  id: number
+  /** Match strength (higher = closer). */
+  score: number
+  /** What triggered the hint: `"LexicalOverlap"` or `"VectorCosine"`. */
+  reason: string
+}
+/** The result of `remember` / `revise`. */
+export interface RememberOutcome {
+  /** The new fact's id. */
+  id: number
+  /** The subject entity id, if one was named. */
+  entity?: number
+  /**
+   * Similar / potentially-conflicting live facts (best first; the engine
+   * never merges on its own — the caller decides).
+   */
+  similar: Array<Similar>
+}
+/** One recalled fact. */
+export interface RecalledFact {
+  /** The fact id. */
+  id: number
+  /** Fused score (reciprocal-rank fusion + recency). */
+  score: number
+  /** Bit set of the sources that surfaced it. */
+  sources: number
+  /** Subject entity id (a sentinel when none). */
+  entity: number
+  /** Knowledge axis: when the memory learned it (unix ms). */
+  recordedAt: number
+  /** Truth axis start (unix ms). */
+  validFrom: number
+  /** Truth axis end (unix ms), or the open sentinel — see the module note. */
+  validTo: number
+}
+/** One edge walked by the graph source. */
+export interface RecalledEdge {
+  /** Source entity id. */
+  src: number
+  /** Relation term id. */
+  rel: number
+  /** Destination entity id. */
+  dst: number
+  /** Provenance fact id (a sentinel when none). */
+  provenance: number
+}
+/** A recall response: the structured hits plus the prompt-ready block. */
+export interface RecallResult {
+  /** Selected facts, descending fused score. */
+  facts: Array<RecalledFact>
+  /** Edges the graph source walked (deduplicated). */
+  edges: Array<RecalledEdge>
+  /** The compact prompt block (empty when nothing was found). */
+  rendered: string
+  /** `true` when selection stopped at `k`/the token budget with more left. */
+  truncated: boolean
+}
+/** Engine size counters. */
+export interface Stats {
+  /** Fact records stored (live, closed and tombstoned-awaiting-maintain). */
+  facts: number
+  /** Entities. */
+  entities: number
+  /** Interned terms (tokens, tags, relations, names). */
+  terms: number
+  /** Directed edges. */
+  edges: number
+  /** Historical edge versions, including closed versions. */
+  edgeVersions: number
+  /** Quantized vector slots. */
+  vectors: number
+  /** Tombstoned fact records awaiting physical purge. */
+  tombstones: number
+  /** Vector slots covered by HNSW. */
+  hnswIndexed: number
+  /** The next fact id to be assigned. */
+  nextFact: number
+  /** The next entity id to be assigned. */
+  nextEntity: number
+  /** The next edge-version id to be assigned. */
+  nextEdge: number
+  /** Total bytes held by the engine's pools. */
+  poolBytes: number
+}
+/**
+ * The raw record behind a [`FactSnapshot`] — temporality and flags. (Internal
+ * pointers — the blob/vector slots and the reserved `kind` — are omitted.)
+ */
+export interface FactRecord {
+  /** The fact id. */
+  id: number
+  /** Subject entity id (a sentinel when none). */
+  entity: number
+  /** Bit set of fact flags (tombstone / closed / has-vector). */
+  flags: number
+  /** Predecessor in the revision chain (a sentinel when none). */
+  revises: number
+  /** Knowledge axis: when the memory learned it (unix ms). */
+  recordedAt: number
+  /** Truth axis start (unix ms). */
+  validFrom: number
+  /** Truth axis end (unix ms), or the open sentinel — see the module note. */
+  validTo: number
+}
+/** One fact's full card (from `get`). */
+export interface FactSnapshot {
+  /** The raw record (temporality, flags, references). */
+  record: FactRecord
+  /** The fact text. */
+  text: string
+  /**
+   * The fact's metadata as a key→value map (empty when it has none). Opaque
+   * to the engine — a URI to the real payload, a mime type, an external key.
+   */
+  metadata: Record<string, string>
+}
+/** One exported fact — the id-free, import-ready shape. */
+export interface ExportedFact {
+  /** The fact text. */
+  text: string
+  /** Subject entity name, if any. */
+  entity?: string
+  /** Tag strings. */
+  tags: Array<string>
+  /** Metadata as a key→value map (empty when none); preserved on import. */
+  metadata: Record<string, string>
+  /** When the memory learned it (unix ms; informational). */
+  recordedAt: number
+  /** Validity start (unix ms; preserved on import). */
+  validFrom: number
+}
+/** One bounded page returned by `exportPage`. */
+export interface ExportPage {
+  /** Open facts in fact-id order; never longer than the native page bound. */
+  facts: Array<ExportedFact>
+  /** Pass this opaque cursor to the next call; absent when the scan is done. */
+  nextCursor?: number
+}
+/** The report of a `maintain` pass. */
+export interface MaintainReport {
+  /** Tombstoned facts physically removed by this pass. */
+  purged: number
+  /** On-disk image bytes before the pass. */
+  bytesBefore: number
+  /** On-disk image bytes after the pass. */
+  bytesAfter: number
+  /** No storage/index rewrite was needed. */
+  noOp: boolean
+  /** Tombstones present before the pass. */
+  tombstonesBefore: number
+  /** Fact records before the pass. */
+  factsBefore: number
+  /** Fact records after the pass. */
+  factsAfter: number
+  /** Vector slots before the pass. */
+  vectorsBefore: number
+  /** Vector slots after the pass. */
+  vectorsAfter: number
+  /** HNSW coverage before the pass. */
+  hnswIndexedBefore: number
+  /** HNSW coverage after the pass. */
+  hnswIndexedAfter: number
+  /** Physical compaction ran. */
+  structuralCompacted: boolean
+  /** BM25 was compacted from existing postings. */
+  bm25Compacted: boolean
+  /** BM25 was rebuilt from text. */
+  bm25Reindexed: boolean
+  /** HNSW was rebuilt from empty. */
+  hnswRebuilt: boolean
+  /** HNSW was carried/remapped. */
+  hnswRemapped: boolean
+  /** Vector slots inserted into HNSW. */
+  hnswInserted: number
+  /**
+   * The edge arenas were rewritten page-dense (`full` only). No edge
+   * version is ever dropped, so the version count is unchanged — only the
+   * bytes shrink.
+   */
+  edgesCompacted: boolean
+  /** Current edges before the pass. */
+  edgesBefore: number
+  /** Historical edge versions before the pass. */
+  edgeVersionsBefore: number
+}
+/** How much work a `maintain` pass should do. */
+export const enum MaintainMode {
+  /**
+   * Only pending work: purge tombstones, refresh a stale text index, and
+   * advance the vector graph within a bounded budget. Cheap to run often.
+   */
+  Auto = 'auto',
+  /** Physically purge tombstoned facts and compact storage and indexes. */
+  Compact = 'compact',
+  /** Rebuild the text index by re-reading and re-tokenizing every fact. */
+  ReindexText = 'reindex-text',
+  /** Build or advance the vector graph without compacting anything else. */
+  OptimizeVectors = 'optimize-vectors',
+  /**
+   * Rebuild every rebuildable structure, fully optimize vectors and repack
+   * the edge arenas. O(database) work; no history is ever dropped.
+   */
+  Full = 'full'
+}
+/**
+ * One memory as the workspace registry knows it.
+ *
+ * Hand-mapped rather than serde-round-tripped like the rest of this file:
+ * `DbEntry` carries a `DbName`, which is a validated newtype with no serde
+ * derive, and giving one to a public host type only so a wrapper could
+ * round-trip it would be the wrong direction of dependency.
+ */
+export interface DbEntry {
+  /** The memory's name — its identity, and what `Workspace.open` takes. */
+  db: string
+  /** What it is for. */
+  description: string
+  /** Its tags. */
+  tags: Array<string>
+  /** Its owner, if recorded. */
+  owner?: string
+  /** Whether it is labelled archived. */
+  archived: boolean
+}
+/** What a `Workspace.reindex()` pass did. */
+export interface ReindexReport {
+  /** Memories whose own description was copied into the registry. */
+  indexed: Array<string>
+  /**
+   * Memories nobody has described. Not a fault — a memory works without a
+   * description; it just cannot be found by one.
+   */
+  undescribed: Array<string>
+  /**
+   * Memories another process holds open, so this pass could not read them.
+   * Named rather than skipped silently: the registry is knowingly incomplete.
+   */
+  busy: Array<string>
+}
+/** Something `Workspace.verify()` found. Reported, never repaired. */
+export interface WorkspaceProblem {
+  /** The memory it concerns (empty for a kind this binding does not know). */
+  db: string
+  /**
+   * What kind: `"missing"`, `"undescribed"`, `"stale"`, `"unreadable"`,
+   * `"ambiguous-self"`. The same vocabulary the CLI prints in `--json`.
+   */
+  issue: string
+  /** More detail, where the kind carries any. */
+  detail?: string
+}
+/** Options for [`Workspace::new`]. */
+export interface WorkspaceOptions {
+  /**
+   * Embedding dimension, as in [`crate::db::OpenOptions`]. Applies to every
+   * memory in the workspace and to the registry.
+   */
+  dim?: number
+  /**
+   * Path to a `config.toml`. Resolution is the standard one when omitted.
+   * Its `[workspace]` section supplies the pool defaults below.
+   */
+  config?: string
+  /**
+   * Memories kept open at once; the least recently used is closed to make
+   * room. Defaults to `[workspace].max_open`, else 16.
+   */
+  maxOpen?: number
+  /**
+   * Milliseconds a memory may sit unused before `closeIdle()` closes it.
+   * `0` disables the sweep. Defaults to `[workspace].idle_timeout_ms`, else
+   * 60000.
+   *
+   * This is a liveness setting, not a memory one: 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.
+   */
+  idleTimeoutMs?: number
+}
+/** What to record about a memory — the argument of [`Workspace::describe`]. */
+export interface DescribeArgs {
+  /**
+   * What this memory is for, in the words someone would search with. This is
+   * the text `find` matches.
+   */
+  description: string
+  /** Tags to filter by. */
+  tags?: Array<string>
+  /**
+   * Who it belongs to. Recorded as a graph edge, so `find("ann")` returns
+   * what Ann owns even though no description mentions her.
+   */
+  owner?: string
+}
+/**
+ * The engine/package version (the workspace version; the npm package tracks
+ * it release-for-release).
+ */
+export declare function version(): string
+/** A short, version-free description pointing the caller at the skill. */
+export declare function about(): string
+/** One config.toml setting returned by [`settings_help`]. */
+export interface SettingHelpItem {
+  /** TOML section name. */
+  section: string
+  /** TOML key name. */
+  key: string
+  /** Human-readable value type. */
+  valueType: string
+  /** Displayed default value. */
+  defaultValue: string
+  /** Setting behavior. */
+  description: string
+  /** Owning surface: shared, CLI or MCP. */
+  scope: string
+}
+/** Complete config.toml help returned by [`settings_help`]. */
+export interface SettingsHelpResult {
+  /** Config discovery order from highest to lowest precedence. */
+  configPathPrecedence: Array<string>
+  /** Resolved platform default config path, if the OS exposes a user home. */
+  defaultConfigPath?: string
+  /** Every supported config.toml setting. */
+  settings: Array<SettingHelpItem>
+}
+/** Return the complete settings catalogue without opening a database. */
+export declare function settingsHelp(): SettingsHelpResult
+/**
+ * The companion skill for napi consumers: the canonical `SKILL.md` with the
+ * CLI/MCP "Run it" appendix removed (a napi host has one transport and always
+ * ships skill and engine from the same release, so that ceremony never applies).
+ */
+export declare function skill(): string
+/** The canonical, unstripped `SKILL.md` (what CLI/MCP consumers read). */
+export declare function skillFull(): string
+/**
+ * The `<!-- skill-version: X.Y.Z -->` marker value from the canonical skill
+ * (read from the raw text, so the marker living inside the stripped block is
+ * still visible here).
+ */
+export declare function skillVersion(): string
+/**
+ * A memory over one plugmem file — the napi mirror of [`plugmem_host::Database`]
+ * (writer) or [`plugmem_host::ReadOnlyDatabase`] (with `{ readOnly: true }`).
+ * Construct it, call the verbs, and `close()` it to release the file when done.
+ */
+export declare class Plugmem {
+  /**
+   * Opens (or creates) the memory at `path` and resolves with the handle. If
+   * `path` is omitted, resolution is `PLUGMEM_DB` > `[database].path` > the
+   * platform data path — and [`path()`](Plugmem::path) reports what that was.
+   *
+   * **A static method, not a constructor, and that is the point.** Opening
+   * takes the file's exclusive lock, replays the journal and maps the
+   * snapshot — work proportional to what is on disk. A JavaScript
+   * constructor must evaluate to its object immediately, so `new` has no way
+   * to hand that to a worker: it would run on the one thread that executes
+   * JavaScript and freeze the process for the length of the replay. A static
+   * method can return a `Promise`, so it does.
+   *
+   * @throws synchronously on a config error (the file is read before any
+   * work is scheduled); rejects if another writer holds the lock
+   * (`PLUGMEM_LOCKED`), if `readOnly` is set on a database with no published
+   * snapshot (`PLUGMEM_NEEDS_CHECKPOINT`), or on an IO error.
+   */
+  static open(path?: string | undefined | null, options?: OpenOptions | undefined | null): Promise<Plugmem>
+  /**
+   * The file this memory is open on.
+   *
+   * Worth having because the constructor may resolve the path rather than be
+   * given one — `PLUGMEM_DB`, then `[database].path`, then the platform data
+   * path — and `new Plugmem()` with no argument otherwise leaves the caller
+   * unable to say which file it just wrote to.
+   */
+  path(): string
+  /**
+   * Stores a fact and resolves with its id plus similar/conflicting live
+   * facts.
+   *
+   * **Async** (returns a `Promise`): with an `[embedder]` configured this
+   * makes an HTTP call to the provider, and a write waits for the journal's
+   * durability policy. Both are blocking work, and Node has exactly one
+   * thread that runs JavaScript — doing them on it would freeze every timer,
+   * socket and callback in the process for the whole round trip. It runs on
+   * a libuv worker instead. Arguments are still checked synchronously, so a
+   * refused one throws here rather than rejecting later.
+   * @throws synchronously in read-only mode.
+   */
+  remember(args: RememberArgs): Promise<RememberOutcome>
+  /**
+   * Stores a batch of facts and resolves with one outcome per input.
+   *
+   * A batch may call a remote embedder and always performs one journal sync,
+   * so it runs on napi-rs' libuv worker pool.
+   */
+  rememberMany(args: Array<RememberArgs>): Promise<RememberOutcome[]>
+  /**
+   * Closes fact `id`, records `args` as its successor, and resolves with the
+   * outcome. **Async** for the same reasons as
+   * [`remember`](Plugmem::remember).
+   * @throws synchronously in read-only mode.
+   */
+  revise(id: number, args: RememberArgs): Promise<RememberOutcome>
+  /**
+   * Ranked, fused recall. Resolves with the structured result (its `rendered`
+   * field is the prompt-ready block; `facts`/`edges` are the structured hits).
+   *
+   * **Async** (returns a `Promise`): a text query with an `[embedder]`
+   * configured costs an HTTP round trip, and blocking the one thread that
+   * runs JavaScript for it would stall the whole process. The query shape is
+   * still validated synchronously.
+   */
+  recall(args?: RecallArgs | undefined | null): Promise<RecallResult>
+  /**
+   * Tombstones fact `id` (physically purged at the next `maintain`) and
+   * resolves with whether it was a live fact.
+   *
+   * **Async**: every write syncs the journal, and the host's post-write
+   * policy can fire a whole maintenance pass or a reshard from here — work
+   * proportional to the database, which the JS thread must not be holding.
+   * @throws synchronously in read-only mode.
+   */
+  forget(id: 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.
+   */
+  link(args: LinkArgs): Promise<void>
+  /**
+   * Closes the current typed edge `src -rel-> dst`, resolving with whether
+   * one was open. **Async** for the same reason as
+   * [`forget`](Plugmem::forget). @throws synchronously in read-only mode.
+   */
+  unlink(args: LinkArgs): Promise<boolean>
+  /** One fact's full card by `id`, or `null` if unknown/tombstoned. */
+  get(id: number): FactSnapshot | null
+  /** Engine size counters. */
+  stats(): Stats
+  /**
+   * 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.
+   */
+  export(): Promise<ExportedFact[]>
+  /**
+   * Returns at most 128 inspected fact ids' open facts on a libuv worker
+   * thread. A sparse page can be empty and still carry `nextCursor`.
+   *
+   * Pass `nextCursor` back as `cursor` until it is absent. Each Promise owns
+   * exactly one bounded page and resolves only after its native scan has
+   * completed; there is no callback queue and no database lock held while JS
+   * processes the result. A writer may change between page calls, so do not
+   * mutate it during a snapshot-style backup; a read-only handle is stable.
+   */
+  exportPage(cursor?: number | undefined | null): Promise<ExportPage>
+  /** One fact's tags, or an empty array for an unknown or tombstoned id. */
+  tagsOf(id: number): Array<string>
+  /**
+   * Content-integrity check; rejects on the first inconsistency found.
+   *
+   * **Async**: this is a full sweep — every fact's text and metadata, the
+   * vector mapping, and both directions of every edge. On a large memory
+   * that is seconds of work, and it belongs on a worker.
+   */
+  verify(): Promise<void>
+  /**
+   * Runs policy-driven maintenance; resolves with the before/after report.
+   * **Async** (returns a `Promise`): the pass may do disk I/O (compaction,
+   * HNSW work), so it runs on a libuv worker thread and never blocks the
+   * event loop. @throws synchronously in read-only mode.
+   *
+   * `mode` defaults to `auto`, which does only what is pending. `full`
+   * rebuilds everything and repacks the edge arenas — O(database) work, and
+   * the only mode that reclaims edge-history page slack.
+   */
+  maintain(mode?: 'auto' | 'compact' | 'reindex-text' | 'optimize-vectors' | 'full'): Promise<MaintainReport>
+  /**
+   * 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.
+   * @throws synchronously in read-only mode.
+   */
+  checkpoint(): Promise<void>
+  /**
+   * The pinned snapshot generation (read-only mode only).
+   * @throws on a writer.
+   */
+  generation(): number
+  /**
+   * Advance to the writer's latest published checkpoint (read-only mode only);
+   * returns whether a newer generation was adopted. @throws on a writer.
+   */
+  refresh(): boolean
+  /**
+   * Releases the file and its lock. Every verb afterwards throws; calling it
+   * again is a no-op. (The handle is also released when the object is GC'd,
+   * but `close()` makes the moment explicit — e.g. before a read-only reopen.)
+   */
+  close(): void
+}
+/**
+ * A directory of named memories — the napi mirror of
+ * [`plugmem_host::Workspace`].
+ */
+export declare class Workspace {
+  /**
+   * Opens the workspace rooted at `root`. Creates nothing: the directories
+   * appear when a memory is first written.
+   *
+   * @throws on a config error.
+   */
+  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.
+   *
+   * `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.
+   *
+   * @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.
+   */
+  open(db: string, create?: boolean | undefined | null): Promise<Plugmem>
+  /**
+   * Every memory in the directory, sorted by name.
+   *
+   * Reads the filesystem, not the registry: a memory that exists but was
+   * never described still appears.
+   * **Async**: it reads the directory.
+   */
+  list(): Promise<string[]>
+  /**
+   * Every described memory, sorted by name.
+   *
+   * **Async**: the registry is itself a memory, so this opens and reads a
+   * database.
+   */
+  entries(): Promise<DbEntry[]>
+  /**
+   * The memories whose descriptions best match `query`, best first.
+   *
+   * This is the answer to "I do not know the name": ask in words, get names
+   * back, then open by name. A person's name works too — an owner is a graph
+   * edge, and the graph source reaches it.
+   * **Async**: this is a full recall against the registry memory — the same
+   * hybrid retrieval any other recall runs.
+   */
+  find(query: string, k?: number | undefined | null): Promise<DbEntry[]>
+  /**
+   * Records what a memory is for — in the memory itself and in the registry,
+   * so the registry can always be rebuilt from the memories. Creates the
+   * memory if it does not exist.
+   *
+   * Called again for the same memory this revises rather than duplicating,
+   * so the history of what it used to be for is kept.
+   * **Async**: it writes twice — into the memory itself and into the
+   * registry — and each write syncs a journal.
+   */
+  describe(db: string, args: DescribeArgs): Promise<void>
+  /**
+   * Labels a memory archived, keeping its description. Returns whether
+   * anything changed. Archiving does not close, move or delete anything.
+   *
+   * @throws if the memory has no registry record to archive.
+   * **Async**: a registry write.
+   */
+  archive(db: string): Promise<boolean>
+  /**
+   * Rebuilds the registry from the memories' own descriptions.
+   *
+   * Runs on a libuv thread: it opens and reads every memory in the
+   * directory, which is not work for the main thread. A memory another
+   * process holds open cannot be read and is named in the report rather than
+   * skipped silently.
+   */
+  reindex(): Promise<ReindexReport>
+  /**
+   * Checks the registry against the directory. Reports every disagreement
+   * and repairs nothing — a workspace is a directory a person can edit, and
+   * guessing at their intent is how a consistency check loses data.
+   */
+  verify(): Promise<WorkspaceProblem[]>
+  /**
+   * Closes every memory unused for longer than the idle timeout, returning
+   * how many were closed. Call it on a timer: nothing else releases the file
+   * lock on a memory nobody is asking about.
+   */
+  closeIdle(): number
+  /** 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.
+   */
+  close(): void
+}

package/index.js

@@ -0,0 +1,323 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 10
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch (e) {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'android':
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'plugmem.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./plugmem.android-arm64.node')
+          } else {
+            nativeBinding = require('plugmem-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'plugmem.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./plugmem.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('plugmem-android-arm-eabi')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, 'plugmem.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./plugmem.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('plugmem-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'plugmem.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./plugmem.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('plugmem-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'plugmem.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./plugmem.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('plugmem-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'plugmem.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./plugmem.darwin-universal.node')
+      } else {
+        nativeBinding = require('plugmem-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'plugmem.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./plugmem.darwin-x64.node')
+          } else {
+            nativeBinding = require('plugmem-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'plugmem.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./plugmem.darwin-arm64.node')
+          } else {
+            nativeBinding = require('plugmem-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, 'plugmem.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./plugmem.freebsd-x64.node')
+      } else {
+        nativeBinding = require('plugmem-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'plugmem.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./plugmem.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('plugmem-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'plugmem.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./plugmem.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('plugmem-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'plugmem.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./plugmem.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('plugmem-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'plugmem.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./plugmem.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('plugmem-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'plugmem.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./plugmem.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('plugmem-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'plugmem.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./plugmem.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('plugmem-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'plugmem.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./plugmem.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('plugmem-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'plugmem.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./plugmem.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('plugmem-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'plugmem.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./plugmem.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('plugmem-linux-s390x-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { Plugmem, MaintainMode, Workspace, version, about, settingsHelp, skill, skillFull, skillVersion } = nativeBinding
+
+module.exports.Plugmem = Plugmem
+module.exports.MaintainMode = MaintainMode
+module.exports.Workspace = Workspace
+module.exports.version = version
+module.exports.about = about
+module.exports.settingsHelp = settingsHelp
+module.exports.skill = skill
+module.exports.skillFull = skillFull
+module.exports.skillVersion = skillVersion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plugmem",
-  "version": "0.3.0",
+  "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).",
   "repository": {
     "type": "git",
@@ -41,11 +41,11 @@
     "typecheck": "tsc -p tsconfig.json"
   },
   "optionalDependencies": {
-    "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"
+    "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"
   }
 }