@amemhq/core 1.0.1 → 2.0.0

package/dist/index.d.cts

@@ -6,15 +6,37 @@ declare function configure(opts: {
  * embedding.ts — Local ONNX embedding via @huggingface/transformers
  * Matches Python: SentenceTransformer.encode(text, normalize_embeddings=True)
  *
- * The model is selectable because the default is not a good retrieval model: it
- * caps at 128 tokens, so anything longer is truncated before it reaches the
- * vector. Changing it is a breaking change whenever the dimension differs —
- * Qdrant fixes a collection's vector size at creation — so the default stays put
- * and the switch is opt-in. See docs/reference/embedding-models.md.
- */
-/** The model shipped since the beginning. Not changed here on purpose. */
-declare const DEFAULT_EMBEDDING_MODEL = "Xenova/paraphrase-multilingual-MiniLM-L12-v2";
-/** Which model this process embeds with. */
+ * The model is selectable, and changing it is a breaking change whenever the
+ * dimension differs — Qdrant fixes a collection's vector size at creation. So
+ * nothing here decides on its own: a collection that already exists keeps the
+ * model it was built with (see `pinEmbeddingModel`), and moving is a deliberate
+ * `amem-migrate` run. See docs/reference/embedding-models.md.
+ */
+/**
+ * What a fresh install embeds with.
+ *
+ * Chosen for having no architectural question mark rather than for topping a
+ * leaderboard: XLM-RoBERTa, natively supported by Transformers.js, its ONNX
+ * maintained by that library's own author. 8192 tokens against the 128 of the
+ * model this replaced, which is the whole reason for the change — anything longer
+ * than a couple of sentences was being truncated before it reached the vector.
+ */
+declare const DEFAULT_EMBEDDING_MODEL = "Xenova/bge-m3";
+/**
+ * The default before 2.0.0. Every store built by an earlier version holds its
+ * vectors, and nothing recorded that at the time — `LEGACY_DEFAULT_DIM` is how a
+ * collection from back then is recognised.
+ */
+declare const LEGACY_DEFAULT_EMBEDDING_MODEL = "Xenova/paraphrase-multilingual-MiniLM-L12-v2";
+declare const LEGACY_DEFAULT_DIM = 384;
+/**
+ * Which model this process embeds with: the env var, else whatever the open
+ * collection was built with, else the shipped default.
+ *
+ * An explicit `AMEM_EMBED_MODEL` outranks the pin on purpose — someone who set it
+ * is migrating deliberately, and silently overriding them with the collection's
+ * old model would make the setting look broken.
+ */
 declare function getEmbeddingModel(): string;
 /** How token embeddings are collapsed into one sentence vector. */
 type PoolingMode = 'mean' | 'cls';
@@ -29,6 +51,30 @@ type PoolingMode = 'mean' | 'cls';
  * 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.
  *
@@ -39,7 +85,9 @@ declare function getEmbeddingPooling(): PoolingMode;
  */
 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 — 1024
+ * for the default, 384 for the one before it — so nothing here should assume a
+ * number.
  * Singleton model, loaded once and reused.
  */
 declare function encode(text: string): Promise<number[]>;
@@ -58,7 +106,8 @@ declare function isModelLoaded(): boolean;
 /**
  * storage.ts — Qdrant vector storage for A-MEM
  * Uses native fetch (Node 18+) to avoid undici compatibility issues with Node v26
- * Collection: amem_notes, 384-dim cosine, with agent_id isolation
+ * Collection: amem_notes, cosine, width set by the embedding model, with
+ * agent_id isolation
  */
 /** Per-agent override config. If collection is set, mode B (isolated collection) is used. */
 interface AgentAmemConfig {
@@ -153,6 +202,33 @@ 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);
+}
+/**
+ * Two collections open in one process that need two different models.
+ *
+ * Only reachable in mode B, and normally only mid-migration: per-agent
+ * collections built before 2.0.0 all resolve to the same old model, until one of
+ * them is migrated and the others are not. One process embeds with one model, so
+ * this has to stop rather than pick a winner — picking would write vectors of the
+ * wrong width into whichever collection lost.
+ */
+declare class MixedEmbeddingModelsError extends Error {
+    readonly collection: string;
+    readonly wanted: string;
+    readonly inUse: string;
+    constructor(collection: string, wanted: string, inUse: string);
+}
 /**
  * Ask Qdrant whether it can serve, right now.
  *
@@ -178,28 +254,34 @@ declare function makeCrud(collectionName: string, modeBIsolated?: boolean): {
     addNote(note: MemoryNote): Promise<void>;
     /**
      * Story 36: this is the one read that bypasses the agent filter — it fetches
-     * straight by UUID. Pass `readerAgentId` to enforce `readers`; an unreadable
-     * note comes back as `null` (indistinguishable from missing, so nothing leaks,
-     * and callers already handle null). Omitting it skips the check, preserving
-     * behaviour for internal callers that only ever hold their own ids.
+     * straight by UUID. An unreadable note comes back as `null`, indistinguishable
+     * from missing, so nothing leaks and callers already handle it.
+     *
+     * `reader` is required. It used to be optional, and omitting it skipped the
+     * check — which meant the safe behaviour was the one you had to remember to
+     * ask for. Pass `SYSTEM_ACTOR` to read as the engine itself; that reads as a
+     * deliberate act at the call site, where an absent argument did not.
      */
-    getNote(id: string, readerAgentId?: string): Promise<MemoryNote | null>;
+    getNote(id: string, reader: string): Promise<MemoryNote | null>;
     updateNote(note: MemoryNote): Promise<void>;
     findByHash(hash: string, agentId: string): Promise<MemoryNote | null>;
     /**
-     * Story 33: pass `callerAgentId` to enforce the writers policy. Callers that
-     * hold the note already should prefer checking `canWrite` themselves; this
-     * fetch-then-check path exists for callers that only have an id (the plugin's
-     * CRUD hook). Returns false — without writing — when the caller may not write.
-     * Omitting `callerAgentId` skips the check, preserving existing behaviour for
-     * internal callers that are already scoped to their own notes.
+     * Story 33: enforces the writers policy. Returns false — without writing —
+     * when the caller may not write. This fetch-then-check path exists for callers
+     * that only have an id (the plugin's CRUD hook); callers already holding the
+     * note can check `canWrite` themselves and skip a round trip.
+     *
+     * `caller` is required. Pass `SYSTEM_ACTOR` for the engine's own maintenance
+     * writes. The self-read below is a genuine `SYSTEM_ACTOR` case: it fetches the
+     * note in order to decide whether the caller may write it, and gating that
+     * fetch on the same policy it exists to evaluate would be circular.
      */
-    updateNoteContent(id: string, content: string, embedding: number[], hash: string, callerAgentId?: string): Promise<boolean>;
+    updateNoteContent(id: string, content: string, embedding: number[], hash: string, caller: string): Promise<boolean>;
     queryByEmbedding(embedding: number[], topK: number, agentId: string, scoreThreshold?: number, subject?: string): Promise<QueryResult[]>;
     listNotes(agentId?: string, subject?: string): Promise<MemoryNote[]>;
     deleteNote(id: string): Promise<void>;
     /** Story 33: see `updateNoteContent` — returns false, unwritten, when denied. */
-    invalidateNote(id: string, callerAgentId?: string): Promise<boolean>;
+    invalidateNote(id: string, caller: string): Promise<boolean>;
     getNotesByDatePrefix(datePrefix: string, agentId: string): Promise<MemoryNote[]>;
     countNotes(agentId?: string): Promise<number>;
     updateNoteLinks(id: string, links: string[]): Promise<void>;
@@ -213,11 +295,11 @@ type StorageContext = ReturnType<typeof makeCrud>;
  * Mode B (isolated collection): pass collectionName = 'amem_notes_<agentId>' and modeBIsolated = true.
  */
 declare function createStorageContext(collectionName?: string, modeBIsolated?: boolean): StorageContext;
-declare function getNote(id: string, readerAgentId?: string): Promise<MemoryNote | null>;
+declare function getNote(id: string, reader: string): Promise<MemoryNote | null>;
 declare function updateNote(note: MemoryNote): Promise<void>;
 declare function listNotes(agentId?: string, subject?: string): Promise<MemoryNote[]>;
 declare function deleteNote(id: string): Promise<void>;
-declare function invalidateNote(id: string, callerAgentId?: string): Promise<boolean>;
+declare function invalidateNote(id: string, caller: string): Promise<boolean>;
 declare function patchNotePayload(id: string, fields: Record<string, unknown>): Promise<void>;
 
 /**
@@ -267,8 +349,28 @@ interface SearchResult {
     keywords: string[];
     links: string[];
     timestamp: string;
+    /**
+     * Cosine similarity to the query. **Not** what ordered this list — that is
+     * `rrf`, which fuses the dense and BM25 rankings and then applies a heat/recency
+     * boost. The two disagree often, and a consumer that reads `similarity` as the
+     * ranking score concludes the ranking is broken.
+     */
     similarity: number;
+    /**
+     * The fused score the matches are sorted by, and 0 for anything no retriever
+     * ranked. It is `via`, not this, that says why a row is here.
+     */
     rrf: number;
+    /**
+     * Why this note is in the results.
+     *
+     * `match` — it was retrieved for the query and ranked by `rrf`.
+     * `link` — it was **not** retrieved; it is here because it links to one that
+     * was, within two hops and above the relevance gate. These are appended in
+     * discovery order after the matches and have no `rrf` of their own, so reading
+     * the tail of the list as "lower-ranked matches" is wrong.
+     */
+    via: 'match' | 'link';
     topics: string[];
     note_type: 'memory' | 'knowledge';
 }
@@ -374,6 +476,28 @@ declare function generateReviewBatch(agentId: string, outputPath?: string): Prom
  * policy is unit-testable on its own and identical everywhere it is applied.
  */
 
+/**
+ * The engine acting as itself, rather than on behalf of any agent.
+ *
+ * `getNote`, `updateNoteContent` and `invalidateNote` all used to take an
+ * *optional* identity, and omitting it skipped the authorization check. That put
+ * the safe behaviour behind remembering to ask for it, and made "no check here"
+ * invisible — an absent argument looks the same as an oversight. The identity is
+ * now required, and this is what a call declares when it genuinely has no agent
+ * on whose behalf it acts.
+ *
+ * Two call sites use it, both inside storage.ts: the fetch that
+ * `updateNoteContent` and `invalidateNote` perform in order to *evaluate* the
+ * write policy. Gating that read on the policy it exists to check would be
+ * circular. Everything else passes a real agent id — the audit that prompted this
+ * found the identity was already in scope at every one of them.
+ *
+ * The prefix keeps it from colliding with any plausible agent id. It is not a
+ * secret and does not need to be: amem is self-hosted, the operator owns every
+ * memory in the store, and there is no privilege boundary here to defend. This
+ * guards against a call site forgetting to pass an identity, not against a user.
+ */
+declare const SYSTEM_ACTOR = "__amem_system__";
 /**
  * May `callerAgentId` mutate `note`?
  *
@@ -403,8 +527,10 @@ interface MigrateResult {
     missingDerived: number;
     /** Notes whose fields were re-extracted. 0 unless refreshFields. */
     refreshed: number;
-    /** Notes written into the target. 0 on a dry run. */
+    /** Notes written into the target by THIS run. 0 on a dry run. */
     migrated: number;
+    /** Notes a previous interrupted run had already written. */
+    skipped: number;
     sourceDim: number | null;
     targetDim: number;
     model: string;
@@ -424,6 +550,33 @@ declare function migrateCollection(opts: {
         warn: (m: string) => void;
     };
 }): Promise<MigrateResult>;
+/**
+ * Put the migrated collection behind the name the source used, and drop the
+ * source.
+ *
+ * This is the only irreversible step in the whole migration, which is why it is
+ * a separate call rather than the tail of `migrateCollection`. Everything before
+ * it leaves the original untouched and can simply be abandoned.
+ *
+ * Qdrant cannot rename a collection and cannot create an alias over a name a real
+ * collection holds (409), so freeing the name means deleting it — after checking
+ * the target holds at least as much as the source, because that check is the last
+ * thing standing between a half-finished migration and a deleted store.
+ */
+declare function switchToMigrated(opts: {
+    /** The name readers are configured with. Becomes an alias. */
+    name: string;
+    /** The collection built by `migrateCollection`. */
+    to: string;
+    logger?: {
+        info: (m: string) => void;
+        warn: (m: string) => void;
+    };
+}): Promise<{
+    name: string;
+    to: string;
+    moved: number;
+}>;
 
 /**
  * Similarity floor for accepting an UPDATE target.
@@ -512,4 +665,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 PoolingMode, type QueryResult, type SearchResult, type StorageContext, addEpisodic, addMemory, canRead, canWrite, checkQuality, configure, configureLlm, conflictSweep, consolidateMemories, createStorageContext, deleteNote, encode, ensureCollection, generateReviewBatch, getEmbeddingDim, getEmbeddingModel, getEmbeddingPooling, 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, LEGACY_DEFAULT_DIM, LEGACY_DEFAULT_EMBEDDING_MODEL, type LlmConfig, type LowQualityItem, type LowQualityReason, type MemoryNote, type MemoryOperation, type MigrateResult, MixedEmbeddingModelsError, type PoolingMode, type QueryResult, SYSTEM_ACTOR, 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, switchToMigrated, updateNote };

package/dist/index.d.ts

@@ -6,15 +6,37 @@ declare function configure(opts: {
  * embedding.ts — Local ONNX embedding via @huggingface/transformers
  * Matches Python: SentenceTransformer.encode(text, normalize_embeddings=True)
  *
- * The model is selectable because the default is not a good retrieval model: it
- * caps at 128 tokens, so anything longer is truncated before it reaches the
- * vector. Changing it is a breaking change whenever the dimension differs —
- * Qdrant fixes a collection's vector size at creation — so the default stays put
- * and the switch is opt-in. See docs/reference/embedding-models.md.
- */
-/** The model shipped since the beginning. Not changed here on purpose. */
-declare const DEFAULT_EMBEDDING_MODEL = "Xenova/paraphrase-multilingual-MiniLM-L12-v2";
-/** Which model this process embeds with. */
+ * The model is selectable, and changing it is a breaking change whenever the
+ * dimension differs — Qdrant fixes a collection's vector size at creation. So
+ * nothing here decides on its own: a collection that already exists keeps the
+ * model it was built with (see `pinEmbeddingModel`), and moving is a deliberate
+ * `amem-migrate` run. See docs/reference/embedding-models.md.
+ */
+/**
+ * What a fresh install embeds with.
+ *
+ * Chosen for having no architectural question mark rather than for topping a
+ * leaderboard: XLM-RoBERTa, natively supported by Transformers.js, its ONNX
+ * maintained by that library's own author. 8192 tokens against the 128 of the
+ * model this replaced, which is the whole reason for the change — anything longer
+ * than a couple of sentences was being truncated before it reached the vector.
+ */
+declare const DEFAULT_EMBEDDING_MODEL = "Xenova/bge-m3";
+/**
+ * The default before 2.0.0. Every store built by an earlier version holds its
+ * vectors, and nothing recorded that at the time — `LEGACY_DEFAULT_DIM` is how a
+ * collection from back then is recognised.
+ */
+declare const LEGACY_DEFAULT_EMBEDDING_MODEL = "Xenova/paraphrase-multilingual-MiniLM-L12-v2";
+declare const LEGACY_DEFAULT_DIM = 384;
+/**
+ * Which model this process embeds with: the env var, else whatever the open
+ * collection was built with, else the shipped default.
+ *
+ * An explicit `AMEM_EMBED_MODEL` outranks the pin on purpose — someone who set it
+ * is migrating deliberately, and silently overriding them with the collection's
+ * old model would make the setting look broken.
+ */
 declare function getEmbeddingModel(): string;
 /** How token embeddings are collapsed into one sentence vector. */
 type PoolingMode = 'mean' | 'cls';
@@ -29,6 +51,30 @@ type PoolingMode = 'mean' | 'cls';
  * 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.
  *
@@ -39,7 +85,9 @@ declare function getEmbeddingPooling(): PoolingMode;
  */
 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 — 1024
+ * for the default, 384 for the one before it — so nothing here should assume a
+ * number.
  * Singleton model, loaded once and reused.
  */
 declare function encode(text: string): Promise<number[]>;
@@ -58,7 +106,8 @@ declare function isModelLoaded(): boolean;
 /**
  * storage.ts — Qdrant vector storage for A-MEM
  * Uses native fetch (Node 18+) to avoid undici compatibility issues with Node v26
- * Collection: amem_notes, 384-dim cosine, with agent_id isolation
+ * Collection: amem_notes, cosine, width set by the embedding model, with
+ * agent_id isolation
  */
 /** Per-agent override config. If collection is set, mode B (isolated collection) is used. */
 interface AgentAmemConfig {
@@ -153,6 +202,33 @@ 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);
+}
+/**
+ * Two collections open in one process that need two different models.
+ *
+ * Only reachable in mode B, and normally only mid-migration: per-agent
+ * collections built before 2.0.0 all resolve to the same old model, until one of
+ * them is migrated and the others are not. One process embeds with one model, so
+ * this has to stop rather than pick a winner — picking would write vectors of the
+ * wrong width into whichever collection lost.
+ */
+declare class MixedEmbeddingModelsError extends Error {
+    readonly collection: string;
+    readonly wanted: string;
+    readonly inUse: string;
+    constructor(collection: string, wanted: string, inUse: string);
+}
 /**
  * Ask Qdrant whether it can serve, right now.
  *
@@ -178,28 +254,34 @@ declare function makeCrud(collectionName: string, modeBIsolated?: boolean): {
     addNote(note: MemoryNote): Promise<void>;
     /**
      * Story 36: this is the one read that bypasses the agent filter — it fetches
-     * straight by UUID. Pass `readerAgentId` to enforce `readers`; an unreadable
-     * note comes back as `null` (indistinguishable from missing, so nothing leaks,
-     * and callers already handle null). Omitting it skips the check, preserving
-     * behaviour for internal callers that only ever hold their own ids.
+     * straight by UUID. An unreadable note comes back as `null`, indistinguishable
+     * from missing, so nothing leaks and callers already handle it.
+     *
+     * `reader` is required. It used to be optional, and omitting it skipped the
+     * check — which meant the safe behaviour was the one you had to remember to
+     * ask for. Pass `SYSTEM_ACTOR` to read as the engine itself; that reads as a
+     * deliberate act at the call site, where an absent argument did not.
      */
-    getNote(id: string, readerAgentId?: string): Promise<MemoryNote | null>;
+    getNote(id: string, reader: string): Promise<MemoryNote | null>;
     updateNote(note: MemoryNote): Promise<void>;
     findByHash(hash: string, agentId: string): Promise<MemoryNote | null>;
     /**
-     * Story 33: pass `callerAgentId` to enforce the writers policy. Callers that
-     * hold the note already should prefer checking `canWrite` themselves; this
-     * fetch-then-check path exists for callers that only have an id (the plugin's
-     * CRUD hook). Returns false — without writing — when the caller may not write.
-     * Omitting `callerAgentId` skips the check, preserving existing behaviour for
-     * internal callers that are already scoped to their own notes.
+     * Story 33: enforces the writers policy. Returns false — without writing —
+     * when the caller may not write. This fetch-then-check path exists for callers
+     * that only have an id (the plugin's CRUD hook); callers already holding the
+     * note can check `canWrite` themselves and skip a round trip.
+     *
+     * `caller` is required. Pass `SYSTEM_ACTOR` for the engine's own maintenance
+     * writes. The self-read below is a genuine `SYSTEM_ACTOR` case: it fetches the
+     * note in order to decide whether the caller may write it, and gating that
+     * fetch on the same policy it exists to evaluate would be circular.
      */
-    updateNoteContent(id: string, content: string, embedding: number[], hash: string, callerAgentId?: string): Promise<boolean>;
+    updateNoteContent(id: string, content: string, embedding: number[], hash: string, caller: string): Promise<boolean>;
     queryByEmbedding(embedding: number[], topK: number, agentId: string, scoreThreshold?: number, subject?: string): Promise<QueryResult[]>;
     listNotes(agentId?: string, subject?: string): Promise<MemoryNote[]>;
     deleteNote(id: string): Promise<void>;
     /** Story 33: see `updateNoteContent` — returns false, unwritten, when denied. */
-    invalidateNote(id: string, callerAgentId?: string): Promise<boolean>;
+    invalidateNote(id: string, caller: string): Promise<boolean>;
     getNotesByDatePrefix(datePrefix: string, agentId: string): Promise<MemoryNote[]>;
     countNotes(agentId?: string): Promise<number>;
     updateNoteLinks(id: string, links: string[]): Promise<void>;
@@ -213,11 +295,11 @@ type StorageContext = ReturnType<typeof makeCrud>;
  * Mode B (isolated collection): pass collectionName = 'amem_notes_<agentId>' and modeBIsolated = true.
  */
 declare function createStorageContext(collectionName?: string, modeBIsolated?: boolean): StorageContext;
-declare function getNote(id: string, readerAgentId?: string): Promise<MemoryNote | null>;
+declare function getNote(id: string, reader: string): Promise<MemoryNote | null>;
 declare function updateNote(note: MemoryNote): Promise<void>;
 declare function listNotes(agentId?: string, subject?: string): Promise<MemoryNote[]>;
 declare function deleteNote(id: string): Promise<void>;
-declare function invalidateNote(id: string, callerAgentId?: string): Promise<boolean>;
+declare function invalidateNote(id: string, caller: string): Promise<boolean>;
 declare function patchNotePayload(id: string, fields: Record<string, unknown>): Promise<void>;
 
 /**
@@ -267,8 +349,28 @@ interface SearchResult {
     keywords: string[];
     links: string[];
     timestamp: string;
+    /**
+     * Cosine similarity to the query. **Not** what ordered this list — that is
+     * `rrf`, which fuses the dense and BM25 rankings and then applies a heat/recency
+     * boost. The two disagree often, and a consumer that reads `similarity` as the
+     * ranking score concludes the ranking is broken.
+     */
     similarity: number;
+    /**
+     * The fused score the matches are sorted by, and 0 for anything no retriever
+     * ranked. It is `via`, not this, that says why a row is here.
+     */
     rrf: number;
+    /**
+     * Why this note is in the results.
+     *
+     * `match` — it was retrieved for the query and ranked by `rrf`.
+     * `link` — it was **not** retrieved; it is here because it links to one that
+     * was, within two hops and above the relevance gate. These are appended in
+     * discovery order after the matches and have no `rrf` of their own, so reading
+     * the tail of the list as "lower-ranked matches" is wrong.
+     */
+    via: 'match' | 'link';
     topics: string[];
     note_type: 'memory' | 'knowledge';
 }
@@ -374,6 +476,28 @@ declare function generateReviewBatch(agentId: string, outputPath?: string): Prom
  * policy is unit-testable on its own and identical everywhere it is applied.
  */
 
+/**
+ * The engine acting as itself, rather than on behalf of any agent.
+ *
+ * `getNote`, `updateNoteContent` and `invalidateNote` all used to take an
+ * *optional* identity, and omitting it skipped the authorization check. That put
+ * the safe behaviour behind remembering to ask for it, and made "no check here"
+ * invisible — an absent argument looks the same as an oversight. The identity is
+ * now required, and this is what a call declares when it genuinely has no agent
+ * on whose behalf it acts.
+ *
+ * Two call sites use it, both inside storage.ts: the fetch that
+ * `updateNoteContent` and `invalidateNote` perform in order to *evaluate* the
+ * write policy. Gating that read on the policy it exists to check would be
+ * circular. Everything else passes a real agent id — the audit that prompted this
+ * found the identity was already in scope at every one of them.
+ *
+ * The prefix keeps it from colliding with any plausible agent id. It is not a
+ * secret and does not need to be: amem is self-hosted, the operator owns every
+ * memory in the store, and there is no privilege boundary here to defend. This
+ * guards against a call site forgetting to pass an identity, not against a user.
+ */
+declare const SYSTEM_ACTOR = "__amem_system__";
 /**
  * May `callerAgentId` mutate `note`?
  *
@@ -403,8 +527,10 @@ interface MigrateResult {
     missingDerived: number;
     /** Notes whose fields were re-extracted. 0 unless refreshFields. */
     refreshed: number;
-    /** Notes written into the target. 0 on a dry run. */
+    /** Notes written into the target by THIS run. 0 on a dry run. */
     migrated: number;
+    /** Notes a previous interrupted run had already written. */
+    skipped: number;
     sourceDim: number | null;
     targetDim: number;
     model: string;
@@ -424,6 +550,33 @@ declare function migrateCollection(opts: {
         warn: (m: string) => void;
     };
 }): Promise<MigrateResult>;
+/**
+ * Put the migrated collection behind the name the source used, and drop the
+ * source.
+ *
+ * This is the only irreversible step in the whole migration, which is why it is
+ * a separate call rather than the tail of `migrateCollection`. Everything before
+ * it leaves the original untouched and can simply be abandoned.
+ *
+ * Qdrant cannot rename a collection and cannot create an alias over a name a real
+ * collection holds (409), so freeing the name means deleting it — after checking
+ * the target holds at least as much as the source, because that check is the last
+ * thing standing between a half-finished migration and a deleted store.
+ */
+declare function switchToMigrated(opts: {
+    /** The name readers are configured with. Becomes an alias. */
+    name: string;
+    /** The collection built by `migrateCollection`. */
+    to: string;
+    logger?: {
+        info: (m: string) => void;
+        warn: (m: string) => void;
+    };
+}): Promise<{
+    name: string;
+    to: string;
+    moved: number;
+}>;
 
 /**
  * Similarity floor for accepting an UPDATE target.
@@ -512,4 +665,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 PoolingMode, type QueryResult, type SearchResult, type StorageContext, addEpisodic, addMemory, canRead, canWrite, checkQuality, configure, configureLlm, conflictSweep, consolidateMemories, createStorageContext, deleteNote, encode, ensureCollection, generateReviewBatch, getEmbeddingDim, getEmbeddingModel, getEmbeddingPooling, 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, LEGACY_DEFAULT_DIM, LEGACY_DEFAULT_EMBEDDING_MODEL, type LlmConfig, type LowQualityItem, type LowQualityReason, type MemoryNote, type MemoryOperation, type MigrateResult, MixedEmbeddingModelsError, type PoolingMode, type QueryResult, SYSTEM_ACTOR, 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, switchToMigrated, updateNote };