mnemocyte 0.0.7 → 0.1.0

package/dist/index.d.mts

@@ -1,179 +1,931 @@
 //#region src/types.d.ts
+/**
+ * Discriminator describing what kind of memory a {@link Memory} represents.
+ *
+ * - `"fact"` — a stable, objective statement.
+ * - `"preference"` — a user/entity preference that should bias future responses.
+ * - `"instruction"` — a directive the agent should follow.
+ * - `"backstory"` — long-lived background context about the entity.
+ * - `"episode"` — a discrete past event.
+ * - `"session"` — short-lived context tied to a single session.
+ *
+ * @defaultValue `"fact"` when omitted on {@link RememberInput}.
+ */
 type MemoryType = "fact" | "preference" | "instruction" | "backstory" | "episode" | "session";
+/**
+ * Relative importance assigned to a memory. Influences retrieval ranking
+ * via the `importance` score component.
+ *
+ * @defaultValue `"normal"` when omitted on {@link RememberInput}.
+ */
 type ImportanceLevel = "low" | "normal" | "high" | "critical";
+/**
+ * Output format produced by {@link MnemocyteClient.buildContext}.
+ *
+ * - `"markdown"` — headings + bullet list (default; LLM-friendly).
+ * - `"plain"` — newline-separated plain text.
+ * - `"xml"` — structured tags, useful for models that parse XML reliably.
+ *
+ * @defaultValue `"markdown"`
+ */
 type ContextFormat = "markdown" | "plain" | "xml";
+/**
+ * Identifies which backend a {@link MnemocyteClient} is using.
+ *
+ * Selected automatically by {@link createMnemocyte} based on whether
+ * {@link MnemocyteConfig.databaseUrl} was provided.
+ */
 type MnemocyteBackend = "in-memory" | "postgres";
-type MnemocyteOperation = "remember" | "rememberMany" | "recall" | "buildContext" | "forget" | "forgetAll" | "stats" | "close";
+/**
+ * The set of public {@link MnemocyteClient} methods that emit
+ * {@link MnemocyteObservation} events through {@link ObservabilityConfig.onEvent}.
+ */
+type MnemocyteOperation = "remember" | "rememberMany" | "recall" | "buildContext" | "forget" | "forgetAll" | "prune" | "findDuplicates" | "listAuditLog" | "consolidate" | "stats" | "close";
+/**
+ * Lifecycle phase of a {@link MnemocyteObservation}.
+ *
+ * Every operation emits exactly one `"start"` event and exactly one of
+ * `"success"` or `"error"` once it settles.
+ */
 type MnemocyteObservationPhase = "start" | "success" | "error";
+/**
+ * A single observability event emitted by a {@link MnemocyteClient}.
+ *
+ * Delivered to {@link ObservabilityConfig.onEvent} for tracing, metrics,
+ * and structured logging.
+ */
 interface MnemocyteObservation {
+  /** Operation that produced this event. */
   operation: MnemocyteOperation;
+  /** Lifecycle phase: `"start"`, `"success"`, or `"error"`. */
   phase: MnemocyteObservationPhase;
+  /** Backend handling the operation. */
   backend: MnemocyteBackend;
+  /** Wall-clock timestamp of this event. */
   timestamp: Date;
+  /** Elapsed milliseconds since the `"start"` event. Present on `"success"` / `"error"`. */
   durationMs?: number;
+  /** Entity ID associated with the operation, when applicable. */
   entityId?: string;
+  /** Memory ID associated with the operation, when applicable. */
   memoryId?: string;
+  /** Number of items processed (e.g. memories returned, batch size). */
   count?: number;
+  /** Thrown value. Present only on `"error"`. */
   error?: unknown;
 }
+/**
+ * Hooks for observing client activity.
+ *
+ * Exceptions thrown by {@link ObservabilityConfig.onEvent} are swallowed so
+ * that telemetry never affects application logic.
+ */
 interface ObservabilityConfig {
+  /**
+   * Called for every lifecycle event of every operation. Receives a single
+   * {@link MnemocyteObservation}. May be sync or async; the operation will
+   * not be delayed waiting for slow async hooks beyond the awaited dispatch.
+   */
   onEvent?: (event: MnemocyteObservation) => void | Promise<void>;
 }
+/**
+ * Production-hardening knobs applied to outbound provider calls
+ * (currently the {@link Embedder}). Mnemocyte applies a timeout, retries
+ * on transient failures, and forwards `AbortSignal` cancellation to each
+ * attempt. Every field is optional with conservative defaults; the
+ * defaults disable retries and timeouts so existing setups are
+ * unaffected unless they opt in.
+ */
+interface ProviderResilienceConfig {
+  /**
+   * Maximum time, in milliseconds, that a single provider attempt may
+   * run before a {@link MnemocyteError} with code `"TIMEOUT"` is thrown.
+   * Defaults to `0` which disables the timeout.
+   */
+  timeoutMs?: number;
+  /**
+   * Maximum number of retry attempts after the initial call. `0`
+   * disables retries (default).
+   */
+  retries?: number;
+  /** Base backoff delay (ms) used before the first retry. Defaults to `100`. */
+  baseDelayMs?: number;
+  /** Maximum backoff delay (ms) used between retries. Defaults to `2000`. */
+  maxDelayMs?: number;
+  /**
+   * Optional predicate deciding whether `error` should trigger a retry.
+   * Receives the thrown value and the 1-indexed `attempt` number that
+   * just failed. When omitted, a conservative built-in heuristic is used
+   * that retries on common transient indicators (network errors, 5xx
+   * responses, rate-limit hints) and never retries `"VALIDATION"`,
+   * `"CONFIG"`, or `"ABORTED"` {@link MnemocyteError}s.
+   */
+  shouldRetry?: (error: unknown, attempt: number) => boolean;
+}
+/**
+ * Configuration passed to {@link createMnemocyte}.
+ */
 interface MnemocyteConfig {
+  /**
+   * Postgres connection string. When set, the client uses the Postgres
+   * backend (requires the `pgvector` extension and the bundled migration).
+   * When omitted, an in-memory backend is used.
+   */
   databaseUrl?: string;
+  /** Required embedder used to vectorise content for storage and retrieval. */
   embedder: Embedder;
+  /** Default values applied to {@link RecallInput} when properties are omitted. */
   defaults?: {
-    limit?: number;
+    /** Default `limit` for {@link MnemocyteClient.recall}. */limit?: number; /** Default `minScore` cutoff for {@link MnemocyteClient.recall}. */
     minScore?: number;
   };
+  /** Retrieval-ranking tuning. See {@link RetrievalConfig}. */
   retrieval?: RetrievalConfig;
+  /** Observability hooks. See {@link ObservabilityConfig}. */
   observability?: ObservabilityConfig;
+  /**
+   * Production-hardening knobs for outbound provider calls
+   * (timeouts, retries, abort propagation). See
+   * {@link ProviderResilienceConfig}.
+   */
+  provider?: ProviderResilienceConfig;
+  /**
+   * Audit-log configuration. When enabled, Mnemocyte records an
+   * {@link AuditEvent} for every state-changing operation
+   * (`remember`, `forget`, `forgetAll`, `prune`). Read with
+   * {@link MnemocyteClient.listAuditLog}.
+   *
+   * @experimental Part of Phase 6 (consolidation tooling).
+   */
+  audit?: AuditConfig;
+}
+/**
+ * Audit-log configuration. See {@link MnemocyteConfig.audit}.
+ *
+ * @experimental Part of Phase 6 (consolidation tooling).
+ */
+interface AuditConfig {
+  /**
+   * Master switch for audit logging. When `false` (default), Mnemocyte
+   * neither writes nor relies on the audit log; existing log entries
+   * remain readable via {@link MnemocyteClient.listAuditLog}.
+   *
+   * @defaultValue `false`
+   */
+  enabled?: boolean;
 }
+/**
+ * Pluggable embedding provider. Wraps an external embedding API
+ * (e.g. OpenAI, Cohere, a local model) in a small interface.
+ *
+ * Mnemocyte records {@link Embedder.model} and {@link Embedder.dimensions}
+ * on every stored memory and uses them to detect incompatible vectors
+ * (e.g. when the model is swapped).
+ */
 interface Embedder {
+  /** Stable identifier for the underlying model (e.g. `"text-embedding-3-small"`). */
   readonly model: string;
+  /** Dimensionality of vectors returned by {@link Embedder.embed}. */
   readonly dimensions: number;
-  embed(texts: readonly string[]): Promise<number[][]>;
+  /**
+   * Embed one or more texts. Implementations MUST return one vector per
+   * input, in the same order, each of length {@link Embedder.dimensions}.
+   *
+   * The optional `options.signal` is forwarded by Mnemocyte when the
+   * caller passes a `signal` on a {@link RememberInput} / {@link RecallInput}
+   * / {@link BuildContextInput}, or when Mnemocyte's own provider timeout
+   * fires. Implementations that integrate with `fetch` should forward
+   * the signal to it so requests can be cancelled promptly.
+   */
+  embed(texts: readonly string[], options?: {
+    signal?: AbortSignal;
+  }): Promise<number[][]>;
 }
+/**
+ * A persisted memory record as returned by the client.
+ *
+ * Memories are immutable from the caller's perspective; updates produce a
+ * new memory and link the previous one via {@link Memory.supersededBy}.
+ */
 interface Memory {
+  /** Unique identifier (`mem_*` prefixed string). */
   id: string;
+  /** Owning entity — typically a user, agent, or session ID. */
   entityId: string;
+  /** Raw textual content of the memory. */
   content: string;
+  /** Discriminator describing the kind of memory. */
   type: MemoryType;
+  /** Relative importance assigned at write time. */
   importance: ImportanceLevel;
+  /** Free-form tags used for filtering on {@link RecallInput.tags}. */
   tags: string[];
+  /** Optional human-readable source attribution (e.g. `"chat:2024-04-12"`). */
   source: string | null;
+  /** Arbitrary user-provided metadata persisted alongside the memory. */
   metadata: Record<string, unknown>;
+  /** Confidence in `[0, 1]`. Used in retrieval ranking. */
   confidence: number;
+  /** {@link Embedder.model} value at write time. */
   embeddingModel: string;
+  /** {@link Embedder.dimensions} value at write time. */
   embeddingDimensions: number;
+  /** ID of the memory that supersedes this one, or `null` if active. */
   supersededBy: string | null;
+  /**
+   * Wall-clock time when this memory was superseded, or `null` if it
+   * has not been superseded. Set together with
+   * {@link Memory.supersededBy} by
+   * {@link ExperimentalMnemocyteClient.consolidate}.
+   */
+  supersededAt: Date | null;
+  /** Optional expiry; expired memories are filtered out by default. */
   expiresAt: Date | null;
+  /** Last time this memory was returned by {@link MnemocyteClient.recall}. */
   lastAccessedAt: Date | null;
+  /** Cumulative number of times this memory has been recalled. */
   accessCount: number;
+  /** Creation timestamp. */
   createdAt: Date;
+  /** Most recent update timestamp. */
   updatedAt: Date;
 }
+/**
+ * Per-component scores produced during retrieval ranking. Each value is
+ * normalised to `[0, 1]` before being combined via
+ * {@link RetrievalScoreWeights}.
+ */
 interface RetrievalScores {
+  /** Cosine similarity between the query embedding and the memory embedding. */
   vector: number;
+  /** Token-overlap (lexical) score between query and memory content. */
   lexical: number;
+  /** Time-decay score based on {@link RetrievalConfig.recencyHalfLifeDays}. */
   recency: number;
+  /** Pass-through of the memory's stored `confidence`. */
   confidence: number;
+  /** Saturating score derived from `accessCount`. */
   access: number;
+  /** Score derived from {@link ImportanceLevel}. */
   importance: number;
 }
+/**
+ * Optional overrides for the per-component retrieval weights. Missing keys
+ * fall back to library defaults. Weights need not sum to 1; the final
+ * score is computed as a weighted sum of {@link RetrievalScores}.
+ */
 interface RetrievalScoreWeights {
+  /** Weight applied to {@link RetrievalScores.vector}. */
   vector?: number;
+  /** Weight applied to {@link RetrievalScores.lexical}. */
   lexical?: number;
+  /** Weight applied to {@link RetrievalScores.recency}. */
   recency?: number;
+  /** Weight applied to {@link RetrievalScores.confidence}. */
   confidence?: number;
+  /** Weight applied to {@link RetrievalScores.access}. */
   access?: number;
+  /** Weight applied to {@link RetrievalScores.importance}. */
   importance?: number;
 }
+/**
+ * Retrieval-ranking tuning. All fields are optional; sensible defaults are
+ * used for any field that is omitted.
+ */
 interface RetrievalConfig {
+  /** Per-component score weights. See {@link RetrievalScoreWeights}. */
   weights?: RetrievalScoreWeights;
+  /** Half-life (days) for the time-decay recency component. */
   recencyHalfLifeDays?: number;
+  /** Access count at which the access score is considered saturated. */
   accessSaturation?: number;
+  /**
+   * Multiplier applied to {@link RecallInput.limit} to determine how many
+   * candidates are fetched from the underlying store before re-ranking.
+   */
   candidateMultiplier?: number;
 }
+/**
+ * Detailed scoring breakdown attached to each {@link MemoryWithScore} when
+ * {@link RecallInput.explain} is `true`. Useful for debugging ranking and
+ * tuning {@link RetrievalConfig}.
+ */
 interface RetrievalExplanation {
+  /** Raw vector similarity in `[0, 1]`. */
   vectorScore: number;
+  /** Raw lexical-overlap score in `[0, 1]`. */
   lexicalScore: number;
+  /** Raw recency score in `[0, 1]`. */
   recencyScore: number;
+  /** Raw confidence score in `[0, 1]`. */
   confidenceScore: number;
+  /** Raw access score in `[0, 1]`. */
   accessScore: number;
+  /** Raw importance score in `[0, 1]`. */
   importanceScore: number;
+  /** Additive multiplier applied for high-importance memories. */
   importanceBoost: number;
+  /** Effective weights used for this query (defaults filled in). */
   weights: Required<RetrievalScoreWeights>;
+  /** Final combined score — same value as {@link MemoryWithScore.score}. */
   finalScore: number;
 }
+/**
+ * A {@link Memory} returned by {@link MnemocyteClient.recall}, annotated
+ * with retrieval scores.
+ */
 interface MemoryWithScore extends Memory {
+  /** Final combined relevance score. Higher is better. */
   score: number;
+  /** Per-component scores that produced {@link MemoryWithScore.score}. */
   scores: RetrievalScores;
+  /**
+   * Full scoring breakdown when {@link RecallInput.explain} is `true`,
+   * `null` otherwise.
+   */
   explanation: RetrievalExplanation | null;
 }
+/**
+ * Input for {@link MnemocyteClient.remember} and
+ * {@link MnemocyteClient.rememberMany}.
+ */
 interface RememberInput {
+  /** Owning entity ID (e.g. user, agent, or session). */
   entityId: string;
+  /** Raw textual content to store. Must be non-empty. */
   content: string;
+  /** Memory kind. @defaultValue `"fact"` */
   type?: MemoryType;
+  /** Relative importance. @defaultValue `"normal"` */
   importance?: ImportanceLevel;
+  /** Free-form tags used for later filtering. */
   tags?: string[];
+  /** Optional human-readable source attribution. */
   source?: string;
+  /** Arbitrary metadata persisted alongside the memory. */
   metadata?: Record<string, unknown>;
+  /** Confidence in `[0, 1]`. @defaultValue `1` */
   confidence?: number;
+  /** Optional expiry; expired memories are filtered out by default. */
   expiresAt?: Date;
+  /**
+   * Optional cancellation signal. Forwarded to the embedder; when
+   * aborted, the operation throws a {@link MnemocyteError} with code
+   * `"ABORTED"`.
+   */
+  signal?: AbortSignal;
 }
+/**
+ * Input for {@link MnemocyteClient.recall}.
+ */
 interface RecallInput {
+  /** Owning entity ID to search within. */
   entityId: string;
+  /** Free-text query; embedded and matched against stored memories. */
   query: string;
+  /** Maximum number of results. Falls back to {@link MnemocyteConfig.defaults}. */
   limit?: number;
+  /** Minimum final score required for a memory to be returned. */
   minScore?: number;
+  /** Restrict results to these memory types. */
   types?: MemoryType[];
+  /** Require results to include all of these tags. */
   tags?: string[];
+  /** Only include memories created strictly before this date. */
   before?: Date;
+  /** Only include memories created strictly after this date. */
   after?: Date;
+  /** Include memories that have been superseded. @defaultValue `false` */
   includeSuperseded?: boolean;
+  /** Include memories whose `expiresAt` has passed. @defaultValue `false` */
   includeExpired?: boolean;
+  /** Populate {@link MemoryWithScore.explanation} on each result. @defaultValue `false` */
   explain?: boolean;
+  /**
+   * Optional cancellation signal. Forwarded to the embedder; when
+   * aborted, the operation throws a {@link MnemocyteError} with code
+   * `"ABORTED"`.
+   */
+  signal?: AbortSignal;
 }
+/**
+ * Pluggable token counter used by {@link MnemocyteClient.buildContext} to
+ * enforce {@link BuildContextInput.maxTokens}. Plug in your model's real
+ * tokenizer (e.g. `tiktoken`) for accurate budgeting; a simple word-based
+ * heuristic is used when omitted.
+ */
 interface TokenCounter {
+  /** Return the number of tokens in `text`. */
   count(text: string): number;
 }
+/**
+ * Input for {@link MnemocyteClient.buildContext}, which renders relevant
+ * memories into a prompt-ready string.
+ */
 interface BuildContextInput {
+  /** Owning entity ID to search within. */
   entityId: string;
+  /** Free-text query used to select relevant memories. */
   query: string;
+  /** Output format. @defaultValue `"markdown"` */
   format?: ContextFormat;
+  /** Optional token budget; memories are dropped from the tail until the budget fits. */
   maxTokens?: number;
+  /** Maximum number of memories to consider. */
   limit?: number;
+  /** Minimum retrieval score required. */
   minScore?: number;
+  /** Restrict to these memory types. */
   types?: MemoryType[];
+  /** Require results to include all of these tags. */
   tags?: string[];
+  /** Include superseded memories. @defaultValue `false` */
   includeSuperseded?: boolean;
+  /** Include expired memories. @defaultValue `false` */
   includeExpired?: boolean;
+  /** Tokenizer used to enforce {@link BuildContextInput.maxTokens}. */
   tokenCounter?: TokenCounter;
+  /**
+   * Optional cancellation signal. Forwarded to the underlying recall
+   * call and embedder; when aborted, the operation throws a
+   * {@link MnemocyteError} with code `"ABORTED"`.
+   */
+  signal?: AbortSignal;
+}
+/**
+ * Input for {@link MnemocyteClient.prune}. All fields are optional, but
+ * at least one selector must be set; calling `prune({})` is rejected with
+ * a `"VALIDATION"` {@link MnemocyteError} so memories cannot be deleted
+ * accidentally. Specified filters are combined with AND semantics.
+ */
+interface PruneInput {
+  /** Restrict pruning to a single entity. */
+  entityId?: string;
+  /** Match memories whose `expiresAt` is in the past. */
+  expired?: boolean;
+  /** Match memories that have been superseded (`supersededBy !== null`). */
+  superseded?: boolean;
+  /** Match memories created strictly before this date. */
+  createdBefore?: Date;
+  /**
+   * Match memories whose `lastAccessedAt` is `null` or strictly before
+   * this date. Useful for evicting "cold" memories.
+   */
+  notAccessedSince?: Date;
+  /** Restrict pruning to these memory types. */
+  types?: MemoryType[];
+  /**
+   * Require memories to include all of these tags. Empty array is
+   * treated as no tag filter.
+   */
+  tags?: string[];
+  /**
+   * Match memories whose `importance` is at or below this level. For
+   * example, `"normal"` prunes `"low"` and `"normal"` but never `"high"`
+   * or `"critical"`. Useful for evicting low-value memories first.
+   */
+  maxImportance?: ImportanceLevel;
+  /**
+   * If `true`, count what would be pruned without deleting anything.
+   * @defaultValue `false`
+   */
+  dryRun?: boolean;
+  /** Optional cancellation signal. */
+  signal?: AbortSignal;
+}
+/**
+ * Result returned by {@link MnemocyteClient.prune}.
+ */
+interface PruneResult {
+  /** Number of memories that matched the prune filter. */
+  matchedCount: number;
+  /**
+   * Number of memories actually deleted. Equals `matchedCount` for
+   * normal runs and `0` for `dryRun` runs.
+   */
+  deletedCount: number;
+  /** `true` when {@link PruneInput.dryRun} was set. */
+  dryRun: boolean;
 }
+/**
+ * Input for {@link MnemocyteClient.findDuplicates}.
+ *
+ * Performs a pairwise cosine-similarity scan of stored memories for a
+ * single entity and returns pairs whose similarity meets
+ * {@link FindDuplicatesInput.threshold}. The scan is read-only — no
+ * memories are modified or deleted.
+ *
+ * @experimental Part of Phase 6 (consolidation tooling). API may change.
+ */
+interface FindDuplicatesInput {
+  /** Entity whose memories should be scanned for duplicates. */
+  entityId: string;
+  /**
+   * Cosine-similarity cutoff in `[0, 1]`. Pairs whose similarity is at
+   * or above this value are returned. @defaultValue `0.95`
+   */
+  threshold?: number;
+  /**
+   * Maximum number of duplicate pairs to return, ordered by descending
+   * similarity. @defaultValue `100`
+   */
+  limit?: number;
+  /** Restrict the scan to these memory types. */
+  types?: readonly MemoryType[];
+  /** Require both memories in the pair to include all of these tags. */
+  tags?: readonly string[];
+  /** Include superseded memories in the scan. @defaultValue `false` */
+  includeSuperseded?: boolean;
+  /** Include expired memories in the scan. @defaultValue `false` */
+  includeExpired?: boolean;
+  /** Optional cancellation signal. */
+  signal?: AbortSignal;
+}
+/**
+ * A pair of memories that are likely duplicates.
+ *
+ * The pair is unordered (i.e. `{a, b}` is the same logical result as
+ * `{b, a}`); Mnemocyte returns each pair only once.
+ *
+ * @experimental Part of Phase 6 (consolidation tooling). Shape may change.
+ */
+interface DuplicatePair {
+  /** One of the two memories in the duplicate pair. */
+  a: Memory;
+  /** The other memory in the duplicate pair. */
+  b: Memory;
+  /** Cosine similarity between the two embeddings, in `[0, 1]`. */
+  similarity: number;
+}
+/**
+ * A single audit-log entry recording a state-changing operation.
+ *
+ * @experimental Part of Phase 6 (consolidation tooling).
+ */
+interface AuditEvent {
+  /** Unique identifier (`evt_*` prefixed string). */
+  id: string;
+  /** Entity whose state was changed. */
+  entityId: string;
+  /**
+   * Stable, dotted slug describing the change. Examples:
+   * `"memory.created"`, `"memory.deleted"`, `"memory.pruned"`,
+   * `"entity.cleared"`.
+   */
+  description: string;
+  /** Free-form structured details about the change. */
+  metadata: Record<string, unknown>;
+  /** When the change was recorded. */
+  timestamp: Date;
+}
+/**
+ * Input for {@link MnemocyteClient.listAuditLog}.
+ *
+ * @experimental Part of Phase 6 (consolidation tooling).
+ */
+interface ListAuditLogInput {
+  /** Entity whose audit log should be returned. */
+  entityId: string;
+  /**
+   * Maximum number of entries to return, ordered newest first.
+   * @defaultValue `50`
+   */
+  limit?: number;
+  /** Only return entries strictly before this timestamp. */
+  before?: Date;
+  /** Only return entries strictly after this timestamp. */
+  after?: Date;
+  /** Optional cancellation signal. */
+  signal?: AbortSignal;
+}
+/**
+ * Input for {@link ExperimentalMnemocyteClient.consolidate}.
+ *
+ * Marks each memory in {@link ConsolidateInput.supersededIds} as
+ * superseded by {@link ConsolidateInput.survivorId}. Optionally
+ * unions the losers' tags into the survivor.
+ *
+ * @experimental Part of Phase 6 (consolidation tooling).
+ */
+interface ConsolidateInput {
+  /** Entity that owns every memory referenced. */
+  entityId: string;
+  /** Memory that should win the merge. Must not itself be superseded. */
+  survivorId: string;
+  /**
+   * Memories to mark as superseded by the survivor. Already-superseded
+   * entries in this list are skipped silently for idempotency. Must
+   * not contain {@link ConsolidateInput.survivorId}.
+   */
+  supersededIds: readonly string[];
+  /**
+   * When `true`, the survivor's `tags` becomes the union of its own
+   * tags and the tags of every memory that was actually superseded.
+   * @defaultValue `true`
+   */
+  mergeTags?: boolean;
+  /** Optional cancellation signal. */
+  signal?: AbortSignal;
+}
+/**
+ * Result returned by {@link ExperimentalMnemocyteClient.consolidate}.
+ *
+ * @experimental Part of Phase 6 (consolidation tooling).
+ */
+interface ConsolidateResult {
+  /** Echoes {@link ConsolidateInput.survivorId}. */
+  survivorId: string;
+  /**
+   * Number of memories actually marked as superseded. Excludes entries
+   * that were already superseded (idempotent skip).
+   */
+  supersededCount: number;
+  /** The IDs that were newly superseded during this call. */
+  supersededIds: readonly string[];
+}
+/**
+ * Stats for a single entity, returned by
+ * {@link MnemocyteClient.stats} when an `entityId` is provided.
+ */
 interface EntityStats {
+  /** The entity these stats describe. */
   entityId: string;
+  /** Total number of memories ever stored for this entity. */
   memoryCount: number;
+  /** Memories that are neither expired nor superseded. */
   activeMemoryCount: number;
+  /** Memories whose `expiresAt` has passed. */
   expiredMemoryCount: number;
+  /** Memories that have been superseded by a newer one. */
   supersededMemoryCount: number;
 }
+/**
+ * Stats aggregated across all entities, returned by
+ * {@link MnemocyteClient.stats} when no `entityId` is provided.
+ */
 interface GlobalStats {
+  /** Number of distinct entities with at least one memory. */
   entityCount: number;
+  /** Total number of memories across all entities. */
   memoryCount: number;
+  /** Memories that are neither expired nor superseded. */
   activeMemoryCount: number;
+  /** Memories whose `expiresAt` has passed. */
   expiredMemoryCount: number;
+  /** Memories that have been superseded by a newer one. */
   supersededMemoryCount: number;
 }
+/**
+ * The Mnemocyte client. Returned by {@link createMnemocyte}.
+ *
+ * Every method may throw {@link MnemocyteError}; use {@link isMnemocyteError}
+ * to narrow caught values.
+ */
 interface MnemocyteClient {
+  /**
+   * Persist a single memory and return the stored record.
+   *
+   * @throws {MnemocyteError} `"VALIDATION"` for invalid input, `"EMBEDDING"`
+   * if the embedder fails, `"DB"` for storage failures.
+   */
   remember(input: RememberInput): Promise<Memory>;
+  /**
+   * Persist multiple memories in one round-trip. Returns the stored records
+   * in the same order as `inputs`.
+   */
   rememberMany(inputs: readonly RememberInput[]): Promise<Memory[]>;
+  /**
+   * Retrieve the most relevant memories for `input.query`, ranked by the
+   * configured {@link RetrievalConfig}.
+   */
   recall(input: RecallInput): Promise<MemoryWithScore[]>;
+  /**
+   * Build a prompt-ready context string from the most relevant memories.
+   * Respects {@link BuildContextInput.maxTokens} when supplied.
+   */
   buildContext(input: BuildContextInput): Promise<string>;
+  /**
+   * Delete a specific memory belonging to `entityId`.
+   *
+   * @throws {MnemocyteError} `"NOT_FOUND"` if the memory does not exist
+   * or does not belong to `entityId`.
+   */
   forget(input: {
     entityId: string;
     memoryId: string;
   }): Promise<void>;
+  /** Delete every memory belonging to `entityId`. */
   forgetAll(input: {
     entityId: string;
   }): Promise<void>;
+  /**
+   * Bulk-delete memories matching the filters on {@link PruneInput}.
+   *
+   * At least one filter must be specified; an empty input throws a
+   * `"VALIDATION"` {@link MnemocyteError} to avoid accidental full
+   * deletion. Pass `dryRun: true` to count without deleting.
+   *
+   * @example Evict expired or stale memories for an entity
+   * ```ts
+   * await client.prune({
+   *   entityId: "user_123",
+   *   expired: true,
+   * });
+   *
+   * await client.prune({
+   *   notAccessedSince: new Date(Date.now() - 30 * 24 * 3600 * 1000),
+   *   maxImportance: "normal",
+   * });
+   * ```
+   */
+  prune(input: PruneInput): Promise<PruneResult>;
+  /**
+   * Scan an entity's memories for likely duplicates by pairwise cosine
+   * similarity and return matching pairs, ordered by descending
+   * similarity. Read-only — no memories are modified.
+   *
+   * @experimental Part of Phase 6 (consolidation tooling). API may change.
+   *
+   * @example
+   * ```ts
+   * const pairs = await client.findDuplicates({
+   *   entityId: "user_123",
+   *   threshold: 0.95,
+   *   limit: 50,
+   * });
+   * for (const { a, b, similarity } of pairs) {
+   *   console.log(similarity, a.content, "<>", b.content);
+   * }
+   * ```
+   */
+  findDuplicates(input: FindDuplicatesInput): Promise<DuplicatePair[]>;
+  /**
+   * Return audit-log entries for `entityId`, newest first.
+   *
+   * Entries are recorded automatically when
+   * {@link MnemocyteConfig.audit}.`enabled` is `true`. Historic entries
+   * remain readable even after toggling `enabled` back to `false`.
+   *
+   * @experimental Part of Phase 6 (consolidation tooling). API may change.
+   *
+   * @example
+   * ```ts
+   * const log = await client.listAuditLog({
+   *   entityId: "user_123",
+   *   limit: 100,
+   * });
+   * for (const event of log) {
+   *   console.log(event.timestamp, event.description, event.metadata);
+   * }
+   * ```
+   */
+  listAuditLog(input: ListAuditLogInput): Promise<AuditEvent[]>;
+  /**
+   * Unstable, opt-in extension surface. Members may change or be
+   * removed without a semver bump until they graduate to the main
+   * client interface.
+   *
+   * @experimental Part of Phase 6 (consolidation tooling).
+   */
+  experimental: ExperimentalMnemocyteClient;
+  /**
+   * Return statistics. With an `entityId`, returns {@link EntityStats};
+   * without one, returns {@link GlobalStats}.
+   */
   stats(input?: {
     entityId?: string;
   }): Promise<EntityStats | GlobalStats>;
+  /**
+   * Release any underlying resources (e.g. the Postgres connection pool).
+   * Safe to call multiple times. The client must not be used afterward.
+   */
   close(): Promise<void>;
 }
+/**
+ * Extension surface for unstable Phase 6 operations. Reached via
+ * {@link MnemocyteClient.experimental}.
+ *
+ * @experimental Members may change or be removed without a semver bump.
+ */
+interface ExperimentalMnemocyteClient {
+  /**
+   * Consolidate likely-duplicate memories into a single survivor by
+   * marking the others as superseded. Optionally unions their tags
+   * onto the survivor. Idempotent for memories that are already
+   * superseded.
+   *
+   * Emits one `"memory.superseded"` audit event per newly superseded
+   * memory when {@link MnemocyteConfig.audit}.`enabled` is `true`.
+   *
+   * @experimental Part of Phase 6 (consolidation tooling). API may change.
+   *
+   * @throws {MnemocyteError} `"VALIDATION"` for empty `supersededIds`,
+   * a `survivorId` that also appears in `supersededIds`, or a survivor
+   * that is itself already superseded.
+   * @throws {MnemocyteError} `"NOT_FOUND"` if the survivor or any
+   * non-already-superseded memory in `supersededIds` does not belong
+   * to `entityId`.
+   *
+   * @example
+   * ```ts
+   * const pairs = await client.findDuplicates({ entityId: "user_123" });
+   * for (const { a, b } of pairs) {
+   *   await client.experimental.consolidate({
+   *     entityId: "user_123",
+   *     survivorId: a.id,
+   *     supersededIds: [b.id],
+   *   });
+   * }
+   * ```
+   */
+  consolidate(input: ConsolidateInput): Promise<ConsolidateResult>;
+}
 //#endregion
 //#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.
+ *
+ * The returned client owns any underlying resources (e.g. the Postgres
+ * connection pool). Call {@link MnemocyteClient.close} when finished to
+ * release them.
+ *
+ * @param config - Client configuration. {@link MnemocyteConfig.embedder} is required.
+ * @returns A {@link MnemocyteClient} instance.
+ * @throws {MnemocyteError} With code `"CONFIG"` if `embedder` is missing or
+ * invalid (including when `databaseUrl` is set and `embedder.dimensions`
+ * is not 1536 — the dimensionality pinned by the bundled migration), or
+ * `"VALIDATION"` if `databaseUrl` is provided but empty.
+ *
+ * @example Postgres-backed client
+ * ```ts
+ * const client = createMnemocyte({
+ *   databaseUrl: process.env.DATABASE_URL,
+ *   embedder, // embedder.dimensions MUST be 1536 for the Postgres backend
+ * });
+ * ```
+ */
 declare function createMnemocyte(config: MnemocyteConfig): MnemocyteClient;
 //#endregion
 //#region src/errors.d.ts
-type MnemocyteErrorCode = "CONFIG" | "VALIDATION" | "DB" | "EMBEDDING" | "NOT_FOUND" | "MIGRATION";
+/**
+ * Stable, machine-readable error code attached to every {@link MnemocyteError}.
+ *
+ * - `"CONFIG"` — invalid client configuration (e.g. missing or malformed embedder).
+ * - `"VALIDATION"` — invalid argument passed to a client method.
+ * - `"DB"` — Postgres or driver-level failure.
+ * - `"EMBEDDING"` — embedder threw or returned an invalid vector.
+ * - `"NOT_FOUND"` — referenced memory or entity does not exist.
+ * - `"MIGRATION"` — schema/migration check failed against the target database.
+ * - `"TIMEOUT"` — a provider call exceeded its configured timeout.
+ * - `"ABORTED"` — the operation was cancelled via an `AbortSignal`.
+ */
+type MnemocyteErrorCode = "CONFIG" | "VALIDATION" | "DB" | "EMBEDDING" | "NOT_FOUND" | "MIGRATION" | "TIMEOUT" | "ABORTED";
+/**
+ * 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;
+ * }
+ * ```
+ */
 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). */
   readonly cause?: unknown;
+  /**
+   * @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: string, code: MnemocyteErrorCode, cause?: unknown);
 }
+/**
+ * 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}.
+ */
 declare function isMnemocyteError(error: unknown): error is MnemocyteError;
 //#endregion
-export { type BuildContextInput, type ContextFormat, type Embedder, type EntityStats, type GlobalStats, type ImportanceLevel, type Memory, type MemoryType, type MemoryWithScore, type MnemocyteBackend, type MnemocyteClient, type MnemocyteConfig, MnemocyteError, type MnemocyteErrorCode, type MnemocyteObservation, type MnemocyteObservationPhase, type MnemocyteOperation, type ObservabilityConfig, type RecallInput, type RememberInput, type RetrievalConfig, type RetrievalExplanation, type RetrievalScoreWeights, type RetrievalScores, type TokenCounter, createMnemocyte, isMnemocyteError };
+export { type AuditConfig, type AuditEvent, type BuildContextInput, type ConsolidateInput, type ConsolidateResult, type ContextFormat, type DuplicatePair, type Embedder, type EntityStats, type ExperimentalMnemocyteClient, type FindDuplicatesInput, type GlobalStats, type ImportanceLevel, 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 RetrievalConfig, type RetrievalExplanation, type RetrievalScoreWeights, type RetrievalScores, type TokenCounter, createMnemocyte, isMnemocyteError };
 //# sourceMappingURL=index.d.mts.map