mnemocyte 0.4.0 → 0.5.1

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.
@@ -19,7 +21,9 @@ logs, and duplicate-consolidation tools on top of your existing infrastructure.
 - 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`.
+Mnemocyte ships as ES modules. CommonJS code can load it with `require()` on
+the supported Node versions (22.18 and newer); `require()` returns the
+module's named exports.
 
 ## Install
 
@@ -65,8 +69,8 @@ const context = await client.buildContext({
 await client.close();
 ```
 
-When `databaseUrl` is omitted, Mnemocyte uses the in-memory backend.
-That backend is intended for development, tests, and prototyping. For
+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
@@ -114,7 +118,21 @@ boundary.
 ## Postgres
 
 For persistent storage, enable pgvector in your Postgres database, apply the
-bundled migrations, then pass `databaseUrl`.
+appropriate bundled schema file, then pass `databaseUrl`. The commands below
+use `psql` and assume `DATABASE_URL` points at the target database.
+`-v ON_ERROR_STOP=1 --single-transaction` makes `psql` stop at the first error
+and roll the whole file back, so a failed migration never leaves a partial
+schema.
+
+Enable pgvector before applying any Mnemocyte schema file:
+
+```bash
+psql "$DATABASE_URL" -c 'CREATE EXTENSION IF NOT EXISTS vector;'
+```
+
+The database role running that command must be allowed to install the
+extension. Mnemocyte does not create extensions, tables, or indexes from the
+client constructor.
 
 ```ts
 const client = createMnemocyte({
@@ -123,6 +141,42 @@ 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.
@@ -130,6 +184,7 @@ host, database, and credential validation remains the driver's responsibility.
 The package includes:
 
 ```txt
+migrations/fresh-install.sql
 migrations/0000_initial.sql
 migrations/0001_add_mnemocyte_meta.sql
 migrations/0002_add_embedding_model.sql
@@ -137,28 +192,44 @@ migrations/0000_initial.sql.template
 migrations/render-initial.mjs
 ```
 
-For the default 1536-dimensional schema on a fresh install, apply these in
-order:
+For a brand-new installation using the default 1536 dimensions, apply the
+consolidated fresh-install file:
 
-```txt
-migrations/0000_initial.sql
-migrations/0001_add_mnemocyte_meta.sql
-migrations/0002_add_embedding_model.sql
+```bash
+psql "$DATABASE_URL" -v ON_ERROR_STOP=1 --single-transaction -f node_modules/mnemocyte/migrations/fresh-install.sql
 ```
 
-For an existing 0.1.x Postgres install, apply
-`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`.
+`fresh-install.sql` is generated from `0000_initial.sql.template` and combines
+the final empty-database effects of `0000`, `0001`, and `0002`. It is only for
+a brand-new installation and is not part of the Drizzle migration journal.
+
+Existing installations must continue to use the numbered migration series.
+The `0000` / `0001` / `0002` files remain the correct upgrade source; do not
+apply `fresh-install.sql` over an existing Mnemocyte schema.
+
+For an existing 0.1.x Postgres installation, apply `0001` and then `0002` in
+the same order as before:
+
+```bash
+psql "$DATABASE_URL" -v ON_ERROR_STOP=1 --single-transaction -f node_modules/mnemocyte/migrations/0001_add_mnemocyte_meta.sql
+psql "$DATABASE_URL" -v ON_ERROR_STOP=1 --single-transaction -f node_modules/mnemocyte/migrations/0002_add_embedding_model.sql
+```
+
+For an existing 0.2.x or 0.3.x installation, apply only `0002`:
+
+```bash
+psql "$DATABASE_URL" -v ON_ERROR_STOP=1 --single-transaction -f node_modules/mnemocyte/migrations/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` dimensions and the installation-model column, so it
-does not also need `0001` or `0002`.
+initial migration from the template, then apply that rendered file instead of
+`fresh-install.sql` or any numbered migration. The rendered initial migration
+includes the matching `mnemocyte_meta` dimensions and the installation-model
+column, so it does not also need `0000`, `0001`, or `0002`.
 
 ```bash
 node node_modules/mnemocyte/migrations/render-initial.mjs --dimensions 768 --out migrations/0000_initial.768.sql
+psql "$DATABASE_URL" -v ON_ERROR_STOP=1 --single-transaction -f migrations/0000_initial.768.sql
 ```
 
 Inside this repository, the equivalent development shortcut is:
@@ -429,7 +500,15 @@ 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.
+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
@@ -521,125 +600,27 @@ 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:
-
-- public `MemoryStore` adapter surface
-- `drizzleStore(db)` for caller-owned Drizzle clients
-- `@mnemocyte/mcp`
-
-See [ROADMAP.md](./docs/ROADMAP.md).
-
-## Pre-v1 Notes
-
-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
-  available before v1 but still subject to API refinement.
-
-Known limitations before v1:
-
-- 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:
-
-- 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 pack:check
-```
-
-`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.
+## Limitations
 
-### Where changes belong
+Mnemocyte is pre-1.0. Today:
 
-- 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/`.
+- Postgres stores one embedding model and dimension per installation; mixed
+  vector spaces in one database are not supported.
+- The bundled HNSW index supports at most 2,000 dimensions. Rendering a
+  larger dimension produces a migration that fails at `CREATE INDEX`.
+- `drizzleStore(db)` supports only postgres.js-backed Drizzle instances, the
+  `public` schema and pre-applied migrations.
+- Without `entityId`, `prune` applies to every entity in the database.
+- `forgetAll` rejects with `"CONFLICT"` after a consolidation until the
+  superseded memories are pruned first (`prune({ entityId, superseded: true
+  })`).
+- Provider timeouts abort the attempt's `AbortSignal`; the request stops
+  promptly only if the embedder forwards that signal.
 
-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.
+The planned 0.6 release changes the API; see the
+[roadmap](./docs/ROADMAP.md).
 
-## Architecture
+## Contributing
 
-See [ARCHITECTURE.md](./docs/ARCHITECTURE.md).
+See [docs/DEVELOPMENT.md](./docs/DEVELOPMENT.md) for setup, structure,
+testing and releases, and [AGENTS.md](./AGENTS.md) for repository rules.

package/dist/embedders/index.mjs

@@ -1,2 +1 @@
-import { openaiEmbedder } from "./openai.mjs";
-export { openaiEmbedder };
+export { openaiEmbedder } from "./openai.mjs";

package/dist/embedders/openai.d.mts

@@ -1,7 +1,5 @@
-import { l as Embedder } from "../types-DH0inEay.mjs";
-
-//#region src/embedders/openai.d.ts
-interface OpenAIEmbedderOptions {
+import { l as Embedder } from "../types-DXYtLiOT.mjs";
+export interface OpenAIEmbedderOptions {
   /**
    * OpenAI API key. Defaults to `process.env.OPENAI_API_KEY`.
    */
@@ -25,7 +23,4 @@ interface OpenAIEmbedderOptions {
  * Create an OpenAI-backed {@link Embedder}. This adapter uses `fetch`
  * directly so provider SDKs never become part of Mnemocyte's dependency graph.
  */
-declare function openaiEmbedder(options: OpenAIEmbedderOptions): Embedder;
-//#endregion
-export { OpenAIEmbedderOptions, openaiEmbedder };
-//# sourceMappingURL=openai.d.mts.map
+export declare function openaiEmbedder(options: OpenAIEmbedderOptions): Embedder;

package/dist/embedders/openai.mjs

@@ -1,11 +1,11 @@
-import { t as MnemocyteError } from "../errors-B_7ZdjEO.mjs";
-//#region src/embedders/openai.ts
+import { t as MnemocyteError } from "../errors-Dgt2nAs1.mjs";
+// src/embedders/openai.ts
 const KNOWN_MODEL_DIMENSIONS = {
 	"text-embedding-3-small": 1536,
 	"text-embedding-3-large": 3072,
 	"text-embedding-ada-002": 1536
 };
-const CONFIGURABLE_DIMENSION_MODELS = new Set(["text-embedding-3-small", "text-embedding-3-large"]);
+const CONFIGURABLE_DIMENSION_MODELS = /* @__PURE__ */ new Set(["text-embedding-3-small", "text-embedding-3-large"]);
 function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -87,7 +87,6 @@ function openaiEmbedder(options) {
 		}
 	};
 }
-//#endregion
 export { openaiEmbedder };
 
 //# sourceMappingURL=openai.mjs.map

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\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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"}
+{"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-B_7ZdjEO.mjs → errors-Dgt2nAs1.mjs}

@@ -1,4 +1,4 @@
-//#region src/errors.ts
+// src/errors.ts
 /**
 * Error type thrown by every public Mnemocyte API.
 *
@@ -48,7 +48,6 @@ var MnemocyteError = class extends Error {
 function isMnemocyteError(error) {
 	return error instanceof MnemocyteError;
 }
-//#endregion
 export { isMnemocyteError as n, MnemocyteError as t };
 
-//# sourceMappingURL=errors-B_7ZdjEO.mjs.map
+//# sourceMappingURL=errors-Dgt2nAs1.mjs.map

package/dist/{errors-B_7ZdjEO.mjs.map → errors-Dgt2nAs1.mjs.map}

@@ -1 +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"}
+{"version":3,"file":"errors-Dgt2nAs1.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,24 +1,24 @@
-import { A as PruneResult, C as MnemocyteConfig, D as ObservabilityConfig, E as MnemocyteOperation, F as RetrievalExplanation, I as RetrievalScoreWeights, L as RetrievalScores, M as RememberInput, N as RememberManyInput, O as ProviderResilienceConfig, P as RetrievalConfig, R as TokenCounter, 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 RecallInput, k as PruneInput, 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 } from "./types-DH0inEay.mjs";
-
-//#region src/client.d.ts
+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-DXYtLiOT.mjs";
 /**
  * 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, provider resilience, or the database URL is malformed or does not
- * use the `postgres:` / `postgresql:` protocol, or `"VALIDATION"` if
- * `databaseUrl` is explicitly empty.
+ * 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
@@ -28,9 +28,7 @@ import { A as PruneResult, C as MnemocyteConfig, D as ObservabilityConfig, E as
  * });
  * ```
  */
-declare function createMnemocyte(config: MnemocyteConfig): MnemocyteClient;
-//#endregion
-//#region src/errors.d.ts
+export declare function createMnemocyte(config: MnemocyteConfig): MnemocyteClient;
 /**
  * Stable, machine-readable error code attached to every {@link MnemocyteError}.
  *
@@ -64,7 +62,7 @@ type MnemocyteErrorCode = "CONFIG" | "VALIDATION" | "DB" | "EMBEDDING" | "NOT_FO
  * }
  * ```
  */
-declare class MnemocyteError extends Error {
+export declare class MnemocyteError extends Error {
   /** Stable, machine-readable failure code. See {@link MnemocyteErrorCode}. */
   readonly code: MnemocyteErrorCode;
   /** Underlying cause, if any (e.g. an original driver or embedder error). */
@@ -86,7 +84,5 @@ declare class MnemocyteError extends Error {
  * @param error - Value to test (typically a caught `unknown`).
  * @returns `true` if `error` is a {@link MnemocyteError}.
  */
-declare function isMnemocyteError(error: unknown): error is MnemocyteError;
-//#endregion
-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 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
+export declare function isMnemocyteError(error: unknown): error is MnemocyteError;
+export type { AuditConfig, AuditEvent, AuditLogCursor, BuildContextInput, ConsolidateInput, ConsolidateResult, ContextFormat, DuplicatePair, Embedder, EntityStats, ExperimentalMnemocyteClient, FindDuplicatesInput, GlobalStats, ImportanceLevel, JsonObject, JsonValue, ListAuditLogInput, Memory, MemoryType, MemoryWithScore, MnemocyteBackend, MnemocyteClient, MnemocyteConfig, MnemocyteErrorCode, MnemocyteObservation, MnemocyteObservationPhase, MnemocyteOperation, MnemocyteStoreConfig, ObservabilityConfig, ProviderResilienceConfig, PruneInput, PruneResult, RecallInput, RememberInput, RememberManyInput, RetrievalConfig, RetrievalExplanation, RetrievalScoreWeights, RetrievalScores, TokenCounter };