mnemocyte 0.2.0 → 0.4.0

package/README.md

@@ -16,7 +16,7 @@ logs, and duplicate-consolidation tools on top of your existing infrastructure.
 - Hybrid recall with vector similarity, lexical matching, recency, confidence,
   access count, and importance.
 - Prompt-ready context output in Markdown, plain text, or XML.
-- Provider retries, operation timeouts, and caller `AbortSignal` cancellation.
+- Provider retries, per-attempt timeouts, and caller `AbortSignal` cancellation.
 - Pruning, duplicate detection, audit logs, and experimental consolidation.
 
 Mnemocyte is ESM-only. Use `import`, not CommonJS `require`.
@@ -66,10 +66,16 @@ await client.close();
 ```
 
 When `databaseUrl` is 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`, 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({
@@ -99,7 +105,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
 
@@ -113,11 +123,16 @@ const client = createMnemocyte({
 });
 ```
 
+`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
 ```
@@ -128,16 +143,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
@@ -149,14 +167,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. On the
-first 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:
+
+```sql
+UPDATE mnemocyte_meta
+SET embedding_model = 'your-model-id'
+WHERE key = 'installation';
+```
 
-Use the embedding dimension documented for your chosen model, render or apply a
-matching schema, and keep one dimension per Mnemocyte 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:
@@ -191,6 +236,44 @@ await client.remember({
 });
 ```
 
+Memory metadata is persisted JSON value data. Use the exported `JsonObject`
+and `JsonValue` types; unsupported values such as `undefined`, functions,
+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
+const abortController = new AbortController();
+
+const memories = await client.rememberMany({
+  inputs: [
+    { entityId: "user_123", content: "Likes concise answers." },
+    { entityId: "user_123", content: "Uses TypeScript." },
+  ],
+  signal: abortController.signal,
+});
+```
+
+The positional `rememberMany(inputs)` form remains as a deprecated pre-v1
+compatibility overload and treats its first item's signal as the batch signal.
+New code should use `{ inputs, signal }`; individual items in the object form do
+not have cancellation signals.
+
 ### `recall`
 
 ```ts
@@ -202,6 +285,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
@@ -213,6 +301,36 @@ 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. 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`
 
 ```ts
@@ -228,6 +346,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
@@ -238,6 +373,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
@@ -250,8 +389,30 @@ 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
+`"memory.superseded"` events share the consolidation transaction and commit or
+roll back with it.
+
 ### `experimental.consolidate`
 
 ```ts
@@ -262,6 +423,18 @@ 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.
+
+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
@@ -278,6 +451,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
@@ -290,6 +469,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
@@ -300,6 +490,7 @@ VALIDATION
 CONFIG
 DB
 NOT_FOUND
+CONFLICT
 MIGRATION
 ```
 
@@ -324,15 +515,21 @@ const client = createMnemocyte({
 });
 ```
 
+Retrieval weights must be finite and non-negative, with a non-zero effective
+total after defaults are applied. `recencyHalfLifeDays` and `accessSaturation`
+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"`.
+
 ## Roadmap
 
 Planned larger milestones:
 
-- `MemoryStore` abstraction
+- public `MemoryStore` adapter surface
 - `drizzleStore(db)` for caller-owned Drizzle clients
 - `@mnemocyte/mcp`
 
-See [ROADMAP.md](./ROADMAP.md).
+See [ROADMAP.md](./docs/ROADMAP.md).
 
 ## Pre-v1 Notes
 
@@ -340,6 +537,9 @@ Current behavior:
 
 - `createMnemocyte()` selects either the in-memory backend or the
   Postgres/pgvector backend.
+- Both backends run through an internal `MemoryStore` boundary and shared
+  client orchestration; `MemoryStore` is not exported as a public adapter API
+  yet.
 - Postgres schema setup is explicit; the client does not create tables or
   indexes for you.
 - `findDuplicates`, audit-log workflows, and `experimental.consolidate` are
@@ -347,34 +547,99 @@ Current behavior:
 
 Known limitations before v1:
 
-- The two current backends share behavior by convention rather than through a
-  formal `MemoryStore` adapter boundary.
-- Configured provider timeouts fail the Mnemocyte operation with `"TIMEOUT"`;
-  actively aborting the underlying provider request on timeout remains a
-  pre-v1 hardening follow-up.
-- Postgres dimension metadata is installation-wide. Mixed embedding dimensions
-  in one database are intentionally out of scope for now.
+- The internal `MemoryStore` boundary is not a public adapter API yet.
+  `drizzleStore(db)` is the planned first public store adapter.
+- Configured provider timeouts abort the per-attempt `AbortSignal`; the
+  underlying provider request only stops promptly when the embedder honors that
+  signal.
+- Postgres model and dimension metadata are installation-wide. Mixed embedding
+  vector spaces in one database are intentionally unsupported.
 
 Planned v1 direction:
 
-- Extract a `MemoryStore` boundary so storage adapters own persistence while
-  shared core code owns validation, embedding, scoring, observability,
-  resilience, and context building.
+- Keep storage adapters behind `MemoryStore` while shared core code owns
+  validation, embedding, scoring, observability, resilience, and context
+  building.
 - Keep root `mnemocyte` imports provider-SDK-free.
 - Keep migrations, dimensions, and production index choices explicit.
 
 ## Development
 
+### Prerequisites
+
+- Node.js 22.18 or newer. CI tests the minimum 22.18 release and Node 24.
+- pnpm 11.1.1, matching the `packageManager` field in `package.json`.
+- Postgres with pgvector only when you want to run the integration suite.
+
+Clone the repository and install its locked dependencies:
+
+```bash
+git clone https://github.com/Meenic/mnemocyte.git
+cd mnemocyte
+pnpm install --frozen-lockfile
+```
+
+Mnemocyte is a library, not a standalone server. Use the quick-start example
+from a consuming TypeScript project, or run the repository build in watch mode
+while developing:
+
+```bash
+pnpm dev
+```
+
+Create the publishable ESM artifacts in `dist/` with:
+
+```bash
+pnpm build
+```
+
+### Validation
+
+Run the same main gates used by CI before committing:
+
 ```bash
 pnpm checktypes
 pnpm lint
 pnpm test
-pnpm run test:integration
 pnpm run pack:check
 ```
 
-`test:integration` skips when `DATABASE_URL` is not set.
+`pnpm test` builds the package, runs unit behavior, verifies package exports,
+and type-checks the public declarations. `pnpm lint` is a read-only formatting,
+lint, and import-order check; use `pnpm lint:fix` to apply its safe fixes. The
+Postgres suite is separate:
+
+```bash
+DATABASE_URL=postgres://... pnpm run test:integration
+```
+
+On PowerShell, set the environment variable for the current process first:
+
+```powershell
+$env:DATABASE_URL = "postgres://..."
+pnpm run test:integration
+```
+
+`test:integration` skips when `DATABASE_URL` is not set. The database must have
+pgvector available; the test applies the bundled migrations.
+
+### Where changes belong
+
+- Public exports and types: `src/index.ts`, `src/types.ts`, and `src/errors.ts`.
+- Shared client behavior: `src/memory/client-core.ts`; backend mechanics stay
+  in `src/memory/in-memory.ts` or `src/memory/postgres.ts`.
+- Postgres schema and SQL: `src/db/schema.ts` and `src/db/queries/`. Schema
+  changes require an explicit file under `migrations/`.
+- Provider helpers: `src/embedders/`; keep the root package provider-SDK-free.
+- Retrieval and context rendering: `src/retrieval/` and `src/context/`.
+- Tests: mirror the affected responsibility under `test/`; package boundary
+  checks live under `test/package/`, and real Postgres coverage under
+  `test/integration/`.
+
+See [AGENTS.md](./AGENTS.md) for repository rules and the validation/release
+policy. Read [ARCHITECTURE.md](./docs/ARCHITECTURE.md) before changing module
+boundaries or the public surface.
 
 ## Architecture
 
-See [ARCHITECTURE.md](./ARCHITECTURE.md).
+See [ARCHITECTURE.md](./docs/ARCHITECTURE.md).

package/dist/embedders/openai.d.mts

@@ -1,4 +1,4 @@
-import { c as Embedder } from "../types-DXEGcc47.mjs";
+import { l as Embedder } from "../types-DH0inEay.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-BG3-mNur.mjs";
+import { t as MnemocyteError } from "../errors-B_7ZdjEO.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":"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"}

package/dist/{errors-BG3-mNur.mjs → errors-B_7ZdjEO.mjs}

@@ -38,8 +38,9 @@ var MnemocyteError = class extends Error {
 /**
 * Type guard for {@link MnemocyteError}.
 *
-* Prefer this over `instanceof` when working across module boundaries or
-* bundlers where multiple copies of the class may exist.
+* This guard uses `instanceof` and recognizes errors created by the same loaded
+* Mnemocyte class. It does not recognize structurally similar errors or errors
+* created by another installed copy of the package.
 *
 * @param error - Value to test (typically a caught `unknown`).
 * @returns `true` if `error` is a {@link MnemocyteError}.
@@ -50,4 +51,4 @@ function isMnemocyteError(error) {
 //#endregion
 export { isMnemocyteError as n, MnemocyteError as t };
 
-//# sourceMappingURL=errors-BG3-mNur.mjs.map
+//# sourceMappingURL=errors-B_7ZdjEO.mjs.map

package/dist/errors-B_7ZdjEO.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors-B_7ZdjEO.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"}