mnemocyte 0.1.2 → 0.1.3

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,117 @@ 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`.
-
-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.
+Official embedder helpers are planned, starting with `openaiEmbedder()`.
 
-## Provider Resilience
+## Postgres
 
-Mnemocyte can apply timeouts and retries to embedder calls, and forwards
-`AbortSignal` cancellation to in-flight attempts. Retries and timeouts are
-disabled by default.
+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 an HNSW pgvector index for cosine search. 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 +173,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 +183,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`
+
+```ts
+await client.experimental.consolidate({
+  entityId: "user_123",
+  survivorId: "mem_survivor",
+  supersededIds: ["mem_duplicate"],
+});
+```
 
-- `"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.
+The `experimental` namespace may change before v1.0.
 
-Audit entries are sticky: `forgetAll` does not erase prior log entries. Disable
-audit by leaving `audit.enabled` unset.
+## Provider Resilience
 
-## Consolidation
+```ts
+const client = createMnemocyte({
+  embedder,
+  provider: {
+    timeoutMs: 5_000,
+    retries: 2,
+    baseDelayMs: 200,
+    maxDelayMs: 2_000,
+  },
+});
+```
 
-`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`.
+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 +260,31 @@ const client = createMnemocyte({
 });
 ```
 
+## Roadmap
+
+Near-term work:
+
+- production safety and HNSW documentation
+- official `openaiEmbedder()`
+- configurable embedding dimensions with `mnemocyte_meta`
+- `Store` 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).