@amemhq/core 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,502 @@
+declare function configure(opts: {
+    dataDir?: string;
+}): void;
+
+/**
+ * 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. */
+declare function getEmbeddingModel(): string;
+/**
+ * The vector width this model produces, measured rather than looked up.
+ *
+ * A hardcoded table would be wrong the moment someone points AMEM_EMBED_MODEL at
+ * something not in it, and wrong silently — the collection would be created with
+ * the wrong size and every insert would fail. Encoding one short string costs one
+ * forward pass on a model that has to load anyway, and is right for any model.
+ */
+declare function getEmbeddingDim(): Promise<number>;
+/**
+ * Encode text to 384-dim normalized embedding vector.
+ * Singleton model, loaded once and reused.
+ */
+declare function encode(text: string): Promise<number[]>;
+/**
+ * Load the model now rather than on the first encode(). A long-lived service
+ * pays the download at startup, not on a user's first write.
+ */
+declare function loadModel(): Promise<void>;
+/**
+ * Whether the model is resident. Synchronous and I/O-free — unlike encode() it
+ * can never trigger the several-hundred-megabyte download, so a health check is
+ * free to poll it.
+ */
+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
+ */
+/** Per-agent override config. If collection is set, mode B (isolated collection) is used. */
+interface AgentAmemConfig {
+    agentId?: string;
+    collection?: string;
+}
+/** Top-level plugin config shape (superset — existing fields preserved). */
+interface AmemPluginConfig {
+    agentId?: string;
+    collection?: string;
+    topK?: number;
+    /** Per-agent overrides keyed by agentId */
+    agents?: Record<string, AgentAmemConfig>;
+    llmProvider?: string;
+    llmModel?: string;
+    llmBaseURL?: string;
+    llmStrongProvider?: string;
+    llmStrongModel?: string;
+    llmStrongBaseURL?: string;
+    /** Which tier the agent_end CRUD decision runs on: `fast` (default) or `strong`. */
+    llmCrudRole?: 'fast' | 'strong';
+    /** Story 43: run the nightly contradiction sweep. Default true. */
+    conflictSweep?: boolean;
+    /** Similarity floor for accepting an LLM-chosen UPDATE target. Raise it for
+     * cheaper models — a rejected update is stored as a new memory, never lost. */
+    crudUpdateMinSim?: number;
+}
+/** One entry in a note's evolution history (Story 13-B) */
+interface EvolutionEntry {
+    triggeredBy: string;
+    triggeredAt: string;
+    oldContext: string;
+    newContext: string;
+    oldTags: string[];
+    newTags: string[];
+    action?: 'update_neighbor' | 'strengthen' | 'consolidate' | 'crud_update';
+    /** Story 41: the content this entry replaced, so an overwrite stays recoverable. */
+    oldContent?: string;
+    suggestedConnections?: string[];
+    tagsUpdated?: string[];
+}
+interface MemoryNote {
+    id: string;
+    content: string;
+    keywords: string[];
+    tags: string[];
+    context: string;
+    links: string[];
+    embedding: number[];
+    timestamp: string;
+    agent_id: string;
+    hash: string;
+    retrieval_count: number;
+    last_accessed: string;
+    evolution_history: EvolutionEntry[];
+    category: string;
+    is_active: boolean;
+    note_type: 'memory' | 'knowledge';
+    topics: string[];
+    pending_merge: boolean;
+    evolution_type?: 'EVOLVE' | 'CONFLICT' | 'EXPAND' | 'NEW';
+    conflict: boolean;
+    conflicts_with?: string[];
+    conflict_reason?: string;
+    /**
+     * Story 43: when this note was last included in a contradiction scan.
+     * Absent = never scanned. Lets the sweep skip batches it has already judged,
+     * which is what makes a daily run cost one or two calls instead of re-reading
+     * the whole store every night.
+     */
+    conflict_scanned_at?: string;
+    subjects: string[];
+    ephemeral: boolean;
+    low_quality: boolean;
+    owner: string;
+    readers: string[];
+    writers: string[];
+}
+interface QueryResult {
+    note: MemoryNote;
+    score: number;
+}
+/**
+ * Raised when the configured model's vector width does not match the collection
+ * that already exists. Its own class so the plugin can log it loudly instead of
+ * as one more startup warning — this one needs the operator to act.
+ */
+declare class EmbeddingDimensionMismatchError extends Error {
+    readonly collection: string;
+    readonly collectionDim: number;
+    readonly modelDim: number;
+    readonly model: string;
+    constructor(collection: string, collectionDim: number, modelDim: number, model: string);
+}
+/**
+ * Ask Qdrant whether it can serve, right now.
+ *
+ * `ensureCollection()` cannot answer this: it latches `_collectionReady` and
+ * short-circuits on every later call, so once it has succeeded it keeps
+ * reporting success long after Qdrant has gone away. `/readyz` answers in plain
+ * text, so it deliberately bypasses the JSON-parsing `qdrant()` helper above.
+ */
+declare function pingQdrant(): Promise<void>;
+/**
+ * Ensure the given Qdrant collection exists with the correct schema.
+ * If collectionName is omitted, uses process.env.AMEM_COLLECTION (default: amem_notes).
+ * Mode B agents pass their dedicated collection name here.
+ */
+declare function ensureCollection(collectionName?: string): Promise<void>;
+/**
+ * Core CRUD implementation scoped to a specific collection and agent filter mode.
+ * collectionName: which Qdrant collection to operate on.
+ * modeBIsolated: if true, skip the "also include shared" filter in agentFilter
+ *   (mode B collections are already per-agent, so no cross-agent filter needed).
+ */
+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.
+     */
+    getNote(id: string, readerAgentId?: 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.
+     */
+    updateNoteContent(id: string, content: string, embedding: number[], hash: string, callerAgentId?: 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>;
+    getNotesByDatePrefix(datePrefix: string, agentId: string): Promise<MemoryNote[]>;
+    countNotes(agentId?: string): Promise<number>;
+    updateNoteLinks(id: string, links: string[]): Promise<void>;
+    patchNotePayload(id: string, fields: Record<string, unknown>): Promise<void>;
+    replaceLinkReferences(oldId: string, newId: string, agentId: string): Promise<void>;
+};
+type StorageContext = ReturnType<typeof makeCrud>;
+/**
+ * Create a StorageContext scoped to a specific collection (mode B) or the default collection (mode A).
+ * Mode A (same collection): pass collectionName = undefined → uses AMEM_COLLECTION env var.
+ * 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 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 patchNotePayload(id: string, fields: Record<string, unknown>): Promise<void>;
+
+/**
+ * memory.ts — A-MEM core logic: addMemory, searchMemory, listMemories
+ * Full TypeScript port of amem_client.py
+ */
+
+interface QualityCheckResult {
+    ok: boolean;
+    ephemeral: boolean;
+    reason?: string;
+}
+declare function checkQuality(content: string): QualityCheckResult;
+declare function addMemory(content: string, agentId?: string, opts?: {
+    scope?: 'private' | 'shared';
+    storageCtx?: StorageContext;
+    /**
+     * Story 44: who this memory is about. Empty (the default) means it is about
+     * the world or the agent itself, and stays visible whoever is present.
+     */
+    subjects?: string[];
+}): Promise<string>;
+/**
+ * The cheap write path: quality gate → embed the raw content → store.
+ *
+ * Deliberately skips LLM note construction, similarity dedup, link generation
+ * and evolution, so a real-time caller (a game brain logging events tick by
+ * tick) never pays for an LLM round-trip. Cost is one embed + one upsert.
+ *
+ * Episodic notes are an **append-only, faithful event log**: the same content
+ * written twice is two events, so there is no hash or vector dedup here.
+ * Evolution rewrites a note's context over time — precisely what you do not
+ * want for "remember the time the ender dragon killed us". The offline
+ * consolidation pass distils these raw events into long-term, linked notes.
+ */
+declare function addEpisodic(content: string, agentId?: string, opts?: {
+    scope?: 'private' | 'shared';
+    storageCtx?: StorageContext;
+    /** Story 44: who this episode is about. Empty = world/self. */
+    subjects?: string[];
+}): Promise<string>;
+interface SearchResult {
+    id: string;
+    content: string;
+    context: string;
+    tags: string[];
+    keywords: string[];
+    links: string[];
+    timestamp: string;
+    similarity: number;
+    rrf: number;
+    topics: string[];
+    note_type: 'memory' | 'knowledge';
+}
+declare function searchMemory(query: string, topK?: number, agentId?: string, opts?: {
+    useBfs?: boolean;
+    bfsSimThreshold?: number;
+    topicsFilter?: string[];
+    storageCtx?: StorageContext;
+    /**
+     * Story 44: scope retrieval to one person. Returns memories that name them
+     * plus memories that name nobody (world facts, facts about the agent).
+     * Omitted = no person scoping, i.e. today's behaviour.
+     */
+    subject?: string;
+}): Promise<SearchResult[]>;
+declare function listMemories(agentId?: string, storageCtx?: StorageContext): Promise<{
+    count: number;
+}>;
+/**
+ * Merge semantically similar notes written today.
+ * Called asynchronously from agent_end hook; failures are silent.
+ * Returns the number of notes merged (deleted).
+ *
+ * Story 30: pending_merge=true notes are routed through LLM evolution judgment
+ * (EVOLVE/CONFLICT/EXPAND/NEW) instead of simple merge.
+ * Story 32: shared notes (agent_id='shared') are never merged/consolidated.
+ */
+declare function mergeSimilarNotes(agentId: string, storageCtx?: StorageContext): Promise<number>;
+/**
+ * Consolidate semantically similar memories.
+ * Performs deep deduplication by category and similarity score.
+ * Story 32: shared notes (agent_id='shared') are skipped entirely.
+ */
+declare function consolidateMemories(agentId: string, logger?: any, storageCtx?: StorageContext): Promise<number>;
+/**
+ * How a detected contradiction is handled.
+ *
+ * `review` (default) marks both notes and leaves the decision to a human — the
+ * safe option, because even a strong model is only around 55% accurate at
+ * spotting implicit contradictions.
+ *
+ * `auto` additionally retires the older note of each pair. It needs no human,
+ * but at that accuracy roughly two in five retirements will silence a memory
+ * that was still true. The retirement is a soft delete, so it is recoverable —
+ * but for a system answering in real time, "recoverable" only helps once someone
+ * notices. Documented as such; opt in deliberately.
+ */
+type ConflictMode = 'review' | 'auto';
+interface ConflictSweepResult {
+    scanned: number;
+    pairsFound: number;
+    retired: number;
+    batchesScanned: number;
+    batchesSkipped: number;
+}
+/**
+ * Find memories that contradict each other and mark them.
+ *
+ * This is the cold half of the tiering split. The per-turn CRUD decision runs on
+ * a cheap model, which is safe (the update guard stops it writing to the wrong
+ * note) but dull — it misses contradictions it should have caught. This sweep is
+ * what catches them: it runs offline, in batches, on the strong tier, and it
+ * sees far more context than any single turn does.
+ *
+ * Batches by category and hands each batch to the model whole, rather than
+ * pairing by similarity — see llmConflictScan for why that distinction is the
+ * entire point.
+ */
+declare function conflictSweep(agentId: string, opts?: {
+    mode?: ConflictMode;
+    storageCtx?: StorageContext;
+    logger?: {
+        info: (m: string) => void;
+    };
+    /** Re-read every batch, including ones already judged. For a full re-sweep
+     * after changing the prompt or the model. */
+    force?: boolean;
+}): Promise<ConflictSweepResult>;
+
+/**
+ * quality.ts — Memory quality scanning and review batch generation (Story 31)
+ */
+
+interface LowQualityItem {
+    note: MemoryNote;
+    reasons: LowQualityReason[];
+}
+type LowQualityReason = 'too_short' | 'expired_ephemeral' | 'pending_conflict';
+declare function scanLowQuality(agentId: string): Promise<LowQualityItem[]>;
+declare function generateReviewBatch(agentId: string, outputPath?: string): Promise<string>;
+
+/**
+ * auth.ts — write authorization for the Access Protocol (Story 33).
+ *
+ * Story 32 gave every note `owner` / `readers` / `writers` and enforced `readers`
+ * at query time. It deliberately left `writers` unenforced. The consequence: the
+ * agent filter matches `agent_id == caller OR agent_id == 'shared'`, so ANY query
+ * can return another agent's shared note — and every mutation then wrote to it
+ * unchecked. An audit found eight such write sites (dedup, link generation,
+ * evolution ×2, CRUD update/delete, quality scan, link rewriting).
+ *
+ * This is the one rule they all gate on. Kept pure and dependency-free so the
+ * policy is unit-testable on its own and identical everywhere it is applied.
+ */
+
+/**
+ * May `callerAgentId` mutate `note`?
+ *
+ * True when the caller owns it, is listed in `writers`, or `writers` is open
+ * (`'*'`). Everything else — notably another agent's shared note, which is
+ * readable but not writable — is denied.
+ */
+declare function canWrite(note: Pick<MemoryNote, 'owner' | 'writers'>, callerAgentId: string): boolean;
+/**
+ * May `callerAgentId` read `note`? (Story 36 — the read half of the protocol.)
+ *
+ * True when the caller owns it, is listed in `readers`, or the note is public
+ * (`readers` contains `'*'`, which is how a shared-scope write is stored).
+ *
+ * Queries already filter by `agent_id`, so list/search paths never surface an
+ * unreadable note. This guards the one primitive that bypasses that filter —
+ * `getNote(id)` fetches straight by UUID — and the link-neighbourhood walks that
+ * use it: a shared note's `links[]` can name its owner's PRIVATE notes, so
+ * following those links would otherwise read memory the caller may not see.
+ */
+declare function canRead(note: Pick<MemoryNote, 'owner' | 'readers'>, callerAgentId: string): boolean;
+
+interface MigrateResult {
+    /** Points found in the source. */
+    total: number;
+    /** Notes whose derived fields were empty — the pre-pipeline cohort. */
+    missingDerived: number;
+    /** Notes whose fields were re-extracted. 0 unless refreshFields. */
+    refreshed: number;
+    /** Notes written into the target. 0 on a dry run. */
+    migrated: number;
+    sourceDim: number | null;
+    targetDim: number;
+    model: string;
+    dryRun: boolean;
+}
+declare function migrateCollection(opts: {
+    /** Source collection. Read-only; never modified. */
+    from: string;
+    /** Target collection. Created if absent; must not already hold points. */
+    to: string;
+    /** Re-extract keywords/tags/context for notes that never had them. Default true. */
+    refreshFields?: boolean;
+    /** Report what would happen and write nothing. Default TRUE — opt in to writing. */
+    dryRun?: boolean;
+    logger?: {
+        info: (m: string) => void;
+        warn: (m: string) => void;
+    };
+}): Promise<MigrateResult>;
+
+/**
+ * Similarity floor for accepting an UPDATE target.
+ *
+ * Heuristic, not empirically tuned: it sits just above the 0.3 bar the engine
+ * already uses for "these two notes are related at all", because a legitimate
+ * CRUD UPDATE is often a correction or contradiction ("drinks tea" → "switched to
+ * coffee") that is related but not near-identical. Set it too high and real
+ * corrections get downgraded; too low and the guard does nothing.
+ *
+ * Failing this check is SAFE by construction — the caller inserts the fact as a
+ * new memory instead of overwriting, and scheduled consolidation can merge later.
+ * So the cost of a false positive is a duplicate, and the cost of a false
+ * negative is a destroyed memory. Bias accordingly: raise it for cheaper models.
+ */
+declare const DEFAULT_CRUD_UPDATE_MIN_SIM = 0.35;
+/** Resolve the threshold: env var wins, then an explicit override, then default. */
+declare function resolveCrudUpdateMinSim(override?: number): number;
+/**
+ * May `newEmbedding`'s fact overwrite the memory `targetEmbedding` belongs to?
+ *
+ * True when the replacement is plausibly about the same thing. False means the
+ * LLM most likely named the wrong index — the caller should insert instead of
+ * overwrite, never throw.
+ *
+ * Both vectors are L2-normalized by `encode`, so this is a dot product.
+ */
+declare function isPlausibleUpdateTarget(newEmbedding: number[], targetEmbedding: number[], minSimilarity?: number): boolean;
+
+/**
+ * llm.ts — LLM helpers for A-MEM note construction, linking, evolution
+ */
+/**
+ * Which tier a call runs on (Story 42).
+ *
+ * The engine's calls split cleanly by how much model capability they actually
+ * need. Published results are consistent that memory quality is mostly
+ * architecture-bound — extraction differs ~2 points between a cheap and a strong
+ * model — with ONE exception: judging whether a new fact CONTRADICTS a stored
+ * one, where the gap is large. So the frequent, easy calls run `fast`, and the
+ * rare, genuinely hard judgements can run `strong` if the operator configures
+ * one. See docs/guide/design-rationale.md for the evidence.
+ */
+type LlmRole = 'fast' | 'strong';
+/** Provider/model/endpoint for one role. */
+interface LlmRoleConfig {
+    provider?: string;
+    model?: string;
+    baseURL?: string;
+}
+/** Runtime LLM settings a host may inject. See the precedence note above. */
+interface LlmConfig extends LlmRoleConfig {
+    /** Per-request timeout in ms for the SDK client. Guards against a slow or
+     * stuck endpoint hanging the whole addMemory pipeline. Default 30000.
+     * Shared by both roles — it is a transport concern, not a tier one. */
+    timeoutMs?: number;
+    /**
+     * Optional `strong` tier. Each field falls back to the `fast` value
+     * INDIVIDUALLY, so all three useful shapes work:
+     *   - only `model`      → same endpoint, better model (gpt-4o-mini → gpt-4o)
+     *   - all three         → a wholly separate backend (local Ollama + cloud Claude)
+     *   - nothing           → strong IS fast, i.e. today's single-model behaviour
+     * There is deliberately no built-in strong default: inventing one would start
+     * spending an existing user's money on a pricier model without them asking.
+     */
+    strong?: LlmRoleConfig;
+    /** Which role the agent_end CRUD decision uses. Default `fast`. */
+    crudRole?: LlmRole;
+}
+/**
+ * Point the engine's LLM calls at a provider/model/endpoint chosen by the host.
+ *
+ * Environment variables still win over anything passed here, and any field left
+ * undefined falls through to the default — so `configureLlm({ model })` changes
+ * only the model. Safe to call before or after the first LLM call.
+ */
+declare function configureLlm(cfg: LlmConfig): void;
+interface MemoryOperation {
+    action: 'NEW' | 'UPDATE' | 'DELETE' | 'NONE';
+    fact: string;
+    existingIdx?: number;
+    reason?: string;
+}
+declare function llmCrudDecision(userText: string, assistantText: string, existingMemories: Array<{
+    idx: number;
+    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 };