plugmem 0.3.0 → 0.5.0

package/index.d.ts

@@ -0,0 +1,746 @@
+/* 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
+  /**
+   * Token budget of the `rendered` block (default 512). That block is what
+   * goes into a prompt, so this is the knob deciding how much of the
+   * context window a recall may spend.
+   */
+  tokenBudget?: number
+  /**
+   * HNSW beam width for the vector source (default: the configured
+   * `hnsw_ef_search`). Higher is more accurate and slower; ignored while
+   * the engine is still in the flat regime, below `flat_to_hnsw`.
+   */
+  ef?: 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::link`]. */
+export interface LinkArgs {
+  /** Source entity name. */
+  src: string
+  /** Relation name. */
+  rel: string
+  /** Destination entity name. */
+  dst: string
+  /**
+   * The fact this edge follows from, recorded on the edge and returned by
+   * graph recall — the answer to "why is this edge here". Ignored by
+   * `unlink`, which closes an edge rather than opening one.
+   */
+  provenance?: number
+}
+/** 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's id in the database it came from. Informational: an import
+   * assigns fresh ids. Present because edges name their provenance fact by
+   * id, so a dump carrying edges needs something for them to point at.
+   */
+  id: number
+  /** 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, in two ways.** The scan runs on a worker,
+   * yet the whole memory is materialized into a single array before it
+   * resolves, so peak memory is the whole export. And `resolve` runs on the
+   * JS thread by definition, so building one JavaScript object per fact
+   * stalls it: measured at ~244 ms of a 289 ms call over 100 000 facts,
+   * against 0 ms for the same data through `exportPage`. A promise hides
+   * neither cost. Prefer `exportPage` 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
+}