@linxiraos/pi-mnemopi 1.0.0

package/dist/types/core/cost-log.d.ts

@@ -0,0 +1,13 @@
+import type { Database } from "bun:sqlite";
+export declare const DEFAULT_LOG_DIR: string;
+export declare const DEFAULT_LOG_DB: string;
+export interface CostStats {
+    total_calls: number;
+    total_memories_injected: number;
+    total_tokens: number;
+    total_estimated_cost_usd: number;
+}
+export declare function getConn(dbPath?: string): Database;
+export declare function initCostLog(dbPath?: string): void;
+export declare function logCost(sessionId: string, memoryCount: number, tokenCount: number, estimatedCostUsd: number, model?: string, dbPath?: string): void;
+export declare function getCostStats(sessionId?: string, dbPath?: string): CostStats;

package/dist/types/core/embeddings.d.ts

@@ -0,0 +1,93 @@
+import type { EmbeddingModel } from "fastembed";
+import { type EmbeddingOutput } from "./runtime-options.js";
+export type { EmbeddingOutput } from "./runtime-options.js";
+export { cosineSimilarity } from "./vector-math.js";
+export type Vector = Float32Array;
+export type EmbeddingMatrix = Vector[];
+export interface EmbeddingProvider {
+    embed(texts: readonly string[]): EmbeddingOutput | Promise<EmbeddingOutput>;
+    available?(): boolean | Promise<boolean>;
+}
+export type StandardEmbeddingModel = Exclude<EmbeddingModel, EmbeddingModel.CUSTOM>;
+export interface LocalEmbeddingModel {
+    embed(texts: string[], batchSize?: number): EmbeddingOutput;
+    queryEmbed?(query: string): Promise<number[]>;
+}
+export type LocalModelInitOptions = {
+    model: StandardEmbeddingModel;
+    cacheDir?: string;
+    showDownloadProgress?: boolean;
+};
+export type LocalModelInitializer = (options: LocalModelInitOptions) => Promise<LocalEmbeddingModel>;
+/**
+ * Quarantine the exact ONNX file named by a "Protobuf parsing failed" init
+ * error. A truncated cached model blocks local embeddings forever: the
+ * downloader treats the existing file as complete, so every init re-parses
+ * the same broken bytes. The extracted path is error-message CONTENT, so it
+ * is only honored when it resolves inside the fastembed cache directory —
+ * never rename an arbitrary file a dependency happens to mention. Atomic
+ * rename; losing a concurrent-heal race (file already renamed/removed)
+ * still returns true because a retry is safe either way.
+ * @internal exported for tests
+ */
+export declare function quarantineCorruptModelFile(message: string, cacheDir?: string): Promise<boolean>;
+/**
+ * Recover from a partially-extracted fastembed model cache. An interrupted
+ * archive download/extraction leaves `<cacheDir>/<model>/` populated with
+ * sidecars and a truncated `model.onnx_data` but WITHOUT the graph file
+ * (`model.onnx` / `model_optimized.onnx`), so `FlagEmbedding.init` throws
+ * `Model file not found at .../model.onnx`. Upstream `retrieveModel`
+ * short-circuits on the existing model dir and never re-downloads, and
+ * `downloadFileFromGCS` reuses a leftover partial `<model>.tar.gz` as-is, so
+ * the cache is stuck broken forever: recall silently dies and the rebuild
+ * queue grows every session. Delete the incomplete model dir AND the leftover
+ * partial archive so the retry re-downloads from scratch. The model path is
+ * error-message CONTENT, so the dir is only removed when it is a direct child
+ * of the fastembed cache root — never touch a directory a dependency merely
+ * names. Returns true when a retry is worth attempting (the incomplete cache
+ * was cleared, or already gone from a concurrent heal).
+ * @internal exported for tests
+ */
+export declare function clearIncompleteModelCache(message: string, cacheDir?: string): Promise<boolean>;
+/**
+ * Shared local-model initializer: FlagEmbedding.init with BOTH cache heals.
+ * Missing sidecars (config/tokenizer/tokens map) re-fetch and retry; a
+ * corrupt model blob (Protobuf parse failure) quarantines the file and
+ * retries THROUGH the sidecar heal, so a cache that is broken in both ways
+ * still recovers in one pass. Also the initializer the embed worker uses in
+ * its subprocess; the in-process seam stays {@link setLocalModelInitializer}.
+ */
+export declare function defaultLocalModelInitializer(options: LocalModelInitOptions): Promise<LocalEmbeddingModel>;
+export declare function embeddingsDisabled(): boolean;
+/**
+ * Resolve the embedding model name for the currently active runtime scope.
+ *
+ * Reads (in order): the active provider's `model` from `withMnemopiRuntimeOptions`,
+ * the `MNEMOPI_EMBEDDING_MODEL` env var, then the bundled fastembed default. Stored
+ * alongside each row in `memory_embeddings.model` so migrations can re-embed when
+ * the active model changes.
+ */
+export declare function currentEmbeddingModel(): string;
+export declare function isApiModel(modelName: string): boolean;
+export declare function embeddingDimFor(modelName: string): number;
+export declare function setEmbeddingProviderForTests(provider: EmbeddingProvider | null | undefined): void;
+export declare const setEmbeddingProvider: typeof setEmbeddingProviderForTests;
+export declare function setLocalModelInitializerForTests(initializer: LocalModelInitializer | null | undefined): void;
+/**
+ * Override the function used to construct the local fastembed model the next
+ * time `embed()` is called. Lets a host (e.g. the agent CLI) keep
+ * `onnxruntime-node` out of its own address space by routing every fastembed
+ * load + inference through a dedicated subprocess. Same wipe semantics as the
+ * `*ForTests` form: clears the cached model promise and the query cache so
+ * subsequent embeds run through the new initializer immediately.
+ */
+export declare const setLocalModelInitializer: typeof setLocalModelInitializerForTests;
+export declare function resetEmbeddingProviderForTests(): void;
+export declare const resetEmbeddingStateForTests: typeof resetEmbeddingProviderForTests;
+export declare function available(): Promise<boolean>;
+export declare function availableApi(): boolean;
+export declare function embedQuery(text: string): Promise<Vector | null>;
+export declare function embed(texts: readonly string[]): Promise<EmbeddingMatrix | null>;
+export declare function getEmbeddingApiCallCountForTests(): number;
+export declare const DEFAULT_MODEL: string;
+export declare const EMBEDDING_DIM: number;

package/dist/types/core/entities.d.ts

@@ -0,0 +1,9 @@
+export declare const ENTITY_EXTRACTION_STOP_WORDS: ReadonlySet<string>;
+/** Maximum raw text size for regex-only entity extraction. */
+export declare const REGEX_EXTRACTION_MAX_INPUT_CHARS = 50000;
+export declare function levenshteinDistance(s1: string, s2: string): number;
+export declare function similarity(s1: string, s2: string): number;
+export declare function extractEntitiesRegex(text: string): string[];
+export type SimilarEntity = readonly [entity: string, score: number];
+export declare function findSimilarEntities(entity: string, knownEntities: readonly string[], threshold?: number): SimilarEntity[];
+export declare function entityExtractionPerformance(text: string, iterations?: number): number;

package/dist/types/core/episodic-graph.d.ts

@@ -0,0 +1,89 @@
+import type { Database } from "bun:sqlite";
+import { type DatabasePath } from "../db.js";
+export interface Gist {
+    readonly id: string;
+    readonly text: string;
+    readonly timestamp: string;
+    readonly participants: readonly string[];
+    readonly location: string | null;
+    readonly emotion: string | null;
+    readonly timeScope: string | null;
+}
+export interface Fact {
+    readonly id: string;
+    readonly subject: string;
+    readonly predicate: string;
+    readonly object: string;
+    readonly timestamp: string;
+    readonly confidence: number;
+    readonly temporalQualifier?: string | null;
+}
+export interface GraphEdge {
+    readonly source: string;
+    readonly target: string;
+    readonly edgeType: string;
+    readonly weight: number;
+    readonly timestamp: string;
+}
+export interface RelatedMemory {
+    readonly memoryId: string;
+    readonly edgeType: string;
+    readonly weight: number;
+    readonly depth: number;
+}
+export interface GraphStats {
+    readonly gists: number;
+    readonly facts: number;
+    readonly edges: number;
+    readonly totalNodes: number;
+}
+export interface IngestOptions {
+    readonly sessionId?: string;
+    readonly linkExisting?: boolean;
+    readonly minLinkScore?: number;
+    readonly extractEntities?: boolean;
+}
+export interface IngestResult {
+    readonly memoryId: string;
+    readonly gist: Gist;
+    readonly facts: readonly Fact[];
+    readonly edges: readonly GraphEdge[];
+}
+export interface EpisodicGraphOptions {
+    readonly db?: Database;
+    readonly dbPath?: DatabasePath;
+}
+export declare class EpisodicGraph {
+    readonly db: Database;
+    readonly dbPath: DatabasePath;
+    readonly ownsConnection: boolean;
+    constructor(options?: EpisodicGraphOptions);
+    private initTables;
+    extractGist(content: string, memoryId: string): Gist;
+    extractFacts(content: string, memoryId: string): Fact[];
+    storeGist(gist: Gist, memoryId: string): void;
+    getGist(id: string): Gist | null;
+    storeFact(fact: Fact, memoryId: string, sessionId?: string): void;
+    getFact(id: string): Fact | null;
+    addEdge(edge: GraphEdge): void;
+    getEdges(source?: string | null): GraphEdge[];
+    findRelatedMemories(memoryId: string, depth?: number, edgeType?: string, minWeight?: number): RelatedMemory[];
+    findFactsBySubject(subject: string): Fact[];
+    findGistsByParticipant(participant: string): Gist[];
+    scoreMemoryLink(sourceMemoryId: string, targetMemoryId: string): number;
+    ingestMemory(content: string, memoryId: string, options?: IngestOptions): IngestResult;
+    getStats(): GraphStats;
+    close(): void;
+    private count;
+    private extractParticipants;
+    private extractTemporalScope;
+    private extractLocation;
+    private extractEmotion;
+    private createSummary;
+    private knownMemoryIds;
+    private memoryContent;
+    private entityOverlapScore;
+    private temporalContextScore;
+    private memoryFeatures;
+    private scoreFeatures;
+}

package/dist/types/core/extraction/client.d.ts

@@ -0,0 +1,35 @@
+import { type ApiKey, type FetchImpl } from "@linxiraos/pi-ai";
+export declare const DEFAULT_EXTRACTION_MODEL: string;
+export declare const OPENROUTER_BASE_URL: string;
+export declare const FALLBACK_MODELS: readonly ["google/gemini-flash-latest"];
+export interface ChatMessage {
+    role: string;
+    content: string;
+}
+export interface ExtractedFact {
+    subject?: string;
+    predicate?: string;
+    object?: string;
+    timestamp?: string;
+    source?: number;
+    confidence?: number;
+    [key: string]: unknown;
+}
+export interface ExtractionClientOptions {
+    model?: string | null;
+    apiKey?: ApiKey | null;
+    baseUrl?: string | null;
+    fetch?: FetchImpl;
+}
+export declare class ExtractionClient {
+    model: string;
+    apiKey: ApiKey;
+    baseUrl: string;
+    callCount: number;
+    private readonly fetchImpl;
+    constructor(opts?: ExtractionClientOptions);
+    chat(messages: readonly ChatMessage[], temperature?: number, maxTokens?: number): Promise<string>;
+    callApi(model: string, messages: readonly ChatMessage[], temperature: number, maxTokens: number, apiKey?: string): Promise<string>;
+    extractFacts(messages: readonly ChatMessage[]): Promise<ExtractedFact[]>;
+    xtractFacts(messages: readonly ChatMessage[]): Promise<ExtractedFact[]>;
+}

package/dist/types/core/extraction/diagnostics.d.ts

@@ -0,0 +1,51 @@
+export declare const EXTRACTION_TIERS: readonly ["host", "remote", "local", "cloud", "wrapper"];
+export type ExtractionTier = (typeof EXTRACTION_TIERS)[number];
+export interface ErrorSample {
+    at: string;
+    type: string;
+    msg: string;
+    reason?: string;
+}
+export interface TierStatsSnapshot {
+    attempts: number;
+    successes: number;
+    no_output: number;
+    failures: number;
+    error_samples: ErrorSample[];
+}
+export interface ExtractionStatsSnapshot {
+    created_at: string;
+    snapshot_at: string;
+    totals: {
+        calls: number;
+        successes: number;
+        failures: number;
+        empty: number;
+        success_rate: number;
+    };
+    by_tier: Record<ExtractionTier, TierStatsSnapshot>;
+}
+export declare function safeForLog(value: unknown): string;
+export declare class ExtractionDiagnostics {
+    private tierStats;
+    private totalCalls;
+    private totalSuccesses;
+    private totalFailures;
+    private totalEmpty;
+    private createdAt;
+    private validateTier;
+    recordAttempt(tier: ExtractionTier): void;
+    recordSuccess(tier: ExtractionTier, _factCount?: number): void;
+    recordNoOutput(tier: ExtractionTier): void;
+    recordFailure(tier: ExtractionTier, exc?: unknown, reason?: string): void;
+    recordCall(opts: {
+        succeeded: boolean;
+        allEmpty?: boolean;
+    }): void;
+    successRate(): number;
+    snapshot(): ExtractionStatsSnapshot;
+    reset(): void;
+}
+export declare function getDiagnostics(): ExtractionDiagnostics;
+export declare function getExtractionStats(): ExtractionStatsSnapshot;
+export declare function resetExtractionStats(): void;

package/dist/types/core/extraction/prompts.d.ts

@@ -0,0 +1,2 @@
+export declare const EXTRACTION_SYSTEM_PROMPT = "You extract structured facts from conversation messages. For each message or group of related messages, identify:\n\n1. ENTITIES: People, projects, tools, versions, dates, numbers mentioned\n2. RELATIONSHIPS: How entities relate to each other (uses, created, set, changed, prefers)\n3. TEMPORAL ANCHORS: When something happened, deadlines, durations\n4. CONTRADICTIONS: When a fact was later changed or updated\n\nReturn ONLY a JSON array of fact objects. Each fact must have:\n- subject: the entity the fact is about (string)\n- predicate: the relationship or action (string)\n- object: the value or related entity (string)\n- timestamp: ISO timestamp when this was stated (string, from message context)\n- source: which message index this came from (integer, 0-based)\n- confidence: 0.0-1.0 how certain you are (float)\n\nRULES:\n- One fact per relationship. \"I use React 18.2 and Node.js 18\" = 2 facts.\n- Use lowercase for predicates: \"uses\", \"set\", \"changed\", \"created\", \"prefers\"\n- Include versions and numbers as objects when available\n- If a message states something changed, extract BOTH old and new facts\n- If unclear, use confidence < 0.8\n\nFormat: [{\"subject\": \"...\", \"predicate\": \"...\", \"object\": \"...\", \"timestamp\": \"...\", \"source\": 0, \"confidence\": 0.95}]\n";
+export declare const EXTRACTION_USER_TEMPLATE = "Extract all structured facts from the following conversation messages. Return ONLY the JSON array, no other text.\n\nCONVERSATION:\n{conversation_text}\n\nFACTS:";

package/dist/types/core/extraction.d.ts

@@ -0,0 +1,34 @@
+import { type RemoteLlmOptions } from "./local-llm.js";
+export declare const EXTRACTION_PROMPT_TEMPLATE: string;
+export declare function buildExtractionPrompt(text: string, detectedLang?: string): string;
+/** Parsed knowledge-graph edge emitted by the extractor LLM. */
+export interface ExtractedKgTriple {
+    subject: string;
+    predicate: string;
+    object: string;
+}
+/** Category-preserving extraction result used by background memory routing. */
+export interface ExtractedFactCategories {
+    facts: string[];
+    instructions: string[];
+    preferences: string[];
+    timelines: string[];
+    kg: ExtractedKgTriple[];
+}
+/** Flatten extracted string categories for legacy fact callers. */
+export declare function flattenExtractedFactCategories(extracted: ExtractedFactCategories): string[];
+/** Count string facts plus KG triples in a category-preserving extraction result. */
+export declare function countExtractedFactCategories(extracted: ExtractedFactCategories): number;
+/** Parse extractor output without discarding MEMORIA categories or KG triples. */
+export declare function parseExtractedFactCategories(rawOutput: string | null | undefined): ExtractedFactCategories;
+/** Parse extractor output into the legacy flat string fact list. */
+export declare function parseFacts(rawOutput: string | null | undefined): string[];
+export declare function heuristicExtractFacts(text: string): string[];
+/** Extract fact categories from text using configured, host, local, or remote LLMs. */
+export declare function extractFactCategories(text: string | null | undefined, options?: RemoteLlmOptions): Promise<ExtractedFactCategories>;
+/** Extract legacy flat fact strings from text. */
+export declare function extractFacts(text: string | null | undefined, options?: RemoteLlmOptions): Promise<string[]>;
+/** Safely extract category-preserving facts, swallowing best-effort failures. */
+export declare function extractFactCategoriesSafe(text: string | null | undefined): Promise<ExtractedFactCategories>;
+/** Safely extract legacy flat fact strings, swallowing best-effort failures. */
+export declare function extractFactsSafe(text: string | null | undefined): Promise<string[]>;

package/dist/types/core/fastembed-model-cache.d.ts

@@ -0,0 +1,2 @@
+/** Download missing config/tokenizer sidecars into a fastembed model cache directory. */
+export declare function ensureFastembedModelSidecars(model: string, cacheDir?: string): Promise<boolean>;

package/dist/types/core/fastembed-runtime.d.ts

@@ -0,0 +1,41 @@
+import { type RuntimeInstallSpec } from "@linxiraos/pi-utils";
+import type * as Fastembed from "fastembed";
+type FastembedModule = typeof Fastembed;
+/** Runtime install inputs for the optional fastembed embedding stack. */
+export interface FastembedRuntimeInstallPlan {
+    /** Cache directory key; changes when runtime resolution policy changes. */
+    versionKey: string;
+    /** Dependency graph written to the runtime cache package manifest. */
+    install: RuntimeInstallSpec;
+}
+/** Build the deterministic fastembed runtime install plan used by local embeddings. */
+export declare function fastembedRuntimeInstallPlan(): FastembedRuntimeInstallPlan;
+/** Inputs for selecting the Windows DLL directory paired with a fastembed installation. */
+export interface WindowsFastembedRuntimeOptions {
+    /** Resolved fastembed package entry whose dependency graph owns the ORT binding. */
+    fastembedEntry: string;
+    /** Directory containing fastembed's manifest and nested dependency graph. */
+    fastembedPackageDir: string;
+    /** Native architecture to select; defaults to the current process architecture. */
+    arch?: string;
+    /** Environment receiving the DLL search path; defaults to the subprocess environment. */
+    env?: NodeJS.ProcessEnv;
+}
+/** The ORT module and DLL directory selected from fastembed's own dependency graph. */
+export interface WindowsFastembedRuntime {
+    /** Resolved entry for fastembed's own ONNX Runtime dependency. */
+    ortEntry: string;
+    /** Package directory containing the selected ORT manifest and native assets. */
+    ortPackageDir: string;
+    /** Directory prepended to `PATH` so Windows finds the paired native DLL. */
+    dllDir: string;
+}
+/**
+ * Prepend the ORT DLL directory paired with fastembed before Bun loads its
+ * native binding. Compiled Windows binaries extract `.node` files to a
+ * temporary directory, so the default DLL search can otherwise select an
+ * unrelated `onnxruntime.dll` from the inherited system path.
+ */
+export declare function prepareWindowsFastembedRuntime({ fastembedEntry, fastembedPackageDir, arch, env, }: WindowsFastembedRuntimeOptions): Promise<WindowsFastembedRuntime>;
+export declare function loadFastembed(): Promise<FastembedModule>;
+export {};

package/dist/types/core/index.d.ts

@@ -0,0 +1,6 @@
+export { configureRecallFeatures, type RecallFeatureFlags } from "../config.js";
+export * from "./banks.js";
+export * from "./beam/index.js";
+export { defaultLocalModelInitializer, type LocalEmbeddingModel, type LocalModelInitializer, type LocalModelInitOptions, type StandardEmbeddingModel, setLocalModelInitializer, } from "./embeddings.js";
+export * from "./memory.js";
+export { addMemory, forget, get, getBank, getContext, getDefaultInstance, getStats, Mnemopi, query, recall, recallEnhanced, remember, resetDefaultInstanceForTests, resetMemoryForTests, resetModuleStateForTests, saveMemory, scratchpadClear, scratchpadRead, scratchpadWrite, search, setBank, sleep, sleepAllSessions, storeMemory, update, } from "./memory.js";

package/dist/types/core/llm-backends.d.ts

@@ -0,0 +1,23 @@
+import type { FetchImpl } from "@linxiraos/pi-ai";
+export interface CompleteOptions {
+    maxTokens?: number;
+    temperature?: number;
+    timeout?: number;
+    provider?: string | null;
+    model?: string | null;
+    fetch?: FetchImpl;
+}
+export interface LlmBackend {
+    name?: string;
+    complete(prompt: string, opts?: CompleteOptions): string | null | Promise<string | null>;
+}
+export declare function setHostLlmBackend(backend: LlmBackend | null | undefined): void;
+export declare function getHostLlmBackend(): LlmBackend | null;
+export declare function resetHostLlmBackendForTests(): void;
+export declare function callHostLlm(prompt: string, opts?: CompleteOptions): Promise<string | null>;
+export declare class CallableLlmBackend implements LlmBackend {
+    name: string;
+    private readonly fn;
+    constructor(name: string, fn: (prompt: string, opts?: CompleteOptions) => string | null | Promise<string | null>);
+    complete(prompt: string, opts?: CompleteOptions): string | null | Promise<string | null>;
+}

package/dist/types/core/local-llm.d.ts

@@ -0,0 +1,20 @@
+import { type FetchImpl } from "@linxiraos/pi-ai";
+import { type CompleteOptions } from "./llm-backends.js";
+import { type MnemopiLlmCompleteOptions } from "./runtime-options.js";
+export interface RemoteLlmOptions {
+    fetch?: FetchImpl;
+}
+export declare const DEFAULT_MODEL_REPO: string;
+export declare const DEFAULT_MODEL_FILE: string;
+export declare function buildPrompt(memories: readonly string[], source?: string): string;
+export declare function callConfiguredCompletion(prompt: string, temperature: number, opts?: MnemopiLlmCompleteOptions): Promise<string | null>;
+export declare function buildHostPrompt(memories: readonly string[], source?: string): string;
+export declare function configuredLlmWillHandleCall(): boolean;
+export declare function cleanOutput(text: string): string;
+export declare function chunkMemoriesByBudget(memories: readonly string[], source?: string): string[][];
+export declare function llmAvailable(): boolean;
+export declare function callRemoteLlm(prompt: string, temperature?: number, options?: RemoteLlmOptions): Promise<string | null>;
+export declare function localGgufAvailable(): false;
+export declare function callLocalLlm(_prompt: string): Promise<string | null>;
+export declare function summarizeMemories(memories: readonly string[], source?: string, options?: RemoteLlmOptions): Promise<string | null>;
+export declare function complete(prompt: string, temperature?: number, options?: CompleteOptions): Promise<string | null>;

package/dist/types/core/memory.d.ts

@@ -0,0 +1,186 @@
+import type { Database } from "bun:sqlite";
+import type { Api, ApiKey, Model } from "@linxiraos/pi-ai";
+import type { MemoryInput, Metadata } from "../types.js";
+import { BeamMemory } from "./beam/index.js";
+import type { RecallEnhancedOptions, RecallOptions, RecallResult, SleepResult } from "./beam/types.js";
+import { type MnemopiEmbeddingRuntimeOptions, type MnemopiLlmCompletion, type MnemopiLlmRuntimeOptions, type ResolvedMnemopiRuntimeOptions } from "./runtime-options.js";
+export interface MnemopiOptions {
+    readonly db?: Database;
+    readonly dbPath?: string;
+    readonly db_path?: string;
+    readonly sessionId?: string;
+    readonly session_id?: string;
+    readonly bank?: string | null;
+    readonly authorId?: string | null;
+    readonly author_id?: string | null;
+    readonly authorType?: string | null;
+    readonly author_type?: string | null;
+    readonly channelId?: string | null;
+    readonly channel_id?: string | null;
+    readonly noEmbeddings?: boolean;
+    readonly embeddingModel?: string;
+    readonly embeddingApiUrl?: string;
+    readonly embeddingApiKey?: ApiKey;
+    readonly embeddings?: false | MnemopiEmbeddingRuntimeOptions;
+    readonly llmEnabled?: boolean;
+    readonly llmBaseUrl?: string;
+    readonly llmApiKey?: ApiKey;
+    readonly llmModel?: string | Model<Api>;
+    readonly llm?: false | MnemopiLlmRuntimeOptions | Model<Api> | MnemopiLlmCompletion;
+    readonly proactiveLinking?: boolean;
+    /** Escalate best-effort failure logs (embedding pipeline) from debug to warn. */
+    readonly debug?: boolean;
+    /**
+     * When `false`, skip the embedding-model reconcile (wipe-and-rebuild) on open.
+     * Read-only / ephemeral consumers (e.g. a stats snapshot) set this so an open
+     * never triggers a destructive migration whose background rebuild the process
+     * would exit before completing. Defaults to `true`.
+     */
+    readonly reconcile?: boolean;
+}
+export interface RememberInput extends MemoryInput {
+    readonly extract?: boolean;
+    readonly extractEntities?: boolean;
+    readonly extract_entities?: boolean;
+    readonly extractText?: string | null;
+    readonly extract_text?: string | null;
+    readonly embedText?: string | null;
+    readonly embed_text?: string | null;
+    readonly trustTier?: string | null;
+    readonly trust_tier?: string | null;
+    readonly memoryType?: string | null;
+    readonly memory_type?: string | null;
+}
+export interface RememberFacadeOptions {
+    readonly source?: string | null;
+    readonly importance?: number;
+    readonly metadata?: Metadata | null;
+    readonly validUntil?: string | Date | null;
+    readonly valid_until?: string | Date | null;
+    readonly scope?: string | null;
+    readonly extractEntities?: boolean;
+    readonly extract_entities?: boolean;
+    readonly extract?: boolean;
+    /**
+     * Override the text passed to fact/entity extraction. When unset, the
+     * stored content is used. See {@link RememberOptions.extractText}.
+     */
+    readonly extractText?: string | null;
+    readonly extract_text?: string | null;
+    /**
+     * Override the text passed to embeddings and FTS indexing. Stored content
+     * remains unchanged; when unset, embeddings and FTS use stored content.
+     */
+    readonly embedText?: string | null;
+    readonly embed_text?: string | null;
+    readonly trustTier?: string | null;
+    readonly trust_tier?: string | null;
+    readonly timestamp?: string | Date | null;
+    readonly veracity?: string | null;
+    readonly memoryType?: string | null;
+    readonly memory_type?: string | null;
+}
+export interface RecallFacadeOptions extends Omit<RecallOptions, "temporalHalflife" | "vecWeight" | "ftsWeight" | "importanceWeight"> {
+    readonly from_date?: string | null;
+    readonly to_date?: string | null;
+    readonly source?: string | null;
+    readonly topic?: string | null;
+    readonly temporalWeight?: number;
+    readonly temporal_weight?: number;
+    readonly query_time?: string | Date | null;
+    readonly temporalHalflife?: number | null;
+    readonly temporal_halflife?: number | null;
+    readonly vecWeight?: number | null;
+    readonly vec_weight?: number | null;
+    readonly ftsWeight?: number | null;
+    readonly fts_weight?: number | null;
+    readonly importanceWeight?: number | null;
+    readonly importance_weight?: number | null;
+}
+export interface MemoryFacadeStats {
+    total_memories: number;
+    total_sessions: number;
+    sources: Record<string, number>;
+    last_memory: string | null;
+    database: string;
+    mode: "beam";
+    banks: string[];
+    beam: {
+        working_memory: unknown;
+        episodic_memory: unknown;
+        triples: {
+            total: number;
+        };
+    };
+}
+type ModuleRememberOptions = RememberFacadeOptions & {
+    readonly bank?: string | null;
+};
+type ModuleRecallOptions = RecallFacadeOptions & {
+    readonly bank?: string | null;
+};
+type ModuleRecallEnhancedOptions = RecallFacadeOptions & RecallEnhancedOptions & {
+    readonly bank?: string | null;
+};
+export declare class Mnemopi {
+    #private;
+    readonly sessionId: string;
+    readonly bank: string;
+    readonly dbPath?: string;
+    readonly authorId: string | null;
+    readonly authorType: string | null;
+    readonly channelId: string;
+    readonly beam: BeamMemory;
+    readonly conn: Database;
+    readonly db: Database;
+    readonly runtimeOptions?: ResolvedMnemopiRuntimeOptions;
+    constructor(options?: MnemopiOptions);
+    close(): void;
+    flushExtractions(): Promise<void>;
+    remember(memory: string | RememberInput, options?: RememberFacadeOptions): string;
+    recall(query: string, topK?: number, options?: RecallFacadeOptions): Promise<RecallResult[]>;
+    recallEnhanced(query: string, topK?: number, options?: RecallFacadeOptions & RecallEnhancedOptions): Promise<RecallResult[]>;
+    getContext(limit?: number): unknown[];
+    getStats(authorId?: string | null, authorType?: string | null, channelId?: string | null): MemoryFacadeStats;
+    get(memoryId: string): unknown | null;
+    forget(memoryId: string): boolean;
+    update(memoryId: string, content?: string | null, importance?: number | null): boolean;
+    sleep(dryRun?: boolean): SleepResult;
+    sleepAllSessions(dryRun?: boolean): SleepResult;
+    scratchpadWrite(content: string): string;
+    scratchpadRead(): unknown[];
+    scratchpadClear(): void;
+    addMemory(memory: string | RememberInput, options?: RememberFacadeOptions): string;
+    saveMemory(memory: string | RememberInput, options?: RememberFacadeOptions): string;
+    storeMemory(memory: string | RememberInput, options?: RememberFacadeOptions): string;
+    search(query: string, topK?: number, options?: RecallFacadeOptions): Promise<RecallResult[]>;
+    query(query: string, topK?: number, options?: RecallFacadeOptions): Promise<RecallResult[]>;
+    consolidate(dryRun?: boolean): SleepResult;
+}
+export declare function setBank(bank: string): void;
+export declare function getBank(): string;
+export declare function getDefaultInstance(bank?: string | null): Mnemopi;
+export declare function remember(content: string | RememberInput, options?: ModuleRememberOptions): string;
+export declare function recall(query: string, topK?: number, options?: ModuleRecallOptions): Promise<RecallResult[]>;
+export declare function recallEnhanced(query: string, topK?: number, options?: ModuleRecallEnhancedOptions): Promise<RecallResult[]>;
+export declare function getContext(limit?: number, bank?: string | null): unknown[];
+export declare function getStats(bank?: string | null): MemoryFacadeStats;
+export declare function get(memoryId: string, bank?: string | null): unknown | null;
+export declare function forget(memoryId: string, bank?: string | null): boolean;
+export declare function update(memoryId: string, content?: string | null, importance?: number | null, bank?: string | null): boolean;
+export declare function sleep(dryRun?: boolean, bank?: string | null): SleepResult;
+export declare function sleepAllSessions(dryRun?: boolean, bank?: string | null): SleepResult;
+export declare function flushExtractions(bank?: string | null): Promise<void>;
+export declare function scratchpadWrite(content: string, bank?: string | null): string;
+export declare function scratchpadRead(bank?: string | null): unknown[];
+export declare function scratchpadClear(bank?: string | null): void;
+export declare function addMemory(memory: string | RememberInput, options?: ModuleRememberOptions): string;
+export declare function saveMemory(memory: string | RememberInput, options?: ModuleRememberOptions): string;
+export declare function storeMemory(memory: string | RememberInput, options?: ModuleRememberOptions): string;
+export declare function search(query: string, topK?: number, options?: ModuleRecallOptions): Promise<RecallResult[]>;
+export declare function query(query: string, topK?: number, options?: ModuleRecallOptions): Promise<RecallResult[]>;
+export declare function resetDefaultInstanceForTests(): void;
+export declare function resetMemoryForTests(): void;
+export declare function resetModuleStateForTests(): void;
+export type { MemoryInput, MemoryStats } from "../types.js";
+export default Mnemopi;

package/dist/types/core/migrations/e6-triplestore-split.d.ts

@@ -0,0 +1,17 @@
+import type { Database } from "bun:sqlite";
+import { type DatabasePath } from "../../db.js";
+export declare const ANNOTATION_KINDS: readonly ["mentions", "fact", "occurred_on", "has_source"];
+export type AnnotationKind = (typeof ANNOTATION_KINDS)[number];
+export interface MigrationOptions {
+    readonly dbPath: DatabasePath;
+    readonly dryRun?: boolean;
+    readonly backup?: boolean;
+    readonly logFn?: (line: string) => void;
+}
+export interface PendingConnection {
+    query<T = unknown>(sql: string): {
+        get(...params: unknown[]): T | null;
+    };
+}
+export declare function hasPendingMigration(db: Database): boolean;
+export declare function migrate(dbPathOrOptions: DatabasePath | MigrationOptions, dryRun?: boolean, backup?: boolean, logFn?: (line: string) => void): number;

package/dist/types/core/migrations/index.d.ts

@@ -0,0 +1 @@
+export * from "./e6-triplestore-split.js";

package/dist/types/core/mmr.d.ts

@@ -0,0 +1,8 @@
+export interface MmrResult {
+    readonly content?: string;
+    readonly score?: number;
+    readonly [key: string]: unknown;
+}
+export type SimilarityFn = (textA: string, textB: string) => number;
+export declare function jaccardSimilarity(textA: string, textB: string): number;
+export declare function mmrRerank<T extends MmrResult>(results: readonly T[], lambdaParam?: number, topK?: number, similarityFn?: SimilarityFn): T[];