mnemocyte 0.1.2 → 0.1.4

package/README.md

@@ -1,20 +1,20 @@
 # Mnemocyte
 
-Persistent memory for TypeScript AI applications.
+Infrastructure-native memory for TypeScript AI applications.
 
-Mnemocyte stores small, durable memories for users, agents, sessions, or
-other entities. It provides hybrid retrieval, context formatting, lifecycle
-operations, audit logging, and duplicate-consolidation tools without requiring
-a separate vector database.
+Mnemocyte stores durable memories for users, agents, sessions, and other
+entities. It gives your app hybrid recall, prompt-ready context, pruning, audit
+logs, and duplicate-consolidation tools on top of your existing infrastructure.
 
 > Mnemocyte is early software. APIs may change before v1.0.
 
 ## Features
 
-- In-memory backend for tests, demos, and short-lived processes.
+- In-memory backend for tests and demos.
 - Postgres + pgvector backend for persistent storage.
-- Hybrid recall using vector similarity, lexical matching, recency,
-  confidence, access count, and importance.
+- User-supplied `Embedder` interface.
+- Hybrid recall with vector similarity, lexical matching, recency, confidence,
+  access count, and importance.
 - Prompt-ready context output in Markdown, plain text, or XML.
 - Provider timeouts, retries, and `AbortSignal` cancellation.
 - Pruning, duplicate detection, audit logs, and experimental consolidation.
@@ -55,92 +55,145 @@ const memories = await client.recall({
   explain: true,
 });
 
+const context = await client.buildContext({
+  entityId: "user_123",
+  query: "How should I respond?",
+  format: "markdown",
+  maxTokens: 500,
+});
+
 await client.close();
 ```
 
 When `databaseUrl` is omitted, Mnemocyte uses the in-memory backend.
 
-## Postgres
+## Embedder
 
-Apply the bundled migration to a Postgres database with pgvector enabled, then
-pass `databaseUrl`:
+Mnemocyte accepts any embedder that returns one vector per input text.
 
 ```ts
 const client = createMnemocyte({
-  databaseUrl: process.env.DATABASE_URL,
-  embedder, // embedder.dimensions must be 1536 for the Postgres backend.
+  embedder: {
+    model: "text-embedding-3-small",
+    dimensions: 1536,
+    async embed(texts, options) {
+      return embedWithYourProvider(texts, {
+        signal: options?.signal,
+      });
+    },
+  },
 });
 ```
 
-The published package includes `migrations/0000_initial.sql`.
+You can also use the optional OpenAI helper:
 
-The current Postgres schema uses `embedding vector(1536)`. If
-`embedder.dimensions` is anything else, `createMnemocyte` throws a
-`MnemocyteError` with code `"CONFIG"` before opening the connection pool. The
-in-memory backend does not enforce this constraint.
+```ts
+import { openaiEmbedder } from "mnemocyte/embedders/openai";
 
-## Provider Resilience
+const embedder = openaiEmbedder({
+  model: "text-embedding-3-small",
+});
+```
 
-Mnemocyte can apply timeouts and retries to embedder calls, and forwards
-`AbortSignal` cancellation to in-flight attempts. Retries and timeouts are
-disabled by default.
+`openaiEmbedder()` reads `OPENAI_API_KEY` by default. Pass `apiKey`
+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.
+
+## Postgres
+
+For persistent storage, apply the bundled migration to a Postgres database with
+pgvector enabled, then pass `databaseUrl`.
 
 ```ts
 const client = createMnemocyte({
+  databaseUrl: process.env.DATABASE_URL!,
   embedder,
-  provider: {
-    timeoutMs: 5_000,
-    retries: 2,
-    baseDelayMs: 200,
-    maxDelayMs: 2_000,
-  },
 });
+```
 
-const controller = new AbortController();
-setTimeout(() => controller.abort(), 1_000);
+The package includes:
 
+```txt
+migrations/0000_initial.sql
+```
+
+The current Postgres schema uses `embedding vector(1536)`, so the Postgres
+backend currently requires a 1536-dimensional embedder.
+
+If dimensions do not match, `createMnemocyte` throws a `MnemocyteError` with
+code `"CONFIG"` before opening the connection pool.
+
+The migration creates the bundled HNSW pgvector index
+`mnemocyte_memories_embedding_hnsw_idx` for cosine search. HNSW is approximate:
+it is fast for nearest-neighbor recall, but recall quality, index build memory,
+and write overhead should be benchmarked against your data volume and write
+rate. Postgres still applies ordinary filters such as `entity_id`, `type`, and
+tags around vector search, so highly selective filters may need query tuning or
+a workload-specific index strategy.
+
+Large production tables should benchmark alternate indexes or custom
+migrations with representative data before changing the default. IVFFlat can be
+a good fit for some large, steady-state tables, but it needs tuning after the
+table has representative vectors. The bundled migration intentionally does not
+add full-text or tag-specific GIN indexes yet; add and benchmark expression
+indexes such as `to_tsvector('english', content)` or tag-oriented indexes only
+when your workload needs them.
+
+Configurable embedding dimensions are planned for `0.2.0`.
+
+## API
+
+### `remember`
+
+```ts
 await client.remember({
   entityId: "user_123",
-  content: "Prefers short answers.",
-  signal: controller.signal,
+  content: "Likes concise answers.",
+  type: "preference",
+  importance: "high",
+  tags: ["communication"],
 });
 ```
 
-Provider failures surface as `MnemocyteError` values with stable `code`s:
-
-- `"TIMEOUT"`: a provider attempt exceeded `timeoutMs`.
-- `"ABORTED"`: the operation was cancelled via `signal` and is not retried.
-- `"EMBEDDING"`: the embedder failed after retries were exhausted.
+### `recall`
 
-## Pruning
+```ts
+const memories = await client.recall({
+  entityId: "user_123",
+  query: "How should I respond to this user?",
+  limit: 5,
+  explain: true,
+});
+```
 
-`prune` deletes memories matching a filter. At least one selector is required;
-`prune({})` is rejected to avoid accidental full deletion.
+### `buildContext`
 
 ```ts
-await client.prune({ entityId: "user_123", expired: true });
-
-await client.prune({
-  notAccessedSince: new Date(Date.now() - 30 * 24 * 3600 * 1000),
-  maxImportance: "normal",
+const context = await client.buildContext({
+  entityId: "user_123",
+  query: "User communication preferences",
+  format: "markdown",
+  maxTokens: 500,
 });
+```
+
+### `prune`
 
+```ts
 const preview = await client.prune({
   entityId: "user_123",
   superseded: true,
   dryRun: true,
 });
-console.log(preview.matchedCount);
-```
-
-Available selectors: `entityId`, `expired`, `superseded`, `createdBefore`,
-`notAccessedSince`, `types`, `tags`, `maxImportance`. Selectors are combined
-with AND semantics.
 
-## Duplicate Detection
+await client.prune({
+  entityId: "user_123",
+  expired: true,
+});
+```
 
-`findDuplicates` is an experimental, read-only scan that surfaces
-near-identical memories for one entity using pairwise cosine similarity.
+### `findDuplicates`
 
 ```ts
 const pairs = await client.findDuplicates({
@@ -148,20 +201,9 @@ const pairs = await client.findDuplicates({
   threshold: 0.95,
   limit: 50,
 });
-
-for (const { a, b, similarity } of pairs) {
-  console.log(similarity.toFixed(3), a.content, "<>", b.content);
-}
 ```
 
-Optional selectors: `types`, `tags`, `includeSuperseded`, `includeExpired`.
-`types` and `tags` must match on both memories in each pair. Superseded and
-expired memories are excluded by default.
-
-## Audit Log
-
-When `audit.enabled` is `true`, Mnemocyte records an entry for state-changing
-operations. Read entries with `client.listAuditLog()`.
+### `listAuditLog`
 
 ```ts
 const client = createMnemocyte({
@@ -169,53 +211,61 @@ const client = createMnemocyte({
   audit: { enabled: true },
 });
 
-await client.remember({ entityId: "user_123", content: "Likes tea." });
-await client.prune({ entityId: "user_123", expired: true });
-
-const log = await client.listAuditLog({
+const events = await client.listAuditLog({
   entityId: "user_123",
   limit: 100,
 });
-
-for (const event of log) {
-  console.log(event.timestamp, event.description, event.metadata);
-}
 ```
 
-Recorded `description` slugs:
+### `experimental.consolidate`
 
-- `"memory.created"`: single insert.
-- `"memory.deleted"`: single `forget`.
-- `"entity.cleared"`: `forgetAll`.
-- `"memory.pruned"`: non-dry-run `prune` with an `entityId` selector.
-- `"memory.superseded"`: experimental consolidation.
+```ts
+await client.experimental.consolidate({
+  entityId: "user_123",
+  survivorId: "mem_survivor",
+  supersededIds: ["mem_duplicate"],
+});
+```
 
-Audit entries are sticky: `forgetAll` does not erase prior log entries. Disable
-audit by leaving `audit.enabled` unset.
+The `experimental` namespace may change before v1.0.
 
-## Consolidation
+## Provider Resilience
 
-`client.experimental.consolidate()` marks likely-duplicate memories as
-superseded by a survivor. Superseded memories are excluded from `recall` by
-default. Tags are unioned onto the survivor unless `mergeTags: false`.
+```ts
+const client = createMnemocyte({
+  embedder,
+  provider: {
+    timeoutMs: 5_000,
+    retries: 2,
+    baseDelayMs: 200,
+    maxDelayMs: 2_000,
+  },
+});
+```
+
+Pass `signal` to cancel an operation:
 
 ```ts
-const pairs = await client.findDuplicates({
+const controller = new AbortController();
+
+await client.remember({
   entityId: "user_123",
-  threshold: 0.97,
+  content: "Prefers short answers.",
+  signal: controller.signal,
 });
-
-for (const { a, b } of pairs) {
-  await client.experimental.consolidate({
-    entityId: "user_123",
-    survivorId: a.id,
-    supersededIds: [b.id],
-  });
-}
 ```
 
-The `experimental` namespace is intentionally unstable. Members may change or
-move before v1.0.
+Common `MnemocyteError` codes:
+
+```txt
+TIMEOUT
+ABORTED
+EMBEDDING
+VALIDATION
+CONFIG
+DB
+NOT_FOUND
+```
 
 ## Retrieval Tuning
 
@@ -238,19 +288,29 @@ const client = createMnemocyte({
 });
 ```
 
+## Roadmap
+
+Planned larger milestones:
+
+- configurable embedding dimensions with `mnemocyte_meta`
+- `MemoryStore` abstraction
+- `drizzleStore(db)` for caller-owned Drizzle clients
+- `@mnemocyte/mcp`
+
+See [ROADMAP.md](./ROADMAP.md).
+
 ## Development
 
 ```bash
 pnpm checktypes
 pnpm lint
-pnpm run test:retrieval
+pnpm test
 pnpm run test:integration
 pnpm run pack:check
 ```
 
-`test:integration` skips cleanly when `DATABASE_URL` is not set.
+`test:integration` skips when `DATABASE_URL` is not set.
 
 ## Architecture
 
-See [ARCHITECTURE.md](./ARCHITECTURE.md) for implementation details and
-[ROADMAP.md](./ROADMAP.md) for planned work.
+See [ARCHITECTURE.md](./ARCHITECTURE.md).

package/dist/embedders/openai.d.mts

@@ -0,0 +1,31 @@
+import { c as Embedder } from "../types-QK_43oKJ.mjs";
+
+//#region src/embedders/openai.d.ts
+interface OpenAIEmbedderOptions {
+  /**
+   * OpenAI API key. Defaults to `process.env.OPENAI_API_KEY`.
+   */
+  readonly apiKey?: string;
+  /**
+   * OpenAI embedding model name.
+   */
+  readonly model: string;
+  /**
+   * Output dimensions. Required for unknown/future model names and accepted
+   * only for OpenAI models that support configurable dimensions.
+   */
+  readonly dimensions?: number;
+  /**
+   * Override the OpenAI API base URL. Intended for tests and compatible
+   * deployments; defaults to `https://api.openai.com/v1`.
+   */
+  readonly baseUrl?: string;
+}
+/**
+ * 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

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

@@ -0,0 +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"}

package/dist/embedders/openai.mjs

@@ -0,0 +1,78 @@
+import { t as MnemocyteError } from "../errors-BG3-mNur.mjs";
+//#region 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"]);
+function assertDimensions(dimensions) {
+	if (!Number.isInteger(dimensions) || dimensions < 1) throw new MnemocyteError("openaiEmbedder dimensions must be a positive integer.", "CONFIG");
+}
+function resolveApiKey(apiKey) {
+	const resolved = apiKey ?? process.env.OPENAI_API_KEY;
+	if (!resolved || resolved.trim().length === 0) throw new MnemocyteError("openaiEmbedder requires an API key. Pass apiKey or set OPENAI_API_KEY.", "CONFIG");
+	return resolved;
+}
+function resolveDimensions(options) {
+	const defaultDimensions = KNOWN_MODEL_DIMENSIONS[options.model];
+	if (defaultDimensions === void 0) {
+		if (options.dimensions === void 0) throw new MnemocyteError(`openaiEmbedder requires dimensions for unknown model "${options.model}".`, "CONFIG");
+		assertDimensions(options.dimensions);
+		return {
+			embedderDimensions: options.dimensions,
+			requestDimensions: options.dimensions
+		};
+	}
+	if (options.dimensions !== void 0 && !CONFIGURABLE_DIMENSION_MODELS.has(options.model)) throw new MnemocyteError(`openaiEmbedder does not support a dimensions override for "${options.model}".`, "CONFIG");
+	if (options.dimensions !== void 0) {
+		assertDimensions(options.dimensions);
+		return {
+			embedderDimensions: options.dimensions,
+			requestDimensions: options.dimensions
+		};
+	}
+	return { embedderDimensions: defaultDimensions };
+}
+/**
+* Create an OpenAI-backed {@link Embedder}. This adapter uses `fetch`
+* directly so provider SDKs never become part of Mnemocyte's dependency graph.
+*/
+function openaiEmbedder(options) {
+	const apiKey = resolveApiKey(options.apiKey);
+	const { embedderDimensions, requestDimensions } = resolveDimensions(options);
+	const baseUrl = options.baseUrl ?? "https://api.openai.com/v1";
+	return {
+		model: options.model,
+		dimensions: embedderDimensions,
+		async embed(texts, embedOptions) {
+			const response = await fetch(`${baseUrl}/embeddings`, {
+				method: "POST",
+				headers: {
+					authorization: `Bearer ${apiKey}`,
+					"content-type": "application/json"
+				},
+				body: JSON.stringify({
+					model: options.model,
+					input: [...texts],
+					encoding_format: "float",
+					...requestDimensions === void 0 ? {} : { dimensions: requestDimensions }
+				}),
+				...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;
+		}
+	};
+}
+//#endregion
+export { openaiEmbedder };
+
+//# sourceMappingURL=openai.mjs.map

package/dist/embedders/openai.mjs.map

@@ -0,0 +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"}

package/dist/errors-BG3-mNur.mjs

@@ -0,0 +1,53 @@
+//#region src/errors.ts
+/**
+* Error type thrown by every public Mnemocyte API.
+*
+* Use the {@link MnemocyteError.code} property — not the message — to branch
+* on failure modes, or call {@link isMnemocyteError} as a type guard when
+* working with `unknown` errors.
+*
+* @example
+* ```ts
+* try {
+*   await client.recall({ entityId: "u1", query: "hi" });
+* } catch (err) {
+*   if (isMnemocyteError(err) && err.code === "DB") {
+*     // handle database failure
+*   }
+*   throw err;
+* }
+* ```
+*/
+var MnemocyteError = class extends Error {
+	/** Stable, machine-readable failure code. See {@link MnemocyteErrorCode}. */
+	code;
+	/** Underlying cause, if any (e.g. an original driver or embedder error). */
+	cause;
+	/**
+	* @param message - Human-readable error message.
+	* @param code - Stable failure code; see {@link MnemocyteErrorCode}.
+	* @param cause - Optional underlying cause (driver error, network error, etc.).
+	*/
+	constructor(message, code, cause) {
+		super(message);
+		this.name = "MnemocyteError";
+		this.code = code;
+		this.cause = cause;
+	}
+};
+/**
+* Type guard for {@link MnemocyteError}.
+*
+* Prefer this over `instanceof` when working across module boundaries or
+* bundlers where multiple copies of the class may exist.
+*
+* @param error - Value to test (typically a caught `unknown`).
+* @returns `true` if `error` is a {@link MnemocyteError}.
+*/
+function isMnemocyteError(error) {
+	return error instanceof MnemocyteError;
+}
+//#endregion
+export { isMnemocyteError as n, MnemocyteError as t };
+
+//# sourceMappingURL=errors-BG3-mNur.mjs.map

package/dist/errors-BG3-mNur.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors-BG3-mNur.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 * - `\"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| \"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 * Prefer this over `instanceof` when working across module boundaries or\n * bundlers where multiple copies of the class may exist.\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":";;;;;;;;;;;;;;;;;;;;AAyCA,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;;;;;;;;;;AAWA,SAAgB,iBAAiB,OAAyC;CACzE,OAAO,iBAAiB;AACzB"}