@amemhq/core 1.0.0 → 1.1.0

package/dist/index.d.cts

@@ -16,6 +16,43 @@ declare function configure(opts: {
 declare const DEFAULT_EMBEDDING_MODEL = "Xenova/paraphrase-multilingual-MiniLM-L12-v2";
 /** Which model this process embeds with. */
 declare function getEmbeddingModel(): string;
+/** How token embeddings are collapsed into one sentence vector. */
+type PoolingMode = 'mean' | 'cls';
+/**
+ * Which pooling this process uses: `AMEM_EMBED_POOLING`, else the model's known
+ * mode, else `mean`.
+ *
+ * Getting this wrong does not fail. `encode()` returns a normalized vector of the
+ * right width either way, and search keeps working because notes and queries are
+ * embedded by the same function — it just retrieves worse than the model can,
+ * with nothing to indicate it. That is why the mode is resolved rather than
+ * assumed.
+ */
+declare function getEmbeddingPooling(): PoolingMode;
+/**
+ * Where inference runs. Unset means Transformers.js picks, which on Node is `cpu`.
+ *
+ * It is not CPU-only for lack of anything else: `onnxruntime-node`'s macOS arm64
+ * binary links CoreML.framework and exports the CoreML provider, and
+ * Transformers.js lists `coreml` (macOS), `dml` (Windows), `cuda` (Linux x64) and
+ * `webgpu` alongside `cpu`. It simply defaults to `cpu` and amem never asked for
+ * anything else.
+ *
+ * Whether asking helps is **unmeasured**. CoreML partitions a graph operator by
+ * operator and falls back to CPU for the ones it cannot take, so it can lose to
+ * plain CPU on some models and pay a compile cost on first load. Hence: opt-in,
+ * default unchanged, and no recommendation until someone benchmarks it.
+ */
+declare function getEmbeddingDevice(): string | undefined;
+/**
+ * Weight precision. Unset means Transformers.js picks, which on Node is `fp32` —
+ * the largest download of every variant a model publishes.
+ *
+ * Passed through rather than validated against a list: Transformers.js already
+ * rejects an unknown value and names the valid ones, and a list here would go
+ * stale the moment it gains a quantization.
+ */
+declare function getEmbeddingDtype(): string | undefined;
 /**
  * The vector width this model produces, measured rather than looked up.
  *
@@ -26,7 +63,8 @@ declare function getEmbeddingModel(): string;
  */
 declare function getEmbeddingDim(): Promise<number>;
 /**
- * Encode text to 384-dim normalized embedding vector.
+ * Encode text to a normalized embedding vector. The width is the model's — 384
+ * for the default, 1024 for bge-m3 — so nothing here should assume a number.
  * Singleton model, loaded once and reused.
  */
 declare function encode(text: string): Promise<number[]>;
@@ -140,6 +178,18 @@ declare class EmbeddingDimensionMismatchError extends Error {
     readonly model: string;
     constructor(collection: string, collectionDim: number, modelDim: number, model: string);
 }
+/**
+ * Which embedding model built a collection, and what the process wants to use.
+ *
+ * Vector width is the only thing Qdrant can check for us, and two models of the
+ * same width are indistinguishable to it. This is the case that check misses.
+ */
+declare class EmbeddingModelMismatchError extends Error {
+    readonly collection: string;
+    readonly collectionModel: string;
+    readonly configuredModel: string;
+    constructor(collection: string, collectionModel: string, configuredModel: string);
+}
 /**
  * Ask Qdrant whether it can serve, right now.
  *
@@ -499,4 +549,4 @@ declare function llmCrudDecision(userText: string, assistantText: string, existi
     content: string;
 }>): Promise<MemoryOperation[]>;
 
-export { type AgentAmemConfig, type AmemPluginConfig, type ConflictMode, type ConflictSweepResult, DEFAULT_CRUD_UPDATE_MIN_SIM, DEFAULT_EMBEDDING_MODEL, EmbeddingDimensionMismatchError, type EvolutionEntry, type LlmConfig, type LowQualityItem, type LowQualityReason, type MemoryNote, type MemoryOperation, type MigrateResult, type QueryResult, type SearchResult, type StorageContext, addEpisodic, addMemory, canRead, canWrite, checkQuality, configure, configureLlm, conflictSweep, consolidateMemories, createStorageContext, deleteNote, encode, ensureCollection, generateReviewBatch, getEmbeddingDim, getEmbeddingModel, getNote, invalidateNote, isModelLoaded, isPlausibleUpdateTarget, listMemories, listNotes, llmCrudDecision, loadModel, mergeSimilarNotes, migrateCollection, patchNotePayload, pingQdrant, resolveCrudUpdateMinSim, scanLowQuality, searchMemory, updateNote };
+export { type AgentAmemConfig, type AmemPluginConfig, type ConflictMode, type ConflictSweepResult, DEFAULT_CRUD_UPDATE_MIN_SIM, DEFAULT_EMBEDDING_MODEL, EmbeddingDimensionMismatchError, EmbeddingModelMismatchError, type EvolutionEntry, type LlmConfig, type LowQualityItem, type LowQualityReason, type MemoryNote, type MemoryOperation, type MigrateResult, type PoolingMode, type QueryResult, type SearchResult, type StorageContext, addEpisodic, addMemory, canRead, canWrite, checkQuality, configure, configureLlm, conflictSweep, consolidateMemories, createStorageContext, deleteNote, encode, ensureCollection, generateReviewBatch, getEmbeddingDevice, getEmbeddingDim, getEmbeddingDtype, getEmbeddingModel, getEmbeddingPooling, getNote, invalidateNote, isModelLoaded, isPlausibleUpdateTarget, listMemories, listNotes, llmCrudDecision, loadModel, mergeSimilarNotes, migrateCollection, patchNotePayload, pingQdrant, resolveCrudUpdateMinSim, scanLowQuality, searchMemory, updateNote };

package/dist/index.d.ts

@@ -16,6 +16,43 @@ declare function configure(opts: {
 declare const DEFAULT_EMBEDDING_MODEL = "Xenova/paraphrase-multilingual-MiniLM-L12-v2";
 /** Which model this process embeds with. */
 declare function getEmbeddingModel(): string;
+/** How token embeddings are collapsed into one sentence vector. */
+type PoolingMode = 'mean' | 'cls';
+/**
+ * Which pooling this process uses: `AMEM_EMBED_POOLING`, else the model's known
+ * mode, else `mean`.
+ *
+ * Getting this wrong does not fail. `encode()` returns a normalized vector of the
+ * right width either way, and search keeps working because notes and queries are
+ * embedded by the same function — it just retrieves worse than the model can,
+ * with nothing to indicate it. That is why the mode is resolved rather than
+ * assumed.
+ */
+declare function getEmbeddingPooling(): PoolingMode;
+/**
+ * Where inference runs. Unset means Transformers.js picks, which on Node is `cpu`.
+ *
+ * It is not CPU-only for lack of anything else: `onnxruntime-node`'s macOS arm64
+ * binary links CoreML.framework and exports the CoreML provider, and
+ * Transformers.js lists `coreml` (macOS), `dml` (Windows), `cuda` (Linux x64) and
+ * `webgpu` alongside `cpu`. It simply defaults to `cpu` and amem never asked for
+ * anything else.
+ *
+ * Whether asking helps is **unmeasured**. CoreML partitions a graph operator by
+ * operator and falls back to CPU for the ones it cannot take, so it can lose to
+ * plain CPU on some models and pay a compile cost on first load. Hence: opt-in,
+ * default unchanged, and no recommendation until someone benchmarks it.
+ */
+declare function getEmbeddingDevice(): string | undefined;
+/**
+ * Weight precision. Unset means Transformers.js picks, which on Node is `fp32` —
+ * the largest download of every variant a model publishes.
+ *
+ * Passed through rather than validated against a list: Transformers.js already
+ * rejects an unknown value and names the valid ones, and a list here would go
+ * stale the moment it gains a quantization.
+ */
+declare function getEmbeddingDtype(): string | undefined;
 /**
  * The vector width this model produces, measured rather than looked up.
  *
@@ -26,7 +63,8 @@ declare function getEmbeddingModel(): string;
  */
 declare function getEmbeddingDim(): Promise<number>;
 /**
- * Encode text to 384-dim normalized embedding vector.
+ * Encode text to a normalized embedding vector. The width is the model's — 384
+ * for the default, 1024 for bge-m3 — so nothing here should assume a number.
  * Singleton model, loaded once and reused.
  */
 declare function encode(text: string): Promise<number[]>;
@@ -140,6 +178,18 @@ declare class EmbeddingDimensionMismatchError extends Error {
     readonly model: string;
     constructor(collection: string, collectionDim: number, modelDim: number, model: string);
 }
+/**
+ * Which embedding model built a collection, and what the process wants to use.
+ *
+ * Vector width is the only thing Qdrant can check for us, and two models of the
+ * same width are indistinguishable to it. This is the case that check misses.
+ */
+declare class EmbeddingModelMismatchError extends Error {
+    readonly collection: string;
+    readonly collectionModel: string;
+    readonly configuredModel: string;
+    constructor(collection: string, collectionModel: string, configuredModel: string);
+}
 /**
  * Ask Qdrant whether it can serve, right now.
  *
@@ -499,4 +549,4 @@ declare function llmCrudDecision(userText: string, assistantText: string, existi
     content: string;
 }>): Promise<MemoryOperation[]>;
 
-export { type AgentAmemConfig, type AmemPluginConfig, type ConflictMode, type ConflictSweepResult, DEFAULT_CRUD_UPDATE_MIN_SIM, DEFAULT_EMBEDDING_MODEL, EmbeddingDimensionMismatchError, type EvolutionEntry, type LlmConfig, type LowQualityItem, type LowQualityReason, type MemoryNote, type MemoryOperation, type MigrateResult, type QueryResult, type SearchResult, type StorageContext, addEpisodic, addMemory, canRead, canWrite, checkQuality, configure, configureLlm, conflictSweep, consolidateMemories, createStorageContext, deleteNote, encode, ensureCollection, generateReviewBatch, getEmbeddingDim, getEmbeddingModel, getNote, invalidateNote, isModelLoaded, isPlausibleUpdateTarget, listMemories, listNotes, llmCrudDecision, loadModel, mergeSimilarNotes, migrateCollection, patchNotePayload, pingQdrant, resolveCrudUpdateMinSim, scanLowQuality, searchMemory, updateNote };
+export { type AgentAmemConfig, type AmemPluginConfig, type ConflictMode, type ConflictSweepResult, DEFAULT_CRUD_UPDATE_MIN_SIM, DEFAULT_EMBEDDING_MODEL, EmbeddingDimensionMismatchError, EmbeddingModelMismatchError, type EvolutionEntry, type LlmConfig, type LowQualityItem, type LowQualityReason, type MemoryNote, type MemoryOperation, type MigrateResult, type PoolingMode, type QueryResult, type SearchResult, type StorageContext, addEpisodic, addMemory, canRead, canWrite, checkQuality, configure, configureLlm, conflictSweep, consolidateMemories, createStorageContext, deleteNote, encode, ensureCollection, generateReviewBatch, getEmbeddingDevice, getEmbeddingDim, getEmbeddingDtype, getEmbeddingModel, getEmbeddingPooling, getNote, invalidateNote, isModelLoaded, isPlausibleUpdateTarget, listMemories, listNotes, llmCrudDecision, loadModel, mergeSimilarNotes, migrateCollection, patchNotePayload, pingQdrant, resolveCrudUpdateMinSim, scanLowQuality, searchMemory, updateNote };