@mnemonic-ai/core 0.1.0

package/dist/client-b2Xhkqdl.d.ts

@@ -0,0 +1,409 @@
+/**
+ * Core memory data structures.
+ */
+/** Built-in tier constants. Custom tiers can be registered via MnemonicConfig. */
+declare const MemoryTier: {
+    readonly IDENTITY: "identity";
+    readonly PROCEDURAL: "procedural";
+    readonly STRUCTURAL: "structural";
+    readonly EPISODIC: "episodic";
+    readonly TRANSIENT: "transient";
+};
+type MemoryTier = (typeof MemoryTier)[keyof typeof MemoryTier];
+/** Options for constructing a Memory. Only `content` is required. */
+interface MemoryInit {
+    content: string;
+    id?: string;
+    tier?: string;
+    source?: string;
+    actor?: string;
+    sessionId?: string | null;
+    createdAt?: Date;
+    lastAccessedAt?: Date;
+    accessCount?: number;
+    importance?: number;
+    supersededBy?: string | null;
+    contradictedBy?: string | null;
+    embedding?: number[] | null;
+    metadata?: Record<string, unknown>;
+    linkedIds?: string[];
+    agentId?: string;
+    shared?: boolean;
+    charsPerToken?: number;
+}
+/** A single unit of agent memory. */
+declare class Memory {
+    readonly content: string;
+    readonly id: string;
+    tier: string;
+    source: string;
+    actor: string;
+    sessionId: string | null;
+    createdAt: Date;
+    lastAccessedAt: Date;
+    accessCount: number;
+    importance: number;
+    supersededBy: string | null;
+    contradictedBy: string | null;
+    embedding: number[] | null;
+    metadata: Record<string, unknown>;
+    linkedIds: string[];
+    agentId: string;
+    shared: boolean;
+    private _charsPerToken;
+    constructor(init: MemoryInit);
+    /** The tier as a plain string, regardless of whether it was set as an enum. */
+    get tierName(): string;
+    /** Rough token count using configurable chars-per-token ratio. */
+    get tokenEstimate(): number;
+    /** Record an access. */
+    touch(): void;
+}
+/** A directed relationship between two memories.
+ * Known relations: "related_to", "contradicts", "elaborates", "supersedes", "consolidates".
+ */
+interface MemoryEdge {
+    sourceId: string;
+    targetId: string;
+    relation: string;
+    weight: number;
+    createdAt: Date;
+}
+/**
+ * A pair of memory IDs with their cosine similarity score.
+ * Used by findSimilarPairs() to return sparse above-threshold pairs
+ * without transferring full embedding vectors from the database.
+ */
+interface SimilarPair {
+    idA: string;
+    idB: string;
+    similarity: number;
+}
+/** Create a MemoryEdge with defaults. */
+declare function createEdge(sourceId: string, targetId: string, relation: string, weight?: number): MemoryEdge;
+
+/**
+ * Centralised configuration for all Mnemonic tunables.
+ */
+
+interface ScorerConfig {
+    weightRecency: number;
+    weightFrequency: number;
+    weightLinks: number;
+    weightBase: number;
+    frequencyLogCap: number;
+    linkSaturation: number;
+    supersessionPenalty: number;
+    contradictionPenalty: number;
+    consolidationPenalty: number;
+    tierBaseScores: Record<string, number>;
+}
+interface ClassifierConfig {
+    extraPatterns: Record<string, string[]>;
+    episodicMinWords: number;
+    customClassifier: ((content: string, source: string, actor: string) => string) | null;
+}
+interface LinkerConfig {
+    similarityThreshold: number;
+    maxLinks: number;
+    keywordPenalty: number;
+    contradictionThreshold: number;
+    elaborationThreshold: number;
+    supersessionThreshold: number;
+    negationWords: Set<string>;
+    customRelationFn: ((a: Memory, b: Memory, similarity: number) => string) | null;
+}
+type SortOrder = "chronological" | "importance" | "relevance" | ((a: Memory, b: Memory) => number);
+interface AssemblerConfig {
+    defaultMaxTokens: number;
+    diversityStrength: number;
+    sortOrder: SortOrder;
+    minRelevance: number;
+}
+interface ConsolidationConfig {
+    minClusterSize: number;
+    similarityThreshold: number;
+    maxContentLength: number;
+    prefix: string;
+    sourceName: string;
+    actorName: string;
+    /**
+     * Custom summary function replacing the default semicolon-join.
+     * Receives original memory content strings, returns a summary string.
+     * May be sync or async. When null/undefined, the default join is used.
+     */
+    summarizer?: ((contents: string[]) => Promise<string> | string) | null;
+    /** Max candidates for brute-force pairwise similarity (SQLite/default). */
+    maxCandidates: number;
+    /** Max nearest neighbors per candidate in LATERAL/vector index (Postgres/Neo4j). */
+    maxNeighborsPerCandidate: number;
+}
+interface PromotionConfig {
+    transientToEpisodicAccesses: number;
+    episodicToStructuralAccesses: number;
+    structuralToIdentityAccesses: number;
+    proceduralToIdentityAccesses: number;
+    demotionImportanceThreshold: number;
+}
+declare class SalienceSignal {
+    readonly name: string;
+    readonly patterns: string[];
+    readonly boost: number;
+    private _compiled;
+    constructor(name: string, patterns: string[], boost: number);
+    scan(text: string): boolean;
+}
+declare const BUILTIN_SALIENCE_SIGNALS: SalienceSignal[];
+interface SalienceConfig {
+    enabled: boolean;
+    maxBoost: number;
+    signals: SalienceSignal[];
+}
+interface TierDefinition {
+    name: string;
+    defaultHalfLifeDays: number;
+    description: string;
+}
+declare const BUILTIN_TIERS: TierDefinition[];
+declare class MnemonicConfig {
+    scorer: ScorerConfig;
+    classifier: ClassifierConfig;
+    linker: LinkerConfig;
+    assembler: AssemblerConfig;
+    consolidation: ConsolidationConfig;
+    promotion: PromotionConfig;
+    salience: SalienceConfig;
+    charsPerToken: number;
+    defaultTier: string;
+    embeddingSearchLimit: number;
+    private _tiers;
+    constructor(overrides?: Partial<{
+        scorer: Partial<ScorerConfig>;
+        classifier: Partial<ClassifierConfig>;
+        linker: Partial<LinkerConfig>;
+        assembler: Partial<AssemblerConfig>;
+        consolidation: Partial<ConsolidationConfig>;
+        promotion: Partial<PromotionConfig>;
+        salience: Partial<SalienceConfig>;
+        charsPerToken: number;
+        defaultTier: string;
+        embeddingSearchLimit: number;
+    }>);
+    registerTier(tier: TierDefinition): void;
+    getTier(name: string): TierDefinition;
+    tierNames(): string[];
+    halfLifeDays(tierName: string): number;
+}
+
+/**
+ * Abstract interface for embedding providers.
+ */
+/** Interface for producing vector embeddings from text. */
+interface BaseEmbedder {
+    /** Return a dense vector for text. */
+    embed(text: string): Promise<number[]>;
+    /** Return dense vectors for a batch of texts. */
+    embedBatch(texts: string[]): Promise<number[][]>;
+    /** Dimensionality of the embeddings produced. */
+    readonly dimension: number;
+}
+
+/**
+ * Abstract base interface for memory stores.
+ */
+
+/** Options for agent-scoped store operations. */
+interface AgentFilterOptions {
+    agentId?: string;
+    includeShared?: boolean;
+    tier?: string;
+    /** Cap the result set at the database level. */
+    limit?: number;
+}
+/** Synchronous interface for storage backends (e.g. SQLite). */
+interface BaseStore {
+    /** Create tables / indexes if they don't exist. */
+    initialize(): void;
+    /** Release resources (close connections, etc.). */
+    close(): void;
+    /** Persist a single memory (insert or update). */
+    save(memory: Memory): void;
+    /** Retrieve a memory by ID. */
+    get(memoryId: string): Memory | null;
+    /** Return memories. When agentId is provided, returns own + shared. */
+    listAll(options?: AgentFilterOptions): Memory[];
+    /** Remove a memory by ID and its edges. */
+    delete(memoryId: string): void;
+    /** Delete memories older than ageMs milliseconds. Returns count deleted. */
+    deleteOlderThan(ageMs: number, tier?: string, options?: AgentFilterOptions): number;
+    /** Persist a relationship edge. */
+    saveEdge(edge: MemoryEdge): void;
+    /** Return all edges where memoryId is source or target. */
+    getEdges(memoryId: string): MemoryEdge[];
+    /** Return memories closest to embedding (approximate nearest-neighbour). */
+    searchByEmbedding(embedding: number[], limit?: number, options?: AgentFilterOptions): Memory[];
+    /**
+     * Return memory pairs whose cosine similarity >= threshold.
+     *
+     * This is a bounded, approximate search. `maxCandidates` caps the number of
+     * embeddings considered, and `maxNeighborsPerCandidate` limits per-row
+     * neighbors in DB-pushed implementations. Results may not include all
+     * qualifying pairs in the store.
+     */
+    findSimilarPairs(options?: {
+        threshold?: number;
+        agentId?: string;
+        tier?: string;
+        maxCandidates?: number;
+        maxNeighborsPerCandidate?: number;
+    }): SimilarPair[];
+    /** Read a key-value metadata entry. */
+    getMeta(key: string): string | null;
+    /** Write a key-value metadata entry (upsert). */
+    setMeta(key: string, value: string): void;
+}
+
+/**
+ * Async mirror of BaseStore for networked backends (Postgres, Neo4j).
+ */
+
+/** Asynchronous interface for networked storage backends. */
+interface AsyncBaseStore {
+    initialize(): Promise<void>;
+    close(): Promise<void>;
+    save(memory: Memory): Promise<void>;
+    get(memoryId: string): Promise<Memory | null>;
+    listAll(options?: AgentFilterOptions): Promise<Memory[]>;
+    delete(memoryId: string): Promise<void>;
+    deleteOlderThan(ageMs: number, tier?: string, options?: AgentFilterOptions): Promise<number>;
+    saveEdge(edge: MemoryEdge): Promise<void>;
+    getEdges(memoryId: string): Promise<MemoryEdge[]>;
+    searchByEmbedding(embedding: number[], limit?: number, options?: AgentFilterOptions): Promise<Memory[]>;
+    findSimilarPairs(options?: {
+        threshold?: number;
+        agentId?: string;
+        tier?: string;
+        maxCandidates?: number;
+        maxNeighborsPerCandidate?: number;
+    }): Promise<SimilarPair[]>;
+    getMeta(key: string): Promise<string | null>;
+    setMeta(key: string, value: string): Promise<void>;
+}
+
+/**
+ * Top-level Mnemonic client — the public API surface.
+ */
+
+type StoreFactory = (uri: string, embeddingDim?: number) => BaseStore | AsyncBaseStore | Promise<AsyncBaseStore>;
+/**
+ * Register a store factory for a URI scheme.
+ *
+ * The factory receives the full URI and the embedding dimension (if known).
+ * Must return a BaseStore or AsyncBaseStore.
+ * Throws if `scheme` is already registered (pass `overwrite: true` to replace).
+ *
+ * @example
+ * ```ts
+ * registerStore("neo4j", (uri, dim) => new Neo4jStore({ uri, embeddingDim: dim }));
+ * new Mnemonic({ store: "neo4j://localhost" }); // now works
+ * ```
+ */
+declare function registerStore(scheme: string, factory: StoreFactory, options?: {
+    overwrite?: boolean;
+}): void;
+interface AddOptions {
+    source?: string;
+    actor?: string;
+    tier?: string;
+    sessionId?: string;
+    metadata?: Record<string, unknown>;
+    shared?: boolean;
+}
+interface RecallOptions {
+    maxTokens?: number;
+    minRelevance?: number;
+    header?: string;
+}
+interface ForgetOptions {
+    olderThan?: string;
+    tier?: string;
+    belowImportance?: number;
+}
+interface StatsResult {
+    totalMemories: number;
+    totalTokens: number;
+    byTier: Record<string, number>;
+    agentId: string;
+}
+declare class Mnemonic {
+    private _config;
+    private _store;
+    private _embedder;
+    private _autoClassify;
+    private _agentId;
+    private _resolvedAgentId;
+    private _initPromise;
+    constructor(options?: {
+        store?: string | BaseStore | AsyncBaseStore;
+        embedder?: BaseEmbedder | null;
+        autoClassify?: boolean;
+        config?: MnemonicConfig;
+        agentId?: string;
+    });
+    get config(): MnemonicConfig;
+    /** The underlying async store. */
+    get store(): AsyncBaseStore;
+    /** The embedder (if configured). */
+    get embedder(): BaseEmbedder | null;
+    /** The resolved agent ID (available after init()). */
+    get agentId(): string;
+    /**
+     * Initialize the store and resolve agent identity. Must be called before use.
+     * Pass `{ skipStoreInit: true }` when reusing an already-initialized store
+     * (e.g. creating per-agent clients that share a single backend).
+     */
+    init(options?: {
+        skipStoreInit?: boolean;
+    }): Promise<void>;
+    private _resolveAgentId;
+    private _ensureInitialized;
+    /** Return only memories owned by this agent (excludes shared from others). */
+    private _ownMemories;
+    private static _contentHash;
+    /**
+     * Store a memory with automatic classification and linking.
+     * If identical content already exists for this agent, returns the existing memory.
+     */
+    add(content: string, options?: AddOptions): Promise<Memory>;
+    private _assemble;
+    /** Retrieve optimised context for a given query within a token budget. */
+    recall(query: string, options?: RecallOptions): Promise<string>;
+    /** Like recall but returns the raw Memory objects. */
+    recallMemories(query: string, options?: {
+        maxTokens?: number;
+        minRelevance?: number;
+    }): Promise<Memory[]>;
+    /** Delete memories matching the given criteria. Returns count deleted. */
+    forget(options?: ForgetOptions): Promise<number>;
+    /**
+     * Merge similar episodic memories into higher-tier summaries.
+     *
+     * Originals are kept alive but deprioritised via a scoring penalty
+     * and `consolidated_into` metadata. A `consolidates` edge links
+     * the summary to each original for graph traversal.
+     */
+    consolidate(): Promise<number>;
+    /** Run the tier promotion/demotion pipeline on own memories. */
+    promote(): Promise<number>;
+    /** Re-run the linker across all memories to retroactively set edges. */
+    relink(): Promise<number>;
+    /** Return aggregate statistics about own memories. */
+    stats(): Promise<StatsResult>;
+    /** Make a memory visible to all agents. */
+    share(memoryId: string): Promise<Memory>;
+    /** Make a memory private (only visible to owner). */
+    unshare(memoryId: string): Promise<Memory>;
+    private _applyTierResults;
+}
+
+export { type AsyncBaseStore as A, type BaseStore as B, type ClassifierConfig as C, type ForgetOptions as F, type LinkerConfig as L, Mnemonic as M, type PromotionConfig as P, type RecallOptions as R, type SimilarPair as S, type TierDefinition as T, Memory as a, type AgentFilterOptions as b, type MemoryEdge as c, type BaseEmbedder as d, MnemonicConfig as e, type SalienceConfig as f, type AddOptions as g, type AssemblerConfig as h, BUILTIN_SALIENCE_SIGNALS as i, BUILTIN_TIERS as j, type ConsolidationConfig as k, type MemoryInit as l, MemoryTier as m, SalienceSignal as n, type ScorerConfig as o, type SortOrder as p, type StatsResult as q, type StoreFactory as r, createEdge as s, registerStore as t };