mnemocyte 0.3.0 → 0.5.0

package/README.md

@@ -12,6 +12,8 @@ logs, and duplicate-consolidation tools on top of your existing infrastructure.
 
 - In-memory backend for tests and demos.
 - Postgres + pgvector backend for persistent storage.
+- Caller-owned postgres.js Drizzle instances through
+  `mnemocyte/stores/drizzle`.
 - User-supplied `Embedder` interface.
 - Hybrid recall with vector similarity, lexical matching, recency, confidence,
   access count, and importance.
@@ -65,14 +67,17 @@ const context = await client.buildContext({
 await client.close();
 ```
 
-When `databaseUrl` is omitted, Mnemocyte uses the in-memory backend.
+When both `databaseUrl` and `store` are omitted, Mnemocyte uses the in-memory
+backend. That backend is intended for development, tests, and prototyping. For
+persistent or larger workloads, use Postgres.
 
 ## Embedder
 
 Mnemocyte accepts any embedder that returns one vector per input text.
-Each vector must match `embedder.dimensions` and contain only finite numbers;
-invalid provider output fails with `MnemocyteError` code `"EMBEDDING"` before
-anything is stored.
+Each vector must match `embedder.dimensions`, contain only finite numbers, and
+have at least one nonzero component. Invalid provider output, including an
+exact zero-norm vector, fails with `MnemocyteError` code `"EMBEDDING"` before
+storage or vector comparison. Tiny nonzero vectors remain valid.
 
 ```ts
 const client = createMnemocyte({
@@ -102,7 +107,11 @@ const embedder = openaiEmbedder({
 explicitly when you use a different key source. The helper uses `fetch`
 directly and does not depend on the OpenAI SDK; plain `import "mnemocyte"` also
 stays provider-free. The direct subpath `mnemocyte/embedders/openai` is also
-supported for consumers that prefer provider-specific imports.
+supported for consumers that prefer provider-specific imports. Provider
+responses must contain exactly one uniquely indexed array embedding per input;
+malformed response shapes fail with `MnemocyteError` code `"EMBEDDING"`.
+Dimension and numeric-component validation remains at the shared embedder
+boundary.
 
 ## Postgres
 
@@ -116,11 +125,52 @@ const client = createMnemocyte({
 });
 ```
 
+Applications that already own a postgres.js Drizzle instance can pass it
+through the `mnemocyte/stores/drizzle` subpath:
+
+```ts
+import { createMnemocyte } from "mnemocyte";
+import { drizzleStore } from "mnemocyte/stores/drizzle";
+import { drizzle } from "drizzle-orm/postgres-js";
+import postgres from "postgres";
+import * as applicationSchema from "./db/schema.js";
+
+const sql = postgres(process.env.DATABASE_URL!);
+const db = drizzle(sql, { schema: applicationSchema });
+
+const client = createMnemocyte({
+  store: drizzleStore(db),
+  embedder,
+});
+
+try {
+  await client.remember({
+    entityId: "user_123",
+    content: "Uses the application's existing Drizzle connection.",
+  });
+} finally {
+  await client.close(); // does not close db or sql
+  await sql.end(); // the caller retains connection ownership
+}
+```
+
+`drizzleStore(db)` v1 accepts only Drizzle instances backed by postgres.js. It
+uses Mnemocyte's fixed tables in the `public` schema; the bundled migrations
+must already have been applied, and the adapter does not create or migrate
+tables. The caller's Drizzle schema map does not need to include Mnemocyte's
+tables. Supplying both `databaseUrl` and `store` is ambiguous and throws
+synchronously with `MnemocyteError` code `"CONFIG"`.
+
+`databaseUrl` must use the `postgres:` or `postgresql:` protocol. Other URL
+protocols reject synchronously with `MnemocyteError` code `"CONFIG"`; detailed
+host, database, and credential validation remains the driver's responsibility.
+
 The package includes:
 
 ```txt
 migrations/0000_initial.sql
 migrations/0001_add_mnemocyte_meta.sql
+migrations/0002_add_embedding_model.sql
 migrations/0000_initial.sql.template
 migrations/render-initial.mjs
 ```
@@ -131,16 +181,19 @@ order:
 ```txt
 migrations/0000_initial.sql
 migrations/0001_add_mnemocyte_meta.sql
+migrations/0002_add_embedding_model.sql
 ```
 
 For an existing 0.1.x Postgres install, apply
-`migrations/0001_add_mnemocyte_meta.sql` to record the current 1536-dimensional
-installation metadata.
+`migrations/0001_add_mnemocyte_meta.sql` and then
+`migrations/0002_add_embedding_model.sql`. Existing 0.2.x or 0.3.x installs
+only need `0002_add_embedding_model.sql`.
 
 For a different embedding dimension on a fresh installation, render an explicit
 initial migration from the template and apply that rendered file instead of the
 default `0000_initial.sql`. The rendered initial migration includes the
-matching `mnemocyte_meta` row.
+matching `mnemocyte_meta` dimensions and the installation-model column, so it
+does not also need `0001` or `0002`.
 
 ```bash
 node node_modules/mnemocyte/migrations/render-initial.mjs --dimensions 768 --out migrations/0000_initial.768.sql
@@ -152,14 +205,41 @@ Inside this repository, the equivalent development shortcut is:
 pnpm migration:render -- --dimensions 768 --out migrations/0000_initial.768.sql
 ```
 
-The Postgres backend supports one embedding dimension per installation. Before
-the first embedding-dependent Postgres operation, Mnemocyte reads
-`mnemocyte_meta` and validates it against `embedder.dimensions` before calling
-the embedder. A mismatch throws a `MnemocyteError` with code `"CONFIG"`; missing
-v0.2.0 metadata throws code `"MIGRATION"`.
+The Postgres backend supports one embedding model and dimension per
+installation. Before writes, recall, or duplicate scans, Mnemocyte reads
+`mnemocyte_meta` and validates both values before calling the embedder or
+comparing vectors. An empty installation atomically records the configured
+model on its first embedding-dependent operation. Migration `0002` records the
+single model already present in historical rows when that value is
+unambiguous.
+
+A configured model or dimension mismatch throws `MnemocyteError` code
+`"CONFIG"`. If historical rows contain multiple model values, the installation
+model remains unset and embedding-dependent operations throw `"MIGRATION"`
+until an operator re-embeds or removes the mixed rows and explicitly records
+the intended installation model. Non-embedding recovery operations such as
+`stats`, `forget`, and pruning remain available.
+
+Inspect mixed history before repairing it:
+
+```sql
+SELECT embedding_model, count(*)
+FROM mnemocyte_memories
+GROUP BY embedding_model;
+```
+
+Only after every retained row belongs to the intended vector space, record that
+model explicitly:
 
-Use the embedding dimension documented for your chosen model, render or apply a
-matching schema, and keep one dimension per Mnemocyte installation.
+```sql
+UPDATE mnemocyte_meta
+SET embedding_model = 'your-model-id'
+WHERE key = 'installation';
+```
+
+Use the model identifier and embedding dimension documented for your embedder,
+render or apply a matching schema, and keep one vector space per Mnemocyte
+installation.
 
 The migration creates the bundled HNSW pgvector index
 `mnemocyte_memories_embedding_hnsw_idx` for cosine search. HNSW is approximate:
@@ -200,6 +280,19 @@ bigints, non-finite numbers, class instances, or cyclic objects are rejected
 with `MnemocyteError` code `"VALIDATION"`. Mnemocyte deep-clones metadata when
 writing and reading, so later mutations do not change stored state.
 
+JavaScript callers receive the same runtime domain checks as TypeScript
+callers: `type` and `importance` must be known values, tags must be an array of
+strings, `source` must be a string when supplied, and `expiresAt` must be a
+valid `Date`. Invalid values reject with `"VALIDATION"` before embedding or
+storage. Mutable tags, metadata, and expiration dates are snapshotted when
+`remember` or `rememberMany` is invoked, so later caller mutations cannot
+change the pending write.
+
+When observability is configured, snapshot and validation failures follow the
+same operation lifecycle as provider or storage failures: one `"start"` event
+and one `"error"` event carrying the thrown value. Snapshotting remains
+synchronous before any awaited `onEvent` hook.
+
 For batches, cancellation belongs to the whole operation:
 
 ```ts
@@ -230,6 +323,11 @@ const memories = await client.recall({
 });
 ```
 
+Successful recall results include the access metadata written by that call:
+`accessCount`, `lastAccessedAt`, and `updatedAt` match stored state when the
+promise resolves. Ranking and score explanations use the count from before the
+current recall so the access update cannot change its own ordering.
+
 ### `buildContext`
 
 ```ts
@@ -241,8 +339,35 @@ const context = await client.buildContext({
 });
 ```
 
+Plain-text context uses a deterministic `=` fence longer than any `=` run in
+the query, rendered metadata, or included memory content. The resulting
+`MEMORY N START/END` boundaries cannot be reproduced by untrusted content.
+Markdown continues to choose a content-safe backtick fence, and XML continues
+to escape content.
+
 When supplied, `maxTokens` must be a positive integer or `buildContext` rejects
-with `"VALIDATION"`. Omitting it keeps the default token-budget path.
+with `"VALIDATION"`. Omitting it keeps the default token-budget path. Returned
+context always fits the supplied counter and budget; when an extremely small
+budget cannot fit the full truncation marker, the result is the longest marker
+fragment that fits or an empty string.
+
+### `forget` and `forgetAll`
+
+```ts
+await client.forget({
+  entityId: "user_123",
+  memoryId: "mem_old",
+});
+
+await client.forgetAll({ entityId: "user_123" });
+```
+
+A memory cannot be deleted while another memory's `supersededBy` still points
+to it as a consolidation survivor. `forget` and `forgetAll` reject with
+`"CONFLICT"` before deleting anything in that case. This also applies when
+`forgetAll` selects both the survivor and its superseded dependent. Delete the
+superseded memories first; deleting a loser, or any memory with no dependents,
+continues to work normally.
 
 ### `prune`
 
@@ -259,6 +384,23 @@ await client.prune({
 });
 ```
 
+Prune selectors are validated and normalized before either backend is called.
+Dates must be valid `Date` instances, enum values must be known, arrays must
+contain valid values, and boolean fields must be actual booleans. `false`
+selector flags and empty selector arrays do not count toward the required
+selector; malformed or selector-free input rejects with `"VALIDATION"` without
+deleting anything. Tag selectors are trimmed and deduplicated.
+
+A dry run may preview a survivor among its matches. A non-dry-run prune rejects
+with `"CONFLICT"` if any matching memory still has consolidation dependents,
+and the entire prune batch remains unchanged; unrelated matching rows are not
+partially deleted.
+
+When audit logging is enabled, every successful non-dry prune writes one
+best-effort `"memory.pruned"` event per affected entity, including global
+prunes without an `entityId`. Dry runs and zero-deletion runs do not write prune
+events.
+
 ### `findDuplicates`
 
 ```ts
@@ -269,6 +411,10 @@ const pairs = await client.findDuplicates({
 });
 ```
 
+The in-memory implementation compares memory pairs quadratically. It degrades
+noticeably once an entity grows beyond roughly a few thousand memories, so use
+the Postgres backend for duplicate detection beyond that scale.
+
 ### `listAuditLog`
 
 ```ts
@@ -281,8 +427,24 @@ const events = await client.listAuditLog({
   entityId: "user_123",
   limit: 100,
 });
+
+const last = events.at(-1);
+const nextPage = last
+  ? await client.listAuditLog({
+      entityId: "user_123",
+      limit: 100,
+      beforeCursor: { timestamp: last.timestamp, id: last.id },
+    })
+  : [];
 ```
 
+Audit entries are ordered newest first by timestamp and event ID. The
+experimental composite `beforeCursor` / `afterCursor` fields provide stable
+pagination when multiple events share a timestamp. The existing `before` and
+`after` fields remain strict timestamp filters; they exclude all events at the
+boundary timestamp and should not be used as the sole cursor when complete
+tie-safe pagination is required.
+
 Ordinary audit writes are best-effort: an audit storage failure does not fail
 the primary client operation, so `listAuditLog` returns only events that were
 successfully persisted. Postgres consolidation is the exception; its
@@ -299,6 +461,26 @@ await client.experimental.consolidate({
 });
 ```
 
+Consolidation records each loser's `supersededBy` reference to the survivor.
+Retrying the same loser with that same survivor is an idempotent no-op. If any
+requested loser already points to a different survivor, the call rejects with
+`"CONFLICT"`. Mixed batches are atomic: no newly eligible loser is changed, no
+tags are merged, and no consolidation audit event is written when any item
+conflicts. Concurrent calls follow the same target-specific rule in both
+backends. `supersededIds` must contain distinct IDs; duplicates reject with
+`"VALIDATION"` before either store is accessed.
+
+The store re-reads and protects the survivor in the same atomic boundary as
+the loser updates, tag merge, and enabled audit events. If the survivor is
+deleted or becomes superseded after initial validation but before that
+boundary, the call rejects with `"CONFLICT"` without a partial mutation. Tag
+merges start from the survivor's state inside that boundary, so concurrent
+successful consolidations preserve every committed tag.
+
+The survivor cannot later be deleted while any such reference remains:
+`forget`, `forgetAll`, and matching non-dry-run `prune` calls reject with
+`"CONFLICT"`. Deleting a superseded loser remains allowed.
+
 The `experimental` namespace may change before v1.0.
 
 ## Provider Resilience
@@ -315,6 +497,12 @@ const client = createMnemocyte({
 });
 ```
 
+Provider resilience values are validated synchronously when the client is
+created. Timeouts and delays must be finite non-negative numbers, retries must
+be a non-negative integer, and `shouldRetry` must be a function when supplied;
+invalid values throw `"CONFIG"`. A `maxDelayMs` below `baseDelayMs` remains
+valid and is normalized up to the base delay.
+
 Pass `signal` to cancel an operation:
 
 ```ts
@@ -327,6 +515,17 @@ await client.remember({
 });
 ```
 
+Pre-aborted signals reject with `"ABORTED"` before storage work begins.
+In-memory maintenance scans check cancellation cooperatively. For Postgres,
+standalone prune, duplicate-search, and audit-log queries request postgres.js
+query cancellation while they are in flight.
+
+Postgres consolidation has a transaction-specific boundary: cancellation is
+checked between mutation steps and immediately before the transaction callback
+returns. If a statement is already in flight, it may finish before the next
+check throws and rolls the transaction back. An abort after the final check,
+including while commit is in flight, may still leave the mutation committed.
+
 Common `MnemocyteError` codes:
 
 ```txt
@@ -337,6 +536,7 @@ VALIDATION
 CONFIG
 DB
 NOT_FOUND
+CONFLICT
 MIGRATION
 ```
 
@@ -367,12 +567,51 @@ must be positive finite numbers, and `candidateMultiplier` must be an integer
 of at least 1. Invalid tuning is rejected at client construction with
 `MnemocyteError` code `"CONFIG"`.
 
+## Storage Adapter Contract
+
+`MemoryStore` is still an internal boundary rather than a public package
+export, but its future-adapter contract is now documented directly in
+[`src/memory/store.ts`](./src/memory/store.ts). The contract is based on
+postconditions, not identical implementation mechanics: every method is
+mandatory, and no capability-flag surface exists or is currently planned.
+
+For adapter implementers, the main rules are:
+
+- `ensureSchema` is a readiness hook, not permission for hidden schema
+  creation. `ensureEmbeddingCompatibility` unconditionally enforces whatever
+  compatibility is meaningful to the persistence model; a store without
+  persistent installation state may no-op.
+- `insertMemories` takes ownership of prepared rows and returns exactly one
+  detached record per prepared ID. Store return order is untrusted; shared
+  orchestration rejects missing, duplicate, or unknown IDs and restores input
+  order. `getMemoryEmbeddings`, `getMemory`, and `stats` use the exact keyed,
+  detached, and count postconditions described in the source comments.
+- `markMemoriesAccessed` requires distinct IDs and returns the committed
+  post-update access fields. Duplicate-ID behavior is intentionally not a
+  portable contract. Ordinary `addAuditEvents` calls are best-effort, and a
+  rejected batch may have partially persisted on some backends.
+- `listAuditLog` uses stable event IDs, comparable timestamps, strict tuple
+  filters, and matching newest-first `(timestamp, id)` order. Tuple pagination
+  needs no transaction. Cancellation may be cooperative or active depending on
+  the implementation.
+- `vectorSearch` may scan or use an approximate, planner-dependent index.
+  `lexicalSearch` may legitimately return different candidates and rankings
+  across implementations. `findDuplicatePairs` compares qualifying memories
+  pairwise and does not imply indexed nearest-neighbor pair generation.
+- `deleteMemory`, `deleteMemoriesForEntity`, and non-dry-run `prune` must
+  protect referenced consolidation survivors with one atomic,
+  non-interleavable check-and-mutate operation and reject with `"CONFLICT"`
+  before any deletion. Other cancellation boundaries remain method- and
+  implementation-specific as documented by the public operations.
+- `close` releases or destroys only implementation-owned state and resources.
+  A future adapter around a caller-supplied connection must not close that
+  connection.
+
 ## Roadmap
 
 Planned larger milestones:
 
 - public `MemoryStore` adapter surface
-- `drizzleStore(db)` for caller-owned Drizzle clients
 - `@mnemocyte/mcp`
 
 See [ROADMAP.md](./docs/ROADMAP.md).
@@ -381,11 +620,15 @@ See [ROADMAP.md](./docs/ROADMAP.md).
 
 Current behavior:
 
-- `createMnemocyte()` selects either the in-memory backend or the
-  Postgres/pgvector backend.
+- `createMnemocyte()` selects an explicitly supplied `store`, the URL-owned
+  Postgres/pgvector backend, or the in-memory backend; supplying both `store`
+  and `databaseUrl` rejects instead of selecting a precedence.
 - Both backends run through an internal `MemoryStore` boundary and shared
   client orchestration; `MemoryStore` is not exported as a public adapter API
   yet.
+- `mnemocyte/stores/drizzle` exposes the first supported public adapter factory
+  for a caller-owned postgres.js Drizzle instance without exporting the full
+  `MemoryStore` contract.
 - Postgres schema setup is explicit; the client does not create tables or
   indexes for you.
 - `findDuplicates`, audit-log workflows, and `experimental.consolidate` are
@@ -394,12 +637,13 @@ Current behavior:
 Known limitations before v1:
 
 - The internal `MemoryStore` boundary is not a public adapter API yet.
-  `drizzleStore(db)` is the planned first public store adapter.
+  `drizzleStore(db)` returns an opaque config value and currently supports only
+  postgres.js, the `public` schema, and pre-applied Mnemocyte migrations.
 - Configured provider timeouts abort the per-attempt `AbortSignal`; the
   underlying provider request only stops promptly when the embedder honors that
   signal.
-- Postgres dimension metadata is installation-wide. Mixed embedding dimensions
-  in one database are intentionally out of scope for now.
+- Postgres model and dimension metadata are installation-wide. Mixed embedding
+  vector spaces in one database are intentionally unsupported.
 
 Planned v1 direction:
 

package/dist/embedders/openai.d.mts

@@ -1,4 +1,4 @@
-import { c as Embedder } from "../types-gOPLre4V.mjs";
+import { l as Embedder } from "../types-XUWYDoXM.mjs";
 
 //#region src/embedders/openai.d.ts
 interface OpenAIEmbedderOptions {

package/dist/embedders/openai.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"openai.d.mts","names":[],"sources":["../../src/embedders/openai.ts"],"mappings":";;;UAciB,qBAAA;;AAAjB;;WAIU,MAAA;EAJ4B;;;EAAA,SAQ5B,KAAA;EAUA;;AAAO;AA4EjB;EA5EU,SALA,UAAA;;;;;WAKA,OAAA;AAAA;AA4E8D;;;;AAAA,iBAAxD,cAAA,CAAe,OAAA,EAAS,qBAAA,GAAwB,QAAQ"}
+{"version":3,"file":"openai.d.mts","names":[],"sources":["../../src/embedders/openai.ts"],"mappings":";;;UAciB,qBAAA;;AAAjB;;WAIU,MAAA;EAJ4B;;;EAAA,SAQ5B,KAAA;EAUA;;AAAO;AAoIjB;EApIU,SALA,UAAA;;;;;WAKA,OAAA;AAAA;AAoI8D;;;;AAAA,iBAAxD,cAAA,CAAe,OAAA,EAAS,qBAAA,GAAwB,QAAQ"}

package/dist/embedders/openai.mjs

@@ -1,4 +1,4 @@
-import { t as MnemocyteError } from "../errors-B_7ZdjEO.mjs";
+import { t as MnemocyteError } from "../errors-DIPysVWl.mjs";
 //#region src/embedders/openai.ts
 const KNOWN_MODEL_DIMENSIONS = {
 	"text-embedding-3-small": 1536,
@@ -6,6 +6,28 @@ const KNOWN_MODEL_DIMENSIONS = {
 	"text-embedding-ada-002": 1536
 };
 const CONFIGURABLE_DIMENSION_MODELS = new Set(["text-embedding-3-small", "text-embedding-3-large"]);
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validateEmbeddingResponse(body, expectedCount) {
+	if (!isRecord(body) || !Array.isArray(body.data)) throw new MnemocyteError("OpenAI returned malformed embedding response data.", "EMBEDDING");
+	if (body.data.length !== expectedCount) throw new MnemocyteError("OpenAI returned an unexpected number of embeddings.", "EMBEDDING");
+	const indices = /* @__PURE__ */ new Set();
+	const items = [];
+	for (const item of body.data) {
+		if (!isRecord(item)) throw new MnemocyteError("OpenAI returned a malformed embedding item.", "EMBEDDING");
+		const { embedding, index } = item;
+		if (typeof index !== "number" || !Number.isInteger(index) || index < 0 || index >= expectedCount) throw new MnemocyteError("OpenAI returned an embedding with an invalid index.", "EMBEDDING");
+		if (indices.has(index)) throw new MnemocyteError("OpenAI returned a duplicate embedding index.", "EMBEDDING");
+		if (!Array.isArray(embedding)) throw new MnemocyteError("OpenAI returned an embedding that is not an array.", "EMBEDDING");
+		indices.add(index);
+		items.push({
+			embedding,
+			index
+		});
+	}
+	return items;
+}
 function assertDimensions(dimensions) {
 	if (!Number.isInteger(dimensions) || dimensions < 1) throw new MnemocyteError("openaiEmbedder dimensions must be a positive integer.", "CONFIG");
 }
@@ -61,14 +83,7 @@ function openaiEmbedder(options) {
 				...embedOptions?.signal === void 0 ? {} : { signal: embedOptions.signal }
 			});
 			if (!response.ok) throw Object.assign(/* @__PURE__ */ new Error(`OpenAI embeddings request failed with status ${response.status}.`), { status: response.status });
-			const body = await response.json();
-			const embeddings = Array.from({ length: texts.length });
-			for (const item of body.data) {
-				if (!Number.isInteger(item.index) || item.index < 0 || item.index >= texts.length) throw new MnemocyteError("OpenAI returned an embedding with an invalid index.", "EMBEDDING");
-				embeddings[item.index] = item.embedding;
-			}
-			if (embeddings.some((embedding) => embedding === void 0)) throw new MnemocyteError("OpenAI returned fewer embeddings than requested.", "EMBEDDING");
-			return embeddings;
+			return validateEmbeddingResponse(await response.json(), texts.length).sort((left, right) => left.index - right.index).map((item) => item.embedding);
 		}
 	};
 }

package/dist/embedders/openai.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"openai.mjs","names":[],"sources":["../../src/embedders/openai.ts"],"sourcesContent":["import { MnemocyteError } from \"../errors.js\";\nimport type { Embedder } from \"../types.js\";\n\nconst KNOWN_MODEL_DIMENSIONS: Record<string, number> = {\n\t\"text-embedding-3-small\": 1536,\n\t\"text-embedding-3-large\": 3072,\n\t\"text-embedding-ada-002\": 1536,\n};\n\nconst CONFIGURABLE_DIMENSION_MODELS = new Set([\n\t\"text-embedding-3-small\",\n\t\"text-embedding-3-large\",\n]);\n\nexport interface OpenAIEmbedderOptions {\n\t/**\n\t * OpenAI API key. Defaults to `process.env.OPENAI_API_KEY`.\n\t */\n\treadonly apiKey?: string;\n\t/**\n\t * OpenAI embedding model name.\n\t */\n\treadonly model: string;\n\t/**\n\t * Output dimensions. Required for unknown/future model names and accepted\n\t * only for OpenAI models that support configurable dimensions.\n\t */\n\treadonly dimensions?: number;\n\t/**\n\t * Override the OpenAI API base URL. Intended for tests and compatible\n\t * deployments; defaults to `https://api.openai.com/v1`.\n\t */\n\treadonly baseUrl?: string;\n}\n\ninterface OpenAIEmbeddingItem {\n\treadonly embedding: number[];\n\treadonly index: number;\n}\n\ninterface OpenAIEmbeddingResponse {\n\treadonly data: OpenAIEmbeddingItem[];\n}\n\nfunction assertDimensions(dimensions: number): void {\n\tif (!Number.isInteger(dimensions) || dimensions < 1) {\n\t\tthrow new MnemocyteError(\n\t\t\t\"openaiEmbedder dimensions must be a positive integer.\",\n\t\t\t\"CONFIG\",\n\t\t);\n\t}\n}\n\nfunction resolveApiKey(apiKey: string | undefined): string {\n\tconst resolved = apiKey ?? process.env.OPENAI_API_KEY;\n\tif (!resolved || resolved.trim().length === 0) {\n\t\tthrow new MnemocyteError(\n\t\t\t\"openaiEmbedder requires an API key. Pass apiKey or set OPENAI_API_KEY.\",\n\t\t\t\"CONFIG\",\n\t\t);\n\t}\n\treturn resolved;\n}\n\nfunction resolveDimensions(options: OpenAIEmbedderOptions): {\n\tembedderDimensions: number;\n\trequestDimensions?: number;\n} {\n\tconst defaultDimensions = KNOWN_MODEL_DIMENSIONS[options.model];\n\tif (defaultDimensions === undefined) {\n\t\tif (options.dimensions === undefined) {\n\t\t\tthrow new MnemocyteError(\n\t\t\t\t`openaiEmbedder requires dimensions for unknown model \"${options.model}\".`,\n\t\t\t\t\"CONFIG\",\n\t\t\t);\n\t\t}\n\t\tassertDimensions(options.dimensions);\n\t\treturn {\n\t\t\tembedderDimensions: options.dimensions,\n\t\t\trequestDimensions: options.dimensions,\n\t\t};\n\t}\n\n\tif (\n\t\toptions.dimensions !== undefined &&\n\t\t!CONFIGURABLE_DIMENSION_MODELS.has(options.model)\n\t) {\n\t\tthrow new MnemocyteError(\n\t\t\t`openaiEmbedder does not support a dimensions override for \"${options.model}\".`,\n\t\t\t\"CONFIG\",\n\t\t);\n\t}\n\n\tif (options.dimensions !== undefined) {\n\t\tassertDimensions(options.dimensions);\n\t\treturn {\n\t\t\tembedderDimensions: options.dimensions,\n\t\t\trequestDimensions: options.dimensions,\n\t\t};\n\t}\n\n\treturn { embedderDimensions: defaultDimensions };\n}\n\n/**\n * Create an OpenAI-backed {@link Embedder}. This adapter uses `fetch`\n * directly so provider SDKs never become part of Mnemocyte's dependency graph.\n */\nexport function openaiEmbedder(options: OpenAIEmbedderOptions): Embedder {\n\tconst apiKey = resolveApiKey(options.apiKey);\n\tconst { embedderDimensions, requestDimensions } = resolveDimensions(options);\n\tconst baseUrl = options.baseUrl ?? \"https://api.openai.com/v1\";\n\n\treturn {\n\t\tmodel: options.model,\n\t\tdimensions: embedderDimensions,\n\t\tasync embed(texts, embedOptions) {\n\t\t\tconst response = await fetch(`${baseUrl}/embeddings`, {\n\t\t\t\tmethod: \"POST\",\n\t\t\t\theaders: {\n\t\t\t\t\tauthorization: `Bearer ${apiKey}`,\n\t\t\t\t\t\"content-type\": \"application/json\",\n\t\t\t\t},\n\t\t\t\tbody: JSON.stringify({\n\t\t\t\t\tmodel: options.model,\n\t\t\t\t\tinput: [...texts],\n\t\t\t\t\tencoding_format: \"float\",\n\t\t\t\t\t...(requestDimensions === undefined\n\t\t\t\t\t\t? {}\n\t\t\t\t\t\t: { dimensions: requestDimensions }),\n\t\t\t\t}),\n\t\t\t\t...(embedOptions?.signal === undefined\n\t\t\t\t\t? {}\n\t\t\t\t\t: { signal: embedOptions.signal }),\n\t\t\t});\n\n\t\t\tif (!response.ok) {\n\t\t\t\tthrow Object.assign(\n\t\t\t\t\tnew Error(\n\t\t\t\t\t\t`OpenAI embeddings request failed with status ${response.status}.`,\n\t\t\t\t\t),\n\t\t\t\t\t{ status: response.status },\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tconst body = (await response.json()) as OpenAIEmbeddingResponse;\n\n\t\t\tconst embeddings: Array<number[] | undefined> = Array.from({\n\t\t\t\tlength: texts.length,\n\t\t\t});\n\t\t\tfor (const item of body.data) {\n\t\t\t\tif (\n\t\t\t\t\t!Number.isInteger(item.index) ||\n\t\t\t\t\titem.index < 0 ||\n\t\t\t\t\titem.index >= texts.length\n\t\t\t\t) {\n\t\t\t\t\tthrow new MnemocyteError(\n\t\t\t\t\t\t\"OpenAI returned an embedding with an invalid index.\",\n\t\t\t\t\t\t\"EMBEDDING\",\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tembeddings[item.index] = item.embedding;\n\t\t\t}\n\t\t\tif (embeddings.some((embedding) => embedding === undefined)) {\n\t\t\t\tthrow new MnemocyteError(\n\t\t\t\t\t\"OpenAI returned fewer embeddings than requested.\",\n\t\t\t\t\t\"EMBEDDING\",\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn embeddings as number[][];\n\t\t},\n\t};\n}\n"],"mappings":";;AAGA,MAAM,yBAAiD;CACtD,0BAA0B;CAC1B,0BAA0B;CAC1B,0BAA0B;AAC3B;AAEA,MAAM,gCAAgC,IAAI,IAAI,CAC7C,0BACA,wBACD,CAAC;AAgCD,SAAS,iBAAiB,YAA0B;CACnD,IAAI,CAAC,OAAO,UAAU,UAAU,KAAK,aAAa,GACjD,MAAM,IAAI,eACT,yDACA,QACD;AAEF;AAEA,SAAS,cAAc,QAAoC;CAC1D,MAAM,WAAW,UAAU,QAAQ,IAAI;CACvC,IAAI,CAAC,YAAY,SAAS,KAAK,EAAE,WAAW,GAC3C,MAAM,IAAI,eACT,0EACA,QACD;CAED,OAAO;AACR;AAEA,SAAS,kBAAkB,SAGzB;CACD,MAAM,oBAAoB,uBAAuB,QAAQ;CACzD,IAAI,sBAAsB,KAAA,GAAW;EACpC,IAAI,QAAQ,eAAe,KAAA,GAC1B,MAAM,IAAI,eACT,yDAAyD,QAAQ,MAAM,KACvE,QACD;EAED,iBAAiB,QAAQ,UAAU;EACnC,OAAO;GACN,oBAAoB,QAAQ;GAC5B,mBAAmB,QAAQ;EAC5B;CACD;CAEA,IACC,QAAQ,eAAe,KAAA,KACvB,CAAC,8BAA8B,IAAI,QAAQ,KAAK,GAEhD,MAAM,IAAI,eACT,8DAA8D,QAAQ,MAAM,KAC5E,QACD;CAGD,IAAI,QAAQ,eAAe,KAAA,GAAW;EACrC,iBAAiB,QAAQ,UAAU;EACnC,OAAO;GACN,oBAAoB,QAAQ;GAC5B,mBAAmB,QAAQ;EAC5B;CACD;CAEA,OAAO,EAAE,oBAAoB,kBAAkB;AAChD;;;;;AAMA,SAAgB,eAAe,SAA0C;CACxE,MAAM,SAAS,cAAc,QAAQ,MAAM;CAC3C,MAAM,EAAE,oBAAoB,sBAAsB,kBAAkB,OAAO;CAC3E,MAAM,UAAU,QAAQ,WAAW;CAEnC,OAAO;EACN,OAAO,QAAQ;EACf,YAAY;EACZ,MAAM,MAAM,OAAO,cAAc;GAChC,MAAM,WAAW,MAAM,MAAM,GAAG,QAAQ,cAAc;IACrD,QAAQ;IACR,SAAS;KACR,eAAe,UAAU;KACzB,gBAAgB;IACjB;IACA,MAAM,KAAK,UAAU;KACpB,OAAO,QAAQ;KACf,OAAO,CAAC,GAAG,KAAK;KAChB,iBAAiB;KACjB,GAAI,sBAAsB,KAAA,IACvB,CAAC,IACD,EAAE,YAAY,kBAAkB;IACpC,CAAC;IACD,GAAI,cAAc,WAAW,KAAA,IAC1B,CAAC,IACD,EAAE,QAAQ,aAAa,OAAO;GAClC,CAAC;GAED,IAAI,CAAC,SAAS,IACb,MAAM,OAAO,uBACZ,IAAI,MACH,gDAAgD,SAAS,OAAO,EACjE,GACA,EAAE,QAAQ,SAAS,OAAO,CAC3B;GAGD,MAAM,OAAQ,MAAM,SAAS,KAAK;GAElC,MAAM,aAA0C,MAAM,KAAK,EAC1D,QAAQ,MAAM,OACf,CAAC;GACD,KAAK,MAAM,QAAQ,KAAK,MAAM;IAC7B,IACC,CAAC,OAAO,UAAU,KAAK,KAAK,KAC5B,KAAK,QAAQ,KACb,KAAK,SAAS,MAAM,QAEpB,MAAM,IAAI,eACT,uDACA,WACD;IAED,WAAW,KAAK,SAAS,KAAK;GAC/B;GACA,IAAI,WAAW,MAAM,cAAc,cAAc,KAAA,CAAS,GACzD,MAAM,IAAI,eACT,oDACA,WACD;GAED,OAAO;EACR;CACD;AACD"}
+{"version":3,"file":"openai.mjs","names":[],"sources":["../../src/embedders/openai.ts"],"sourcesContent":["import { MnemocyteError } from \"../errors.js\";\nimport type { Embedder } from \"../types.js\";\n\nconst KNOWN_MODEL_DIMENSIONS: Record<string, number> = {\n\t\"text-embedding-3-small\": 1536,\n\t\"text-embedding-3-large\": 3072,\n\t\"text-embedding-ada-002\": 1536,\n};\n\nconst CONFIGURABLE_DIMENSION_MODELS = new Set([\n\t\"text-embedding-3-small\",\n\t\"text-embedding-3-large\",\n]);\n\nexport interface OpenAIEmbedderOptions {\n\t/**\n\t * OpenAI API key. Defaults to `process.env.OPENAI_API_KEY`.\n\t */\n\treadonly apiKey?: string;\n\t/**\n\t * OpenAI embedding model name.\n\t */\n\treadonly model: string;\n\t/**\n\t * Output dimensions. Required for unknown/future model names and accepted\n\t * only for OpenAI models that support configurable dimensions.\n\t */\n\treadonly dimensions?: number;\n\t/**\n\t * Override the OpenAI API base URL. Intended for tests and compatible\n\t * deployments; defaults to `https://api.openai.com/v1`.\n\t */\n\treadonly baseUrl?: string;\n}\n\ninterface OpenAIEmbeddingItem {\n\treadonly embedding: number[];\n\treadonly index: number;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction validateEmbeddingResponse(\n\tbody: unknown,\n\texpectedCount: number,\n): OpenAIEmbeddingItem[] {\n\tif (!isRecord(body) || !Array.isArray(body.data)) {\n\t\tthrow new MnemocyteError(\n\t\t\t\"OpenAI returned malformed embedding response data.\",\n\t\t\t\"EMBEDDING\",\n\t\t);\n\t}\n\tif (body.data.length !== expectedCount) {\n\t\tthrow new MnemocyteError(\n\t\t\t\"OpenAI returned an unexpected number of embeddings.\",\n\t\t\t\"EMBEDDING\",\n\t\t);\n\t}\n\n\tconst indices = new Set<number>();\n\tconst items: OpenAIEmbeddingItem[] = [];\n\tfor (const item of body.data) {\n\t\tif (!isRecord(item)) {\n\t\t\tthrow new MnemocyteError(\n\t\t\t\t\"OpenAI returned a malformed embedding item.\",\n\t\t\t\t\"EMBEDDING\",\n\t\t\t);\n\t\t}\n\t\tconst { embedding, index } = item;\n\t\tif (\n\t\t\ttypeof index !== \"number\" ||\n\t\t\t!Number.isInteger(index) ||\n\t\t\tindex < 0 ||\n\t\t\tindex >= expectedCount\n\t\t) {\n\t\t\tthrow new MnemocyteError(\n\t\t\t\t\"OpenAI returned an embedding with an invalid index.\",\n\t\t\t\t\"EMBEDDING\",\n\t\t\t);\n\t\t}\n\t\tif (indices.has(index)) {\n\t\t\tthrow new MnemocyteError(\n\t\t\t\t\"OpenAI returned a duplicate embedding index.\",\n\t\t\t\t\"EMBEDDING\",\n\t\t\t);\n\t\t}\n\t\tif (!Array.isArray(embedding)) {\n\t\t\tthrow new MnemocyteError(\n\t\t\t\t\"OpenAI returned an embedding that is not an array.\",\n\t\t\t\t\"EMBEDDING\",\n\t\t\t);\n\t\t}\n\t\tindices.add(index);\n\t\titems.push({ embedding: embedding as number[], index });\n\t}\n\treturn items;\n}\n\nfunction assertDimensions(dimensions: number): void {\n\tif (!Number.isInteger(dimensions) || dimensions < 1) {\n\t\tthrow new MnemocyteError(\n\t\t\t\"openaiEmbedder dimensions must be a positive integer.\",\n\t\t\t\"CONFIG\",\n\t\t);\n\t}\n}\n\nfunction resolveApiKey(apiKey: string | undefined): string {\n\tconst resolved = apiKey ?? process.env.OPENAI_API_KEY;\n\tif (!resolved || resolved.trim().length === 0) {\n\t\tthrow new MnemocyteError(\n\t\t\t\"openaiEmbedder requires an API key. Pass apiKey or set OPENAI_API_KEY.\",\n\t\t\t\"CONFIG\",\n\t\t);\n\t}\n\treturn resolved;\n}\n\nfunction resolveDimensions(options: OpenAIEmbedderOptions): {\n\tembedderDimensions: number;\n\trequestDimensions?: number;\n} {\n\tconst defaultDimensions = KNOWN_MODEL_DIMENSIONS[options.model];\n\tif (defaultDimensions === undefined) {\n\t\tif (options.dimensions === undefined) {\n\t\t\tthrow new MnemocyteError(\n\t\t\t\t`openaiEmbedder requires dimensions for unknown model \"${options.model}\".`,\n\t\t\t\t\"CONFIG\",\n\t\t\t);\n\t\t}\n\t\tassertDimensions(options.dimensions);\n\t\treturn {\n\t\t\tembedderDimensions: options.dimensions,\n\t\t\trequestDimensions: options.dimensions,\n\t\t};\n\t}\n\n\tif (\n\t\toptions.dimensions !== undefined &&\n\t\t!CONFIGURABLE_DIMENSION_MODELS.has(options.model)\n\t) {\n\t\tthrow new MnemocyteError(\n\t\t\t`openaiEmbedder does not support a dimensions override for \"${options.model}\".`,\n\t\t\t\"CONFIG\",\n\t\t);\n\t}\n\n\tif (options.dimensions !== undefined) {\n\t\tassertDimensions(options.dimensions);\n\t\treturn {\n\t\t\tembedderDimensions: options.dimensions,\n\t\t\trequestDimensions: options.dimensions,\n\t\t};\n\t}\n\n\treturn { embedderDimensions: defaultDimensions };\n}\n\n/**\n * Create an OpenAI-backed {@link Embedder}. This adapter uses `fetch`\n * directly so provider SDKs never become part of Mnemocyte's dependency graph.\n */\nexport function openaiEmbedder(options: OpenAIEmbedderOptions): Embedder {\n\tconst apiKey = resolveApiKey(options.apiKey);\n\tconst { embedderDimensions, requestDimensions } = resolveDimensions(options);\n\tconst baseUrl = options.baseUrl ?? \"https://api.openai.com/v1\";\n\n\treturn {\n\t\tmodel: options.model,\n\t\tdimensions: embedderDimensions,\n\t\tasync embed(texts, embedOptions) {\n\t\t\tconst response = await fetch(`${baseUrl}/embeddings`, {\n\t\t\t\tmethod: \"POST\",\n\t\t\t\theaders: {\n\t\t\t\t\tauthorization: `Bearer ${apiKey}`,\n\t\t\t\t\t\"content-type\": \"application/json\",\n\t\t\t\t},\n\t\t\t\tbody: JSON.stringify({\n\t\t\t\t\tmodel: options.model,\n\t\t\t\t\tinput: [...texts],\n\t\t\t\t\tencoding_format: \"float\",\n\t\t\t\t\t...(requestDimensions === undefined\n\t\t\t\t\t\t? {}\n\t\t\t\t\t\t: { dimensions: requestDimensions }),\n\t\t\t\t}),\n\t\t\t\t...(embedOptions?.signal === undefined\n\t\t\t\t\t? {}\n\t\t\t\t\t: { signal: embedOptions.signal }),\n\t\t\t});\n\n\t\t\tif (!response.ok) {\n\t\t\t\tthrow Object.assign(\n\t\t\t\t\tnew Error(\n\t\t\t\t\t\t`OpenAI embeddings request failed with status ${response.status}.`,\n\t\t\t\t\t),\n\t\t\t\t\t{ status: response.status },\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tconst items = validateEmbeddingResponse(\n\t\t\t\tawait response.json(),\n\t\t\t\ttexts.length,\n\t\t\t);\n\t\t\treturn items\n\t\t\t\t.sort((left, right) => left.index - right.index)\n\t\t\t\t.map((item) => item.embedding);\n\t\t},\n\t};\n}\n"],"mappings":";;AAGA,MAAM,yBAAiD;CACtD,0BAA0B;CAC1B,0BAA0B;CAC1B,0BAA0B;AAC3B;AAEA,MAAM,gCAAgC,IAAI,IAAI,CAC7C,0BACA,wBACD,CAAC;AA4BD,SAAS,SAAS,OAAkD;CACnE,OAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC3E;AAEA,SAAS,0BACR,MACA,eACwB;CACxB,IAAI,CAAC,SAAS,IAAI,KAAK,CAAC,MAAM,QAAQ,KAAK,IAAI,GAC9C,MAAM,IAAI,eACT,sDACA,WACD;CAED,IAAI,KAAK,KAAK,WAAW,eACxB,MAAM,IAAI,eACT,uDACA,WACD;CAGD,MAAM,0BAAU,IAAI,IAAY;CAChC,MAAM,QAA+B,CAAC;CACtC,KAAK,MAAM,QAAQ,KAAK,MAAM;EAC7B,IAAI,CAAC,SAAS,IAAI,GACjB,MAAM,IAAI,eACT,+CACA,WACD;EAED,MAAM,EAAE,WAAW,UAAU;EAC7B,IACC,OAAO,UAAU,YACjB,CAAC,OAAO,UAAU,KAAK,KACvB,QAAQ,KACR,SAAS,eAET,MAAM,IAAI,eACT,uDACA,WACD;EAED,IAAI,QAAQ,IAAI,KAAK,GACpB,MAAM,IAAI,eACT,gDACA,WACD;EAED,IAAI,CAAC,MAAM,QAAQ,SAAS,GAC3B,MAAM,IAAI,eACT,sDACA,WACD;EAED,QAAQ,IAAI,KAAK;EACjB,MAAM,KAAK;GAAa;GAAuB;EAAM,CAAC;CACvD;CACA,OAAO;AACR;AAEA,SAAS,iBAAiB,YAA0B;CACnD,IAAI,CAAC,OAAO,UAAU,UAAU,KAAK,aAAa,GACjD,MAAM,IAAI,eACT,yDACA,QACD;AAEF;AAEA,SAAS,cAAc,QAAoC;CAC1D,MAAM,WAAW,UAAU,QAAQ,IAAI;CACvC,IAAI,CAAC,YAAY,SAAS,KAAK,EAAE,WAAW,GAC3C,MAAM,IAAI,eACT,0EACA,QACD;CAED,OAAO;AACR;AAEA,SAAS,kBAAkB,SAGzB;CACD,MAAM,oBAAoB,uBAAuB,QAAQ;CACzD,IAAI,sBAAsB,KAAA,GAAW;EACpC,IAAI,QAAQ,eAAe,KAAA,GAC1B,MAAM,IAAI,eACT,yDAAyD,QAAQ,MAAM,KACvE,QACD;EAED,iBAAiB,QAAQ,UAAU;EACnC,OAAO;GACN,oBAAoB,QAAQ;GAC5B,mBAAmB,QAAQ;EAC5B;CACD;CAEA,IACC,QAAQ,eAAe,KAAA,KACvB,CAAC,8BAA8B,IAAI,QAAQ,KAAK,GAEhD,MAAM,IAAI,eACT,8DAA8D,QAAQ,MAAM,KAC5E,QACD;CAGD,IAAI,QAAQ,eAAe,KAAA,GAAW;EACrC,iBAAiB,QAAQ,UAAU;EACnC,OAAO;GACN,oBAAoB,QAAQ;GAC5B,mBAAmB,QAAQ;EAC5B;CACD;CAEA,OAAO,EAAE,oBAAoB,kBAAkB;AAChD;;;;;AAMA,SAAgB,eAAe,SAA0C;CACxE,MAAM,SAAS,cAAc,QAAQ,MAAM;CAC3C,MAAM,EAAE,oBAAoB,sBAAsB,kBAAkB,OAAO;CAC3E,MAAM,UAAU,QAAQ,WAAW;CAEnC,OAAO;EACN,OAAO,QAAQ;EACf,YAAY;EACZ,MAAM,MAAM,OAAO,cAAc;GAChC,MAAM,WAAW,MAAM,MAAM,GAAG,QAAQ,cAAc;IACrD,QAAQ;IACR,SAAS;KACR,eAAe,UAAU;KACzB,gBAAgB;IACjB;IACA,MAAM,KAAK,UAAU;KACpB,OAAO,QAAQ;KACf,OAAO,CAAC,GAAG,KAAK;KAChB,iBAAiB;KACjB,GAAI,sBAAsB,KAAA,IACvB,CAAC,IACD,EAAE,YAAY,kBAAkB;IACpC,CAAC;IACD,GAAI,cAAc,WAAW,KAAA,IAC1B,CAAC,IACD,EAAE,QAAQ,aAAa,OAAO;GAClC,CAAC;GAED,IAAI,CAAC,SAAS,IACb,MAAM,OAAO,uBACZ,IAAI,MACH,gDAAgD,SAAS,OAAO,EACjE,GACA,EAAE,QAAQ,SAAS,OAAO,CAC3B;GAOD,OAJc,0BACb,MAAM,SAAS,KAAK,GACpB,MAAM,MAEI,EACT,MAAM,MAAM,UAAU,KAAK,QAAQ,MAAM,KAAK,EAC9C,KAAK,SAAS,KAAK,SAAS;EAC/B;CACD;AACD"}

package/dist/{errors-B_7ZdjEO.mjs → errors-DIPysVWl.mjs}

@@ -51,4 +51,4 @@ function isMnemocyteError(error) {
 //#endregion
 export { isMnemocyteError as n, MnemocyteError as t };
 
-//# sourceMappingURL=errors-B_7ZdjEO.mjs.map
+//# sourceMappingURL=errors-DIPysVWl.mjs.map

package/dist/errors-DIPysVWl.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors-DIPysVWl.mjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/**\n * Stable, machine-readable error code attached to every {@link MnemocyteError}.\n *\n * - `\"CONFIG\"` — invalid client configuration (e.g. missing or malformed embedder).\n * - `\"VALIDATION\"` — invalid argument passed to a client method.\n * - `\"DB\"` — Postgres or driver-level failure.\n * - `\"EMBEDDING\"` — embedder threw or returned an invalid vector.\n * - `\"NOT_FOUND\"` — referenced memory or entity does not exist.\n * - `\"CONFLICT\"` — the requested mutation conflicts with stored relationships.\n * - `\"MIGRATION\"` — schema/migration check failed against the target database.\n * - `\"TIMEOUT\"` — a provider call exceeded its configured timeout.\n * - `\"ABORTED\"` — the operation was cancelled via an `AbortSignal`.\n */\nexport type MnemocyteErrorCode =\n\t| \"CONFIG\"\n\t| \"VALIDATION\"\n\t| \"DB\"\n\t| \"EMBEDDING\"\n\t| \"NOT_FOUND\"\n\t| \"CONFLICT\"\n\t| \"MIGRATION\"\n\t| \"TIMEOUT\"\n\t| \"ABORTED\";\n\n/**\n * Error type thrown by every public Mnemocyte API.\n *\n * Use the {@link MnemocyteError.code} property — not the message — to branch\n * on failure modes, or call {@link isMnemocyteError} as a type guard when\n * working with `unknown` errors.\n *\n * @example\n * ```ts\n * try {\n *   await client.recall({ entityId: \"u1\", query: \"hi\" });\n * } catch (err) {\n *   if (isMnemocyteError(err) && err.code === \"DB\") {\n *     // handle database failure\n *   }\n *   throw err;\n * }\n * ```\n */\nexport class MnemocyteError extends Error {\n\t/** Stable, machine-readable failure code. See {@link MnemocyteErrorCode}. */\n\treadonly code: MnemocyteErrorCode;\n\t/** Underlying cause, if any (e.g. an original driver or embedder error). */\n\toverride readonly cause?: unknown;\n\n\t/**\n\t * @param message - Human-readable error message.\n\t * @param code - Stable failure code; see {@link MnemocyteErrorCode}.\n\t * @param cause - Optional underlying cause (driver error, network error, etc.).\n\t */\n\tconstructor(message: string, code: MnemocyteErrorCode, cause?: unknown) {\n\t\tsuper(message);\n\t\tthis.name = \"MnemocyteError\";\n\t\tthis.code = code;\n\t\tthis.cause = cause;\n\t}\n}\n\n/**\n * Type guard for {@link MnemocyteError}.\n *\n * This guard uses `instanceof` and recognizes errors created by the same loaded\n * Mnemocyte class. It does not recognize structurally similar errors or errors\n * created by another installed copy of the package.\n *\n * @param error - Value to test (typically a caught `unknown`).\n * @returns `true` if `error` is a {@link MnemocyteError}.\n */\nexport function isMnemocyteError(error: unknown): error is MnemocyteError {\n\treturn error instanceof MnemocyteError;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AA2CA,IAAa,iBAAb,cAAoC,MAAM;;CAEzC;;CAEA;;;;;;CAOA,YAAY,SAAiB,MAA0B,OAAiB;EACvE,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,OAAO;EACZ,KAAK,QAAQ;CACd;AACD;;;;;;;;;;;AAYA,SAAgB,iBAAiB,OAAyC;CACzE,OAAO,iBAAiB;AACzB"}

package/dist/index.d.mts

@@ -1,23 +1,26 @@
-import { A as RecallInput, C as MnemocyteObservation, D as ProviderResilienceConfig, E as ObservabilityConfig, F as RetrievalScoreWeights, I as RetrievalScores, L as TokenCounter, M as RememberManyInput, N as RetrievalConfig, O as PruneInput, P as RetrievalExplanation, S as MnemocyteConfig, T as MnemocyteOperation, _ as Memory, a as ConsolidateResult, b as MnemocyteBackend, c as Embedder, d as FindDuplicatesInput, f as GlobalStats, g as ListAuditLogInput, h as JsonValue, i as ConsolidateInput, j as RememberInput, k as PruneResult, l as EntityStats, m as JsonObject, n as AuditEvent, o as ContextFormat, p as ImportanceLevel, r as BuildContextInput, s as DuplicatePair, t as AuditConfig, u as ExperimentalMnemocyteClient, v as MemoryType, w as MnemocyteObservationPhase, x as MnemocyteClient, y as MemoryWithScore } from "./types-gOPLre4V.mjs";
+import { A as PruneInput, C as MnemocyteConfig, D as MnemocyteStoreConfig, E as MnemocyteOperation, F as RetrievalConfig, I as RetrievalExplanation, L as RetrievalScoreWeights, M as RecallInput, N as RememberInput, O as ObservabilityConfig, P as RememberManyInput, R as RetrievalScores, S as MnemocyteClient, T as MnemocyteObservationPhase, _ as ListAuditLogInput, a as ConsolidateInput, b as MemoryWithScore, c as DuplicatePair, d as ExperimentalMnemocyteClient, f as FindDuplicatesInput, g as JsonValue, h as JsonObject, i as BuildContextInput, j as PruneResult, k as ProviderResilienceConfig, l as Embedder, m as ImportanceLevel, n as AuditEvent, o as ConsolidateResult, p as GlobalStats, r as AuditLogCursor, s as ContextFormat, t as AuditConfig, u as EntityStats, v as Memory, w as MnemocyteObservation, x as MnemocyteBackend, y as MemoryType, z as TokenCounter } from "./types-XUWYDoXM.mjs";
 
 //#region src/client.d.ts
 /**
  * Create a Mnemocyte client.
  *
- * When {@link MnemocyteConfig.databaseUrl} is provided, a Postgres-backed
- * client is returned (requires the `pgvector` extension and the bundled
- * migration applied). Otherwise an in-memory client is returned, intended
- * for tests, demos, and short-lived processes.
+ * When {@link MnemocyteConfig.store} is provided, that adapter is used. When
+ * {@link MnemocyteConfig.databaseUrl} is provided, a URL-owned Postgres client
+ * is used (requires the `pgvector` extension and the bundled migrations).
+ * When neither is supplied, an in-memory client is returned for tests, demos,
+ * and short-lived processes.
  *
- * The returned client owns any underlying resources (e.g. the Postgres
- * connection pool). Call {@link MnemocyteClient.close} when finished to
- * release them.
+ * Call {@link MnemocyteClient.close} when finished. URL-created database
+ * resources are owned and closed by Mnemocyte; resources behind a supplied
+ * store retain the ownership policy documented by that adapter.
  *
  * @param config - Client configuration. {@link MnemocyteConfig.embedder} is required.
  * @returns A {@link MnemocyteClient} instance.
  * @throws {MnemocyteError} With code `"CONFIG"` if `embedder`, retrieval
- * tuning, or the database URL is malformed, or `"VALIDATION"` if
- * `databaseUrl` is explicitly empty.
+ * tuning, provider resilience, or the database URL is malformed or does not
+ * use the `postgres:` / `postgresql:` protocol, or if `databaseUrl` and
+ * `store` are both provided; or `"VALIDATION"` if `databaseUrl` is explicitly
+ * empty.
  *
  * @example Postgres-backed client
  * ```ts
@@ -38,11 +41,12 @@ declare function createMnemocyte(config: MnemocyteConfig): MnemocyteClient;
  * - `"DB"` — Postgres or driver-level failure.
  * - `"EMBEDDING"` — embedder threw or returned an invalid vector.
  * - `"NOT_FOUND"` — referenced memory or entity does not exist.
+ * - `"CONFLICT"` — the requested mutation conflicts with stored relationships.
  * - `"MIGRATION"` — schema/migration check failed against the target database.
  * - `"TIMEOUT"` — a provider call exceeded its configured timeout.
  * - `"ABORTED"` — the operation was cancelled via an `AbortSignal`.
  */
-type MnemocyteErrorCode = "CONFIG" | "VALIDATION" | "DB" | "EMBEDDING" | "NOT_FOUND" | "MIGRATION" | "TIMEOUT" | "ABORTED";
+type MnemocyteErrorCode = "CONFIG" | "VALIDATION" | "DB" | "EMBEDDING" | "NOT_FOUND" | "CONFLICT" | "MIGRATION" | "TIMEOUT" | "ABORTED";
 /**
  * Error type thrown by every public Mnemocyte API.
  *
@@ -86,5 +90,5 @@ declare class MnemocyteError extends Error {
  */
 declare function isMnemocyteError(error: unknown): error is MnemocyteError;
 //#endregion
-export { type AuditConfig, type AuditEvent, type BuildContextInput, type ConsolidateInput, type ConsolidateResult, type ContextFormat, type DuplicatePair, type Embedder, type EntityStats, type ExperimentalMnemocyteClient, type FindDuplicatesInput, type GlobalStats, type ImportanceLevel, type JsonObject, type JsonValue, type ListAuditLogInput, type Memory, type MemoryType, type MemoryWithScore, type MnemocyteBackend, type MnemocyteClient, type MnemocyteConfig, MnemocyteError, type MnemocyteErrorCode, type MnemocyteObservation, type MnemocyteObservationPhase, type MnemocyteOperation, type ObservabilityConfig, type ProviderResilienceConfig, type PruneInput, type PruneResult, type RecallInput, type RememberInput, type RememberManyInput, type RetrievalConfig, type RetrievalExplanation, type RetrievalScoreWeights, type RetrievalScores, type TokenCounter, createMnemocyte, isMnemocyteError };
+export { type AuditConfig, type AuditEvent, type AuditLogCursor, type BuildContextInput, type ConsolidateInput, type ConsolidateResult, type ContextFormat, type DuplicatePair, type Embedder, type EntityStats, type ExperimentalMnemocyteClient, type FindDuplicatesInput, type GlobalStats, type ImportanceLevel, type JsonObject, type JsonValue, type ListAuditLogInput, type Memory, type MemoryType, type MemoryWithScore, type MnemocyteBackend, type MnemocyteClient, type MnemocyteConfig, MnemocyteError, type MnemocyteErrorCode, type MnemocyteObservation, type MnemocyteObservationPhase, type MnemocyteOperation, type MnemocyteStoreConfig, type ObservabilityConfig, type ProviderResilienceConfig, type PruneInput, type PruneResult, type RecallInput, type RememberInput, type RememberManyInput, type RetrievalConfig, type RetrievalExplanation, type RetrievalScoreWeights, type RetrievalScores, type TokenCounter, createMnemocyte, isMnemocyteError };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/client.ts","../src/errors.ts"],"mappings":";;;;;AAoCA;;;;;;;;AAAyE;;;;ACxBzE;;;;AAA8B;AA6B9B;;;;;;;iBDLgB,eAAA,CAAgB,MAAA,EAAQ,eAAA,GAAkB,eAAe;;;;;;AAAzE;;;;;;;;AAAyE;KCxB7D,kBAAA;;;AAAZ;;;;AAA8B;AA6B9B;;;;;;;;;;;;cAAa,cAAA,SAAuB,KAAA;EAWvB;EAAA,SATH,IAAA,EAAM,kBAAA;EASc;EAAA,SAPX,KAAA;EAOoD;AAAA;AAkBvE;;;cAlBa,OAAA,UAAiB,IAAA,EAAM,kBAAA,EAAoB,KAAA;AAAA;;;;AAkBiB;;;;;;;iBAAzD,gBAAA,CAAiB,KAAA,YAAiB,KAAA,IAAS,cAAc"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/client.ts","../src/errors.ts"],"mappings":";;;;;AA2CA;;;;;;;;AAAyE;;;;AC9BzE;;;;AAA8B;AA8B9B;;;;;;;;;;iBDAgB,eAAA,CAAgB,MAAA,EAAQ,eAAA,GAAkB,eAAe;;;;;;AAAzE;;;;;;;;AAAyE;;KC9B7D,kBAAA;;AAAZ;;;;AAA8B;AA8B9B;;;;;;;;;;;;;cAAa,cAAA,SAAuB,KAAA;EAWA;EAAA,SAT1B,IAAA,EAAM,kBAAA;EASwC;EAAA,SAPrC,KAAA;EAOoD;AAkBvE;;;;cAlBa,OAAA,UAAiB,IAAA,EAAM,kBAAA,EAAoB,KAAA;AAAA;;;AAkBiB;;;;;;;;iBAAzD,gBAAA,CAAiB,KAAA,YAAiB,KAAA,IAAS,cAAc"}