mnemocyte 0.4.0 → 0.5.0

package/README.md

@@ -12,6 +12,8 @@ logs, and duplicate-consolidation tools on top of your existing infrastructure.
 
 - In-memory backend for tests and demos.
 - Postgres + pgvector backend for persistent storage.
+- Caller-owned postgres.js Drizzle instances through
+  `mnemocyte/stores/drizzle`.
 - User-supplied `Embedder` interface.
 - Hybrid recall with vector similarity, lexical matching, recency, confidence,
   access count, and importance.
@@ -65,8 +67,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
@@ -123,6 +125,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.
@@ -429,7 +467,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,12 +567,51 @@ must be positive finite numbers, and `candidateMultiplier` must be an integer
 of at least 1. Invalid tuning is rejected at client construction with
 `MnemocyteError` code `"CONFIG"`.
 
+## Storage Adapter Contract
+
+`MemoryStore` is still an internal boundary rather than a public package
+export, but its future-adapter contract is now documented directly in
+[`src/memory/store.ts`](./src/memory/store.ts). The contract is based on
+postconditions, not identical implementation mechanics: every method is
+mandatory, and no capability-flag surface exists or is currently planned.
+
+For adapter implementers, the main rules are:
+
+- `ensureSchema` is a readiness hook, not permission for hidden schema
+  creation. `ensureEmbeddingCompatibility` unconditionally enforces whatever
+  compatibility is meaningful to the persistence model; a store without
+  persistent installation state may no-op.
+- `insertMemories` takes ownership of prepared rows and returns exactly one
+  detached record per prepared ID. Store return order is untrusted; shared
+  orchestration rejects missing, duplicate, or unknown IDs and restores input
+  order. `getMemoryEmbeddings`, `getMemory`, and `stats` use the exact keyed,
+  detached, and count postconditions described in the source comments.
+- `markMemoriesAccessed` requires distinct IDs and returns the committed
+  post-update access fields. Duplicate-ID behavior is intentionally not a
+  portable contract. Ordinary `addAuditEvents` calls are best-effort, and a
+  rejected batch may have partially persisted on some backends.
+- `listAuditLog` uses stable event IDs, comparable timestamps, strict tuple
+  filters, and matching newest-first `(timestamp, id)` order. Tuple pagination
+  needs no transaction. Cancellation may be cooperative or active depending on
+  the implementation.
+- `vectorSearch` may scan or use an approximate, planner-dependent index.
+  `lexicalSearch` may legitimately return different candidates and rankings
+  across implementations. `findDuplicatePairs` compares qualifying memories
+  pairwise and does not imply indexed nearest-neighbor pair generation.
+- `deleteMemory`, `deleteMemoriesForEntity`, and non-dry-run `prune` must
+  protect referenced consolidation survivors with one atomic,
+  non-interleavable check-and-mutate operation and reject with `"CONFLICT"`
+  before any deletion. Other cancellation boundaries remain method- and
+  implementation-specific as documented by the public operations.
+- `close` releases or destroys only implementation-owned state and resources.
+  A future adapter around a caller-supplied connection must not close that
+  connection.
+
 ## Roadmap
 
 Planned larger milestones:
 
 - public `MemoryStore` adapter surface
-- `drizzleStore(db)` for caller-owned Drizzle clients
 - `@mnemocyte/mcp`
 
 See [ROADMAP.md](./docs/ROADMAP.md).
@@ -535,11 +620,15 @@ See [ROADMAP.md](./docs/ROADMAP.md).
 
 Current behavior:
 
-- `createMnemocyte()` selects either the in-memory backend or the
-  Postgres/pgvector backend.
+- `createMnemocyte()` selects an explicitly supplied `store`, the URL-owned
+  Postgres/pgvector backend, or the in-memory backend; supplying both `store`
+  and `databaseUrl` rejects instead of selecting a precedence.
 - Both backends run through an internal `MemoryStore` boundary and shared
   client orchestration; `MemoryStore` is not exported as a public adapter API
   yet.
+- `mnemocyte/stores/drizzle` exposes the first supported public adapter factory
+  for a caller-owned postgres.js Drizzle instance without exporting the full
+  `MemoryStore` contract.
 - Postgres schema setup is explicit; the client does not create tables or
   indexes for you.
 - `findDuplicates`, audit-log workflows, and `experimental.consolidate` are
@@ -548,7 +637,8 @@ Current behavior:
 Known limitations before v1:
 
 - The internal `MemoryStore` boundary is not a public adapter API yet.
-  `drizzleStore(db)` is the planned first public store adapter.
+  `drizzleStore(db)` returns an opaque config value and currently supports only
+  postgres.js, the `public` schema, and pre-applied Mnemocyte migrations.
 - Configured provider timeouts abort the per-attempt `AbortSignal`; the
   underlying provider request only stops promptly when the embedder honors that
   signal.

package/dist/embedders/openai.d.mts

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

package/dist/embedders/openai.mjs

@@ -1,4 +1,4 @@
-import { t as MnemocyteError } from "../errors-B_7ZdjEO.mjs";
+import { t as MnemocyteError } from "../errors-DIPysVWl.mjs";
 //#region src/embedders/openai.ts
 const KNOWN_MODEL_DIMENSIONS = {
 	"text-embedding-3-small": 1536,

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

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

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

package/dist/index.d.mts

@@ -1,24 +1,26 @@
-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";
+import { A as PruneInput, C as MnemocyteConfig, D as MnemocyteStoreConfig, E as MnemocyteOperation, F as RetrievalConfig, I as RetrievalExplanation, L as RetrievalScoreWeights, M as RecallInput, N as RememberInput, O as ObservabilityConfig, P as RememberManyInput, R as RetrievalScores, S as MnemocyteClient, T as MnemocyteObservationPhase, _ as ListAuditLogInput, a as ConsolidateInput, b as MemoryWithScore, c as DuplicatePair, d as ExperimentalMnemocyteClient, f as FindDuplicatesInput, g as JsonValue, h as JsonObject, i as BuildContextInput, j as PruneResult, k as ProviderResilienceConfig, l as Embedder, m as ImportanceLevel, n as AuditEvent, o as ConsolidateResult, p as GlobalStats, r as AuditLogCursor, s as ContextFormat, t as AuditConfig, u as EntityStats, v as Memory, w as MnemocyteObservation, x as MnemocyteBackend, y as MemoryType, z as TokenCounter } from "./types-XUWYDoXM.mjs";
 
 //#region src/client.d.ts
 /**
  * Create a Mnemocyte client.
  *
- * When {@link MnemocyteConfig.databaseUrl} is provided, a Postgres-backed
- * client is returned (requires the `pgvector` extension and the bundled
- * migration applied). Otherwise an in-memory client is returned, intended
- * for tests, demos, and short-lived processes.
+ * When {@link MnemocyteConfig.store} is provided, that adapter is used. When
+ * {@link MnemocyteConfig.databaseUrl} is provided, a URL-owned Postgres client
+ * is used (requires the `pgvector` extension and the bundled migrations).
+ * When neither is supplied, an in-memory client is returned for tests, demos,
+ * and short-lived processes.
  *
- * The returned client owns any underlying resources (e.g. the Postgres
- * connection pool). Call {@link MnemocyteClient.close} when finished to
- * release them.
+ * Call {@link MnemocyteClient.close} when finished. URL-created database
+ * resources are owned and closed by Mnemocyte; resources behind a supplied
+ * store retain the ownership policy documented by that adapter.
  *
  * @param config - Client configuration. {@link MnemocyteConfig.embedder} is required.
  * @returns A {@link MnemocyteClient} instance.
  * @throws {MnemocyteError} With code `"CONFIG"` if `embedder`, retrieval
  * tuning, 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
@@ -88,5 +90,5 @@ declare class MnemocyteError extends Error {
  */
 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 };
+export { type AuditConfig, type AuditEvent, type AuditLogCursor, type BuildContextInput, type ConsolidateInput, type ConsolidateResult, type ContextFormat, type DuplicatePair, type Embedder, type EntityStats, type ExperimentalMnemocyteClient, type FindDuplicatesInput, type GlobalStats, type ImportanceLevel, type JsonObject, type JsonValue, type ListAuditLogInput, type Memory, type MemoryType, type MemoryWithScore, type MnemocyteBackend, type MnemocyteClient, type MnemocyteConfig, MnemocyteError, type MnemocyteErrorCode, type MnemocyteObservation, type MnemocyteObservationPhase, type MnemocyteOperation, type MnemocyteStoreConfig, type ObservabilityConfig, type ProviderResilienceConfig, type PruneInput, type PruneResult, type RecallInput, type RememberInput, type RememberManyInput, type RetrievalConfig, type RetrievalExplanation, type RetrievalScoreWeights, type RetrievalScores, type TokenCounter, createMnemocyte, isMnemocyteError };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

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