@oh-my-pi/pi-mnemosyne 15.6.0

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

@@ -0,0 +1,160 @@
+import type { Database } from "bun:sqlite";
+import type { Api, Model } from "@oh-my-pi/pi-ai";
+import type { MemoryInput, Metadata } from "../types";
+import { BeamMemory } from "./beam/index";
+import type { RecallEnhancedOptions, RecallOptions, RecallResult, SleepResult } from "./beam/types";
+import { type MnemosyneEmbeddingRuntimeOptions, type MnemosyneLlmCompletion, type MnemosyneLlmRuntimeOptions, type ResolvedMnemosyneRuntimeOptions } from "./runtime-options";
+export interface MnemosyneOptions {
+    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?: string;
+    readonly embeddings?: false | MnemosyneEmbeddingRuntimeOptions;
+    readonly llmEnabled?: boolean;
+    readonly llmBaseUrl?: string;
+    readonly llmApiKey?: string;
+    readonly llmModel?: string | Model<Api>;
+    readonly llm?: false | MnemosyneLlmRuntimeOptions | Model<Api> | MnemosyneLlmCompletion;
+}
+export interface RememberInput extends MemoryInput {
+    readonly extract?: boolean;
+    readonly extractEntities?: boolean;
+    readonly extract_entities?: boolean;
+    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;
+    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 Mnemosyne {
+    #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?: ResolvedMnemosyneRuntimeOptions;
+    constructor(options?: MnemosyneOptions);
+    close(): void;
+    flushExtractions(): Promise<void>;
+    remember(memory: string | RememberInput, options?: RememberFacadeOptions): string;
+    recall(query: string, topK?: number, options?: RecallFacadeOptions): RecallResult[];
+    recallEnhanced(query: string, topK?: number, options?: RecallFacadeOptions & RecallEnhancedOptions): 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): RecallResult[];
+    query(query: string, topK?: number, options?: RecallFacadeOptions): RecallResult[];
+    consolidate(dryRun?: boolean): SleepResult;
+}
+export declare function setBank(bank: string): void;
+export declare function getBank(): string;
+export declare function getDefaultInstance(bank?: string | null): Mnemosyne;
+export declare function remember(content: string | RememberInput, options?: ModuleRememberOptions): string;
+export declare function recall(query: string, topK?: number, options?: ModuleRecallOptions): RecallResult[];
+export declare function recallEnhanced(query: string, topK?: number, options?: ModuleRecallEnhancedOptions): 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): RecallResult[];
+export declare function query(query: string, topK?: number, options?: ModuleRecallOptions): RecallResult[];
+export declare function resetDefaultInstanceForTests(): void;
+export declare function resetMemoryForTests(): void;
+export declare function resetModuleStateForTests(): void;
+export type { MemoryInput, MemoryStats } from "../types";
+export default Mnemosyne;

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";
+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";

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[];

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

@@ -0,0 +1,20 @@
+import type { BeamMemoryState, RecallOptions, RecallResult } from "./beam/types";
+import { type PolyphonicMemoryResult, type PolyphonicRecallOptions } from "./polyphonic-recall";
+export interface OrchestratorBeam extends BeamMemoryState {
+    recall?: (query: string, topK?: number, options?: RecallOptions) => RecallResult[];
+    recallEnhanced?: (query: string, topK?: number, options?: RecallOptions) => RecallResult[];
+}
+export interface OrchestrateRecallOptions extends Omit<RecallOptions, "queryEmbedding">, Omit<PolyphonicRecallOptions, "queryEmbedding"> {
+    readonly queryEmbedding?: readonly number[] | Float32Array | null;
+    readonly enhanced?: boolean;
+    readonly forcePolyphonic?: boolean;
+    readonly forceLinear?: boolean;
+}
+export interface OrchestratedRecallResult extends Omit<RecallResult, "metadata" | "score" | "tier"> {
+    score?: number;
+    metadata?: RecallResult["metadata"];
+    tier?: RecallResult["tier"] | PolyphonicMemoryResult["tier"];
+    combined_score?: PolyphonicMemoryResult["combined_score"];
+    voice_scores?: PolyphonicMemoryResult["voice_scores"];
+}
+export declare function orchestrateRecall(beam: OrchestratorBeam, query: string, topK?: number, options?: OrchestrateRecallOptions): OrchestratedRecallResult[];

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

@@ -0,0 +1,61 @@
+export interface CompressionStatsInit {
+    readonly originalSize?: number;
+    readonly compressedSize?: number;
+    readonly ratio?: number;
+    readonly method?: string;
+    readonly patternsFound?: number;
+    readonly memoriesCompressed?: number;
+}
+export declare class CompressionStats {
+    originalSize: number;
+    compressedSize: number;
+    ratio: number;
+    method: string;
+    patternsFound: number;
+    memoriesCompressed: number;
+    constructor(init?: CompressionStatsInit);
+    get savingsPercent(): number;
+}
+export type MemoryRecord = Record<string, unknown> & {
+    content?: string;
+    timestamp?: string;
+    created_at?: string;
+    source?: string;
+};
+export declare class MemoryCompressor {
+    readonly dictionary: Readonly<Record<string, string>>;
+    constructor(dictionary?: Readonly<Record<string, string>>);
+    static buildDefaultDict(): Record<string, string>;
+    compress(content: string, method?: string): readonly [string, CompressionStats];
+    private dictCompress;
+    private rleCompress;
+    private semanticCompressSingle;
+    compressBatch(memories: readonly MemoryRecord[], method?: string): readonly [MemoryRecord[], CompressionStats];
+    decompress(content: string, method?: string): string;
+}
+export interface DetectedPatternInit {
+    readonly patternType?: string;
+    readonly pattern_type?: string;
+    readonly description: string;
+    readonly confidence: number;
+    readonly samples?: readonly string[];
+    readonly metadata?: Record<string, unknown>;
+}
+export declare class DetectedPattern {
+    patternType: string;
+    description: string;
+    confidence: number;
+    samples: string[];
+    metadata: Record<string, unknown>;
+    constructor(init: DetectedPatternInit);
+    toDict(): Record<string, unknown>;
+}
+export declare class PatternDetector {
+    readonly minConfidence: number;
+    constructor(minConfidence?: number);
+    detectTemporal(memories: readonly MemoryRecord[]): DetectedPattern[];
+    detectContent(memories: readonly MemoryRecord[]): DetectedPattern[];
+    detectSequence(memories: readonly MemoryRecord[]): DetectedPattern[];
+    detectAll(memories: readonly MemoryRecord[]): DetectedPattern[];
+    summarizePatterns(memories: readonly MemoryRecord[]): Record<string, unknown>;
+}

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

@@ -0,0 +1,109 @@
+export declare const DEFAULT_PLUGIN_DIR: string;
+export type PluginConfig = Record<string, unknown>;
+export type MemoryDict = Record<string, unknown>;
+export declare class MnemosynePlugin {
+    static readonly abstractBase = true;
+    name: string;
+    version: string;
+    enabled: boolean;
+    protected initialized: boolean;
+    readonly config: PluginConfig;
+    constructor(config?: PluginConfig);
+    initialize(): void;
+    shutdown(): void;
+    onRemember(_memory: MemoryDict): void;
+    onRecall(_memory: MemoryDict): void;
+    onConsolidate(_summary: MemoryDict): void;
+    onInvalidate(_memoryId: string): void;
+    toDict(): Record<string, unknown>;
+}
+export declare class LoggingPlugin extends MnemosynePlugin {
+    name: string;
+    version: string;
+    private readonly memoryLog;
+    private readonly maxEntries;
+    constructor(config?: PluginConfig);
+    private append;
+    onRemember(memory: MemoryDict): void;
+    onRecall(memory: MemoryDict): void;
+    onConsolidate(summary: MemoryDict): void;
+    onInvalidate(memoryId: string): void;
+    getLog(): MemoryDict[];
+    clearLog(): void;
+}
+export declare class MetricsPlugin extends MnemosynePlugin {
+    name: string;
+    version: string;
+    private readonly counters;
+    private readonly timings;
+    private readonly maxTimingSamples;
+    constructor(config?: PluginConfig);
+    onRemember(_memory: MemoryDict): void;
+    onRecall(_memory: MemoryDict): void;
+    onConsolidate(_summary: MemoryDict): void;
+    onInvalidate(_memoryId: string): void;
+    recordTiming(event: string, durationMs: number): void;
+    getCounters(): Record<string, number>;
+    getTimings(event: string): number[];
+    getAverageTiming(event: string): number | null;
+    reset(): void;
+    getSummary(): Record<string, unknown>;
+}
+export type FilterRule = (item: MemoryDict) => boolean;
+export declare class FilterPlugin extends MnemosynePlugin {
+    name: string;
+    version: string;
+    private readonly rules;
+    private readonly blocked;
+    private readonly maxBlocked;
+    constructor(config?: PluginConfig);
+    addRule(rule: FilterRule): void;
+    removeRule(rule: FilterRule): void;
+    clearRules(): void;
+    onRemember(memory: MemoryDict): void;
+    onRecall(memory: MemoryDict): void;
+    onConsolidate(summary: MemoryDict): void;
+    onInvalidate(_memoryId: string): void;
+    private passes;
+    private block;
+    getBlocked(): MemoryDict[];
+    isBlocked(memoryId: string): boolean;
+}
+export declare class CompressionPlugin extends MnemosynePlugin {
+    name: string;
+    version: string;
+    enabled: boolean;
+    private readonly threshold;
+    constructor(config?: PluginConfig);
+    compressLines(lines: string[]): string[];
+    onRemember(_memory: MemoryDict): void;
+    onRecall(_memory: MemoryDict): void;
+    onConsolidate(_summary: MemoryDict): void;
+    onInvalidate(_memoryId: string): void;
+}
+export type PluginConstructor<T extends MnemosynePlugin = MnemosynePlugin> = new (config?: PluginConfig) => T;
+export declare class PluginManager {
+    private readonly pluginDir;
+    private readonly registry;
+    private readonly instances;
+    constructor(pluginDir?: string);
+    registerPlugin(name: string, pluginClass: PluginConstructor): void;
+    loadPlugin(name: string, config?: PluginConfig): MnemosynePlugin;
+    unloadPlugin(name: string): void;
+    listPlugins(): Array<Record<string, unknown>>;
+    getPlugin(name: string): MnemosynePlugin | null;
+    isLoaded(name: string): boolean;
+    isRegistered(name: string): boolean;
+    loadAll(configs?: Record<string, PluginConfig>): MnemosynePlugin[];
+    unloadAll(): void;
+    discoverPlugins(): string[];
+    notifyRemember(memory: MemoryDict): void;
+    notifyRecall(memory: MemoryDict): void;
+    notifyConsolidate(summary: MemoryDict): void;
+    notifyInvalidate(memoryId: string): void;
+}
+export declare class ValueError extends Error {
+    name: string;
+}
+export declare function getManager(): PluginManager;
+export declare function resetManager(): void;

package/dist/types/core/polyphonic-recall.d.ts

@@ -0,0 +1,66 @@
+import type { Database } from "bun:sqlite";
+import { type Env } from "../config";
+import { type DatabasePath } from "../db";
+import type { BeamMemoryState, JsonValue, Metadata, RecallResult } from "./beam/types";
+import { EpisodicGraph } from "./episodic-graph";
+import { VeracityConsolidator } from "./veracity-consolidation";
+export type PolyphonicVoice = "vector" | "graph" | "fact" | "temporal";
+export interface VoiceRecallResult {
+    readonly memoryId: string;
+    readonly score: number;
+    readonly voice: PolyphonicVoice;
+    readonly metadata: Metadata;
+}
+export interface PolyphonicResult {
+    readonly memoryId: string;
+    combinedScore: number;
+    readonly voiceScores: Partial<Record<PolyphonicVoice, number>>;
+    readonly metadata: Metadata;
+}
+export interface PolyphonicMemoryResult extends Omit<RecallResult, "metadata" | "score" | "tier"> {
+    score: number;
+    combined_score: number;
+    voice_scores: Partial<Record<PolyphonicVoice, number>>;
+    metadata: Metadata;
+    tier: "working" | "episodic";
+}
+export interface PolyphonicRecallOptions {
+    readonly queryEmbedding?: readonly number[] | Float32Array | null;
+    readonly contextBudget?: number;
+}
+interface PolyphonicEngineOptions {
+    readonly dbPath?: DatabasePath;
+    readonly db?: Database;
+    readonly graph?: EpisodicGraph;
+    readonly consolidator?: VeracityConsolidator;
+    readonly sessionId?: string | null;
+    readonly channelId?: string | null;
+}
+export declare function polyphonicRecallIsEnabled(env?: Env): boolean;
+export declare class PolyphonicRecallEngine {
+    readonly dbPath: DatabasePath;
+    readonly db: Database;
+    readonly ownsConnection: boolean;
+    readonly graph: EpisodicGraph;
+    readonly consolidator: VeracityConsolidator;
+    readonly sessionId: string;
+    readonly channelId: string | null;
+    readonly voiceWeights: Readonly<Record<PolyphonicVoice, number>>;
+    constructor(options?: PolyphonicEngineOptions);
+    recall(query: string, queryEmbedding?: readonly number[] | Float32Array | null, topK?: number, contextBudget?: number): PolyphonicMemoryResult[];
+    vectorVoice(queryEmbedding: readonly number[] | Float32Array | null): VoiceRecallResult[];
+    graphVoice(query: string): VoiceRecallResult[];
+    factVoice(query: string): VoiceRecallResult[];
+    temporalVoice(query: string): VoiceRecallResult[];
+    combineVoices(...voiceResults: readonly VoiceRecallResult[][]): Map<string, PolyphonicResult>;
+    diversityRerank(results: ReadonlyMap<string, PolyphonicResult>, topK: number): PolyphonicResult[];
+    estimateSimilarity(a: PolyphonicResult, b: PolyphonicResult): number;
+    assembleContext(results: readonly PolyphonicResult[], budget: number): PolyphonicResult[];
+    getStats(): Record<string, JsonValue>;
+    close(): void;
+    private hydrateResults;
+    private lookupMemory;
+}
+export declare function getPolyphonicEngine(beam: BeamMemoryState): PolyphonicRecallEngine;
+export declare function polyphonicRecall(beam: BeamMemoryState, query: string, topK?: number, options?: PolyphonicRecallOptions): PolyphonicMemoryResult[];
+export {};

package/dist/types/core/query-cache.d.ts

@@ -0,0 +1,47 @@
+export type QueryCacheResult = Record<string, unknown>;
+export type QueryEmbedding = readonly number[];
+export interface QueryCacheOptions {
+    readonly dbPath?: string | null;
+    readonly db_path?: string | null;
+    readonly maxSize?: number;
+    readonly max_size?: number;
+    readonly ttlSeconds?: number;
+    readonly ttl_seconds?: number;
+}
+export interface QueryCacheStats {
+    readonly hits: number;
+    readonly misses: number;
+    readonly hit_rate: number;
+    readonly tier1_hits: number;
+    readonly tier2_hits: number;
+    readonly tier3_hits: number;
+    readonly tier4_hits: number;
+    readonly size: number;
+    readonly max_size: number;
+    readonly version: number;
+}
+type Env = Readonly<Record<string, string | undefined>>;
+export declare function isEnhancedRecallEnabled(env?: Env): boolean;
+export declare function isQueryCacheEnabled(useCache?: boolean, env?: Env): boolean;
+export declare class QueryCache {
+    #private;
+    readonly maxSize: number;
+    readonly ttlSeconds: number;
+    hits: number;
+    misses: number;
+    tier1Hits: number;
+    tier2Hits: number;
+    tier3Hits: number;
+    tier4Hits: number;
+    constructor(options?: QueryCacheOptions | string | null, maxSize?: number, ttlSeconds?: number);
+    invalidate(): void;
+    get(query: string, embedding?: QueryEmbedding | null): readonly QueryCacheResult[] | null;
+    put(query: string, results: readonly QueryCacheResult[], embedding?: QueryEmbedding | null): void;
+    close(): void;
+    get hitRate(): number;
+    stats(): QueryCacheStats;
+    normalize(query: string): string;
+    cosineSimilarity(embA: QueryEmbedding, embB: QueryEmbedding): number;
+    jaccardWords(queryA: string, queryB: string): number;
+}
+export {};

package/dist/types/core/query-intent.d.ts

@@ -0,0 +1,20 @@
+export type QueryIntentCategory = "temporal" | "factual" | "entity" | "preference" | "procedural" | "general";
+export interface QueryIntent {
+    readonly category: QueryIntentCategory;
+    readonly confidence: number;
+    readonly signals: QueryIntentCategory[];
+    readonly vec_bias: number;
+    readonly fts_bias: number;
+    readonly importance_bias: number;
+}
+export interface IntentWeights {
+    readonly vec_bias: number;
+    readonly fts_bias: number;
+    readonly importance_bias: number;
+}
+type IntentPatternGroup = readonly [QueryIntentCategory, readonly RegExp[]];
+export declare const INTENT_PATTERNS: readonly IntentPatternGroup[];
+export declare const INTENT_WEIGHTS: Record<QueryIntentCategory, IntentWeights>;
+export declare function classifyIntent(query: string): QueryIntent;
+export declare function adjustWeights(baseVec?: number, baseFts?: number, baseImportance?: number, intent?: QueryIntent | null): [number, number, number];
+export {};

package/dist/types/core/recall-diagnostics.d.ts

@@ -0,0 +1,48 @@
+export declare const RECALL_TIERS: readonly ["wm_fts", "wm_vec", "wm_fallback", "em_fts", "em_vec", "em_fallback"];
+export type RecallTier = (typeof RECALL_TIERS)[number];
+export interface TierStatsSnapshot {
+    readonly calls_with_hits: number;
+    readonly total_hits: number;
+}
+export interface RecallDiagnosticsSnapshot {
+    readonly created_at: string;
+    readonly snapshot_at: string;
+    readonly totals: {
+        readonly calls: number;
+        readonly calls_using_wm_fallback: number;
+        readonly calls_using_em_fallback: number;
+        readonly calls_truly_empty: number;
+        readonly wm_fallback_rate: number;
+        readonly em_fallback_rate: number;
+    };
+    readonly by_tier: Record<RecallTier, TierStatsSnapshot>;
+}
+export declare class RecallDiagnostics {
+    private tierStats;
+    private totalCalls;
+    private callsUsingWmFallback;
+    private callsUsingEmFallback;
+    private callsTrulyEmpty;
+    private createdAt;
+    constructor();
+    private static validateTier;
+    recordTierHits(tier: RecallTier | string, hitCount: number): void;
+    recordFallbackUsed(options?: {
+        readonly wm?: boolean;
+        readonly em?: boolean;
+    }): void;
+    recordCall(options?: {
+        readonly trulyEmpty?: boolean;
+        readonly truly_empty?: boolean;
+    }): void;
+    fallbackRate(): {
+        readonly wm: number;
+        readonly em: number;
+    };
+    snapshot(): RecallDiagnosticsSnapshot;
+    reset(): void;
+}
+export declare function getDiagnostics(): RecallDiagnostics;
+export declare function getRecallDiagnostics(): RecallDiagnosticsSnapshot;
+export declare function resetRecallDiagnostics(): void;
+export declare function explainRecallDiagnostics(snapshot: RecallDiagnosticsSnapshot): string[];

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

@@ -0,0 +1,61 @@
+import type { Api, Model } from "@oh-my-pi/pi-ai";
+export interface MnemosyneLlmCompleteOptions {
+    maxTokens?: number;
+    temperature?: number;
+    timeout?: number;
+    provider?: string | null;
+    model?: string | null;
+}
+export type MnemosyneLlmCompletion = (prompt: string, opts?: MnemosyneLlmCompleteOptions) => string | null | Promise<string | null>;
+export interface MnemosyneEmbeddingProvider {
+    embed(texts: readonly string[]): unknown | Promise<unknown>;
+    available?(): boolean | Promise<boolean>;
+}
+export interface MnemosyneEmbeddingRuntimeOptions {
+    disabled?: boolean;
+    model?: string;
+    apiUrl?: string;
+    apiKey?: string;
+    provider?: MnemosyneEmbeddingProvider | ((texts: readonly string[]) => unknown | Promise<unknown>);
+}
+export interface MnemosyneLlmRuntimeOptions {
+    enabled?: boolean;
+    baseUrl?: string;
+    apiKey?: string;
+    model?: string | Model<Api>;
+    maxTokens?: number;
+    complete?: MnemosyneLlmCompletion;
+    /** Override the fact-extraction prompt template ({text}/{lang}). Used to feed small local models a friendlier format. */
+    extractionPrompt?: string;
+    /** Override the consolidation/sleep prompt template ({memories}/{source}/{memory_count}). */
+    consolidationPrompt?: string;
+}
+export interface MnemosyneRuntimeOptions {
+    embeddings?: false | MnemosyneEmbeddingRuntimeOptions;
+    llm?: false | MnemosyneLlmRuntimeOptions | Model<Api> | MnemosyneLlmCompletion;
+}
+export interface ResolvedMnemosyneEmbeddingRuntimeOptions {
+    disabled?: boolean;
+    model?: string;
+    apiUrl?: string;
+    apiKey?: string;
+    provider?: MnemosyneEmbeddingProvider;
+}
+export interface ResolvedMnemosyneLlmRuntimeOptions {
+    enabled?: boolean;
+    baseUrl?: string;
+    apiKey?: string;
+    model?: string | Model<Api>;
+    maxTokens?: number;
+    complete?: MnemosyneLlmCompletion;
+    extractionPrompt?: string;
+    consolidationPrompt?: string;
+}
+export interface ResolvedMnemosyneRuntimeOptions {
+    embeddings?: ResolvedMnemosyneEmbeddingRuntimeOptions;
+    llm?: ResolvedMnemosyneLlmRuntimeOptions;
+}
+export declare function withMnemosyneRuntimeOptions<T>(options: ResolvedMnemosyneRuntimeOptions | undefined, fn: () => T): T;
+export declare function getMnemosyneRuntimeOptions(): ResolvedMnemosyneRuntimeOptions | undefined;
+export declare function resolveEmbeddingProvider(provider: MnemosyneEmbeddingProvider | ((texts: readonly string[]) => unknown | Promise<unknown>) | undefined): MnemosyneEmbeddingProvider | undefined;
+export declare function isPiAiModel(value: unknown): value is Model<Api>;