@oh-my-pi/pi-mnemosyne 15.6.0

package/README.md

@@ -0,0 +1,107 @@
+# @oh-my-pi/pi-mnemosyne
+
+Local SQLite memory engine for Oh My Pi agents.
+
+This package is the Bun/TypeScript port of the Mnemosyne memory engine. It provides:
+
+- `Mnemosyne`, a small facade for remember/recall/stats/sleep workflows.
+- `BeamMemory`, the lower-level working/episodic memory engine.
+- MCP tool definitions and a dispatcher for host integrations.
+- Optional local ONNX embeddings through `fastembed` and optional OpenAI-compatible embedding/LLM endpoints.
+
+The package does not bundle or download a local GGUF LLM. LLM paths are host-backend or OpenAI-compatible remote only; when no LLM is configured, deterministic heuristic paths are used.
+
+## Basic use
+
+```ts
+import { Mnemosyne } from "@oh-my-pi/pi-mnemosyne";
+
+const memory = new Mnemosyne({ dbPath: "./mnemosyne.db", bank: "project" });
+const id = memory.remember("The deployment target is stable-cluster.", {
+	source: "notes",
+	importance: 0.8,
+	veracity: "true",
+});
+
+const results = memory.recall("deployment target", 5);
+console.log(id, results[0]?.content);
+
+memory.close();
+```
+
+## Configuration
+
+`Mnemosyne` accepts LLM and embedding options directly. `MNEMOSYNE_*` environment variables remain fallbacks/defaults when the matching constructor option is omitted.
+
+```ts
+import { Mnemosyne } from "@oh-my-pi/pi-mnemosyne";
+import type { Model } from "@oh-my-pi/pi-ai";
+
+const ftsOnly = new Mnemosyne({ noEmbeddings: true });
+
+const remoteEmbeddings = new Mnemosyne({
+	embeddingModel: "text-embedding-3-small",
+	embeddingApiUrl: "https://api.openai.com/v1",
+	embeddingApiKey: process.env.OPENAI_API_KEY,
+});
+
+const remoteLlm = new Mnemosyne({
+	llm: {
+		baseUrl: "https://api.openai.com/v1",
+		apiKey: process.env.OPENAI_API_KEY,
+		model: "gpt-4.1-mini",
+	},
+	// Equivalent aliases: llmBaseUrl, llmApiKey, llmModel.
+});
+
+declare const smolModel: Model;
+const piAiLlm = new Mnemosyne({ llm: smolModel });
+const dynamicLlm = new Mnemosyne({
+	llm: async (prompt, opts) => {
+		const token = await getFreshOauthToken();
+		return await completeWithPiAi(prompt, {
+			token,
+			maxTokens: opts?.maxTokens,
+			temperature: opts?.temperature,
+		});
+	},
+});
+```
+
+### Banks and host scoping
+
+`Mnemosyne` itself exposes banks directly through constructor options such as `bank`; it does not hard-code coding-agent project scoping.
+
+The Oh My Pi coding-agent wrapper adds `mnemosyne.scoping` on top of those constructor options:
+
+- `global`: one shared bank
+- `per-project`: isolated project memory
+- `per-project-tagged`: project-local writes plus global recall visibility
+
+In `per-project-tagged`, the wrapper is responsible for combining project-local retention with global recall visibility. The package still just exposes banks plus constructor-level LLM and embedding options.
+
+Common environment fallbacks:
+
+- `MNEMOSYNE_DATA_DIR` / `MNEMOSYNE_DB_PATH`: default storage location.
+- `MNEMOSYNE_NO_EMBEDDINGS=1`: force FTS-only recall.
+- `MNEMOSYNE_EMBEDDING_MODEL`: defaults to `BAAI/bge-small-en-v1.5`.
+- `MNEMOSYNE_EMBEDDING_API_URL` and `MNEMOSYNE_EMBEDDING_API_KEY`: OpenAI-compatible embedding endpoint.
+- `MNEMOSYNE_LLM_ENABLED=1`, `MNEMOSYNE_LLM_BASE_URL`, `MNEMOSYNE_LLM_API_KEY`, `MNEMOSYNE_LLM_MODEL`: OpenAI-compatible LLM endpoint.
+
+Local embeddings use the `fastembed` npm package. Its default `BGESmallENV15` model is 384-dimensional and uses the package's CLS pooling plus vector normalization path. Local GGUF LLMs are not available in this package.
+
+## Commands
+
+```sh
+mnemosyne remember "Use stable-cluster for production deploys"
+mnemosyne recall "production deploy target"
+mnemosyne stats
+mnemosyne sleep
+```
+
+## Tests
+
+```sh
+bun --cwd packages/mnemosyne test
+bun --cwd packages/mnemosyne run check
+```

package/dist/types/cli.d.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env bun
+import { BeamMemory } from "./core/beam";
+export interface CliIo {
+    write(data: string): void;
+}
+export interface CliContext {
+    readonly dataDir?: string;
+    readonly dbPath?: string;
+    readonly memory?: BeamMemory;
+    readonly createMemory?: () => BeamMemory;
+    readonly stdout?: CliIo;
+    readonly stderr?: CliIo;
+}
+export declare class CliError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+type CommandHandler = (args: readonly string[], context?: CliContext) => number | Promise<number>;
+export declare function memoryStats(memory: BeamMemory, dataDir?: string): Record<string, unknown>;
+export declare const cmdExport: CommandHandler;
+export declare const cmdImport: CommandHandler;
+export declare const cmdMcp: CommandHandler;
+export declare const cmdRemember: CommandHandler;
+export declare const cmdRecall: CommandHandler;
+export declare const cmdUpdate: CommandHandler;
+export declare const cmdDelete: CommandHandler;
+export declare const cmdStats: CommandHandler;
+export declare const cmdSleep: CommandHandler;
+export declare const cmdScratchpad: CommandHandler;
+export declare const cmdBank: CommandHandler;
+export declare const cmdDiagnose: CommandHandler;
+export declare const COMMANDS: Readonly<Record<string, CommandHandler>>;
+export declare function printHelp(context?: CliContext): void;
+export declare function runCli(args?: readonly string[], context?: CliContext): Promise<number>;
+export {};

package/dist/types/config.d.ts

@@ -0,0 +1,77 @@
+import { type Env, envBool, envDisabled, envFloat, envInt, envOneOf, envOptionalString, envString, envTruthy } from "./util/env";
+export type { Env };
+export { envBool, envDisabled, envFloat, envInt, envOneOf, envOptionalString, envString, envTruthy };
+export declare const DEFAULT_DATA_DIR: string;
+export declare const DEFAULT_DB_FILENAME = "mnemosyne.db";
+export declare const FASTEMBED_CACHE_DIR: string;
+export declare const MODEL_CACHE_DIR: string;
+export declare const DEFAULT_EMBEDDING_MODEL = "BAAI/bge-small-en-v1.5";
+export declare const DEFAULT_EMBEDDING_API_URL = "https://openrouter.ai/api/v1";
+export declare const DEFAULT_LLM_MODEL_REPO = "TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF";
+export declare const DEFAULT_LLM_MODEL_FILE = "tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf";
+export declare const HOST_LLM_TIMEOUT_SECONDS = 15;
+export type VecType = "float32" | "int8" | "bit";
+export declare const EMBEDDING_DIMS: Readonly<Record<string, number>>;
+export declare const VERACITY_WEIGHT_DEFAULTS: {
+    readonly stated: 1;
+    readonly inferred: 0.7;
+    readonly tool: 0.5;
+    readonly imported: 0.6;
+    readonly unknown: 0.8;
+};
+export declare function dataDir(env?: Env): string;
+export declare function dbPath(env?: Env): string;
+export declare function beamOptimizationsEnabled(env?: Env): boolean;
+export declare function embeddingModel(env?: Env): string;
+export declare function embeddingDim(env?: Env): number;
+export declare function embeddingApiKey(env?: Env): string;
+export declare function embeddingApiUrl(env?: Env): string;
+export declare function embeddingsViaApi(env?: Env): boolean;
+export declare function embeddingsDisabled(env?: Env): boolean;
+export declare function isApiEmbeddingModel(model?: string, env?: Env): boolean;
+export declare function apiEmbeddingsAvailable(env?: Env): boolean;
+export declare function workingMemoryMaxItems(env?: Env): number;
+export declare function workingMemoryTtlHours(env?: Env): number;
+export declare function episodicRecallLimit(env?: Env): number;
+export declare function sleepBatchSize(env?: Env): number;
+export declare function scratchpadMaxItems(env?: Env): number;
+export declare function recencyHalflifeHours(env?: Env): number;
+export declare function tier2Days(env?: Env): number;
+export declare function tier3Days(env?: Env): number;
+export declare function tier1Weight(env?: Env): number;
+export declare function tier2Weight(env?: Env): number;
+export declare function tier3Weight(env?: Env): number;
+export declare function degradeBatchSize(env?: Env): number;
+export declare function smartCompressEnabled(env?: Env): boolean;
+export declare function tier3MaxChars(env?: Env): number;
+export declare function statedWeight(env?: Env): number;
+export declare function inferredWeight(env?: Env): number;
+export declare function toolWeight(env?: Env): number;
+export declare function importedWeight(env?: Env): number;
+export declare function unknownWeight(env?: Env): number;
+export declare function veracityWeightOverrides(env?: Env): string[];
+export declare function vecType(env?: Env): VecType;
+export declare function vectorWeight(env?: Env): number;
+export declare function ftsWeight(env?: Env): number;
+export declare function importanceWeight(env?: Env): number;
+export declare function normalizedRecallWeights(vec?: number, fts?: number, importance?: number): readonly [number, number, number];
+export declare function autoMigrateEnabled(env?: Env): boolean;
+export declare function proactiveLinkingEnabled(env?: Env): boolean;
+export declare function polyphonicRecallEnabled(env?: Env): boolean;
+export declare function temporalHalflifeHours(env?: Env): number;
+export declare function enhancedRecallEnabled(env?: Env): boolean;
+export declare function llmEnabled(env?: Env): boolean;
+export declare function llmMaxTokens(env?: Env): number;
+export declare function llmThreads(env?: Env): number;
+export declare function llmContext(env?: Env): number;
+export declare function llmRepo(env?: Env): string;
+export declare function llmFile(env?: Env): string;
+export declare function llmModelFiles(env?: Env): readonly [repo: string, file: string];
+export declare function llmBaseUrl(env?: Env): string;
+export declare function llmApiKey(env?: Env): string;
+export declare function llmModel(env?: Env): string;
+export declare function hostLlmEnabled(env?: Env): boolean;
+export declare function hostLlmProvider(env?: Env): string | undefined;
+export declare function hostLlmModel(env?: Env): string | undefined;
+export declare function hostLlmContext(env?: Env): number;
+export declare function sleepPrompt(env?: Env): string;

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

@@ -0,0 +1,55 @@
+export declare const CATEGORY_MAP: {
+    readonly PREFERENCE: "PREF";
+    readonly TRAIT: "TRAIT";
+    readonly STATUS: "STAT";
+    readonly INSTRUCTION: "INST";
+    readonly PROJECT: "PROJ";
+    readonly LOCATION: "LOC";
+    readonly FAMILY: "FAM";
+    readonly OCCUPATION: "OCC";
+    readonly DECISION: "DEC";
+    readonly EVENT: "EVT";
+    readonly TOOL: "TOOL";
+    readonly FACT: "FACT";
+    readonly OPINION: "OPN";
+};
+export declare const PHRASE_MAP: {
+    readonly "User asked ": "ASK ";
+    readonly "User wants ": "WANT ";
+    readonly "User prefers ": "PREF ";
+    readonly "User likes ": "LIKE ";
+    readonly "User dislikes ": "DISLIKE ";
+    readonly "User is ": "IS ";
+    readonly "User has ": "HAS ";
+    readonly "User built ": "BUILT ";
+    readonly "User asked for ": "ASK ";
+    readonly "User requested ": "REQ ";
+    readonly "Married to ": "MARRIED→";
+    readonly "Email: ": "@";
+    readonly "GitHub: ": "GH:";
+    readonly "Location: ": "LOC:";
+    readonly "Phone: ": "PH:";
+    readonly "User email is ": "@";
+    readonly "User voice message ": "VM ";
+    readonly "User stack: ": "STACK|";
+    readonly "Full-stack developer": "FSDEV";
+    readonly "Software Developer": "SDEV";
+    readonly "AI Systems Engineer": "AIENG";
+    readonly "real-time": "RT";
+    readonly "Real-time": "RT";
+    readonly bilingual: "bi";
+    readonly Bilingual: "bi";
+    readonly "self-hosted": "selfhost";
+    readonly automation: "auto";
+    readonly transcription: "transc";
+    readonly translation: "transl";
+};
+export declare const STRUCTURAL_REPLACEMENTS: readonly (readonly [pattern: string, replacement: string])[];
+export declare const REV_CATEGORY: Record<"DEC" | "EVT" | "FACT" | "FAM" | "INST" | "LOC" | "OCC" | "OPN" | "PREF" | "PROJ" | "STAT" | "TOOL" | "TRAIT", "DECISION" | "EVENT" | "FACT" | "FAMILY" | "INSTRUCTION" | "LOCATION" | "OCCUPATION" | "OPINION" | "PREFERENCE" | "PROJECT" | "STATUS" | "TOOL" | "TRAIT">;
+export declare const REV_PHRASE: Record<"@" | "AIENG" | "ASK " | "BUILT " | "DISLIKE " | "FSDEV" | "GH:" | "HAS " | "IS " | "LIKE " | "LOC:" | "MARRIED→" | "PH:" | "PREF " | "REQ " | "RT" | "SDEV" | "STACK|" | "VM " | "WANT " | "auto" | "bi" | "selfhost" | "transc" | "transl", "AI Systems Engineer" | "Bilingual" | "Email: " | "Full-stack developer" | "GitHub: " | "Location: " | "Married to " | "Phone: " | "Real-time" | "Software Developer" | "User asked " | "User asked for " | "User built " | "User dislikes " | "User email is " | "User has " | "User is " | "User likes " | "User prefers " | "User requested " | "User stack: " | "User voice message " | "User wants " | "automation" | "bilingual" | "real-time" | "self-hosted" | "transcription" | "translation">;
+export declare function applyCategoryPrefixes(text: string): string;
+export declare function applyPhrases(text: string): string;
+export declare function applyStructural(text: string): string;
+export declare function compactParens(text: string): string;
+export declare function encode(text: string): string;
+export declare const aaakEncode: typeof encode;

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

@@ -0,0 +1,75 @@
+import type { Database } from "bun:sqlite";
+declare const ANNOTATION_KIND_VALUES: readonly ["mentions", "fact", "occurred_on", "has_source"];
+export type AnnotationKind = (typeof ANNOTATION_KIND_VALUES)[number] | (string & {});
+export declare const ENTITY_STOP_WORDS: ReadonlySet<string>;
+export declare const ANNOTATION_KINDS: ReadonlySet<string>;
+export declare const MIN_FACT_LENGTH = 10;
+export interface AnnotationRow {
+    readonly id: number;
+    readonly memory_id: string;
+    readonly kind: string;
+    readonly value: string;
+    readonly source: string | null;
+    readonly confidence: number | null;
+    readonly created_at: string | null;
+}
+export interface AnnotationInput {
+    readonly id?: number | bigint | null;
+    readonly memory_id: string;
+    readonly kind: string;
+    readonly value: string;
+    readonly source?: string | null;
+    readonly confidence?: number | null;
+    readonly created_at?: string | null;
+}
+export interface AnnotationImportStats {
+    inserted: number;
+    skipped: number;
+    overwritten: number;
+    imported_renumbered: number;
+}
+export interface AnnotationStoreOptions {
+    readonly dbPath?: string;
+    readonly db_path?: string;
+    readonly db?: Database;
+    readonly conn?: Database;
+}
+export declare function filterCleanMentions<T extends {
+    readonly value?: string | null;
+}>(rows: readonly T[]): T[];
+export declare function filterFacts(facts: readonly string[] | null | undefined): string[];
+export declare function initAnnotations(path?: string): void;
+export declare function initAnnotationsWithConn(db: Database): void;
+export declare class AnnotationStore {
+    readonly dbPath: string;
+    readonly db: Database;
+    readonly conn: Database;
+    private readonly ownsConnection;
+    constructor(options?: AnnotationStoreOptions | string);
+    close(): void;
+    add(memoryId: string, kind: string, value: string, source?: string, confidence?: number): number;
+    addMany(memoryId: string, kind: string, values: readonly string[] | null | undefined, source?: string, confidence?: number): number;
+    queryByMemory(memoryId: string, kind?: string | null): AnnotationRow[];
+    queryByKind(kind: string, options?: {
+        readonly value?: string | null;
+        readonly memory_id?: string | null;
+        readonly memoryId?: string | null;
+        readonly filter_noise?: boolean;
+        readonly filterNoise?: boolean;
+    }): AnnotationRow[];
+    getDistinctValues(kind: string): string[];
+    exportAll(): AnnotationRow[];
+    importAll(annotations: readonly AnnotationInput[], force?: boolean): AnnotationImportStats;
+}
+export declare function addAnnotation(memoryId: string, kind: string, value: string, source?: string, confidence?: number, path?: string): number;
+export interface QueryAnnotationsOptions {
+    readonly memory_id?: string | null;
+    readonly memoryId?: string | null;
+    readonly kind?: string | null;
+    readonly value?: string | null;
+    readonly db_path?: string | null;
+    readonly dbPath?: string | null;
+}
+export declare function queryAnnotations(options?: QueryAnnotationsOptions): AnnotationRow[];
+export declare function queryAnnotations(memoryId?: string | null, kind?: string | null, value?: string | null, dbPath?: string | null): AnnotationRow[];
+export {};

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

@@ -0,0 +1,33 @@
+export declare const DEFAULT_DATA_DIR: string;
+export declare const BANKS_DIR: string;
+export declare class ValueError extends Error {
+    name: string;
+}
+export interface BankStats {
+    readonly name: string;
+    readonly exists: boolean;
+    readonly db_path: string;
+    readonly dbSizeBytes: number;
+    readonly db_size_bytes: number;
+}
+export declare class BankManager {
+    readonly dataDir: string;
+    readonly banksDir: string;
+    constructor(dataDir?: string);
+    createBank(name: string): string;
+    deleteBank(name: string, force?: boolean): boolean;
+    listBanks(): string[];
+    bankExists(name: string): boolean;
+    getBankDbPath(name: string): string;
+    renameBank(oldName: string, newName: string): string;
+    getBankStats(name: string): BankStats;
+    private validateName;
+}
+export declare function createBank(name: string, dataDir?: string): string;
+export declare function deleteBank(name: string, dataDir?: string, force?: boolean): boolean;
+export declare function listBanks(dataDir?: string): string[];
+export declare function bankExists(name: string, dataDir?: string): boolean;
+export declare function bankDbPath(name?: string, dataDir?: string): string;
+export declare function setBank(bank: string): void;
+export declare function getBank(): string;
+export declare function resetBankForTests(): void;

package/dist/types/core/beam/consolidate.d.ts

@@ -0,0 +1,32 @@
+import type { BeamMemoryState, BeamStats, JsonValue, MemoriaRetrieveResult, Metadata, SleepResult } from "./types";
+type Row = Record<string, unknown>;
+type FactCounts = {
+    metric: number;
+    date: number;
+    version: number;
+    entity: number;
+    sequence: number;
+    timeline: number;
+    negation: number;
+    decision: number;
+};
+type ConsolidateOptions = {
+    metadata?: Metadata | null;
+    validUntil?: string | null;
+    scope?: string;
+    veracity?: string | null;
+};
+export declare function consolidateToEpisodic(beam: BeamMemoryState, summary: string, sourceWmIds: readonly string[], source?: string, importance?: number, options?: ConsolidateOptions): string;
+export declare function detectLanguage(_beam: BeamMemoryState, text: string): string;
+export declare function storeFactStrings(beam: BeamMemoryState, facts: readonly string[], messageIdx?: number, sourceMemoryId?: string | null, importance?: number): number;
+export declare function extractAndStoreFacts(beam: BeamMemoryState, content: string, messageIdx?: number, sourceMemoryId?: string | null): FactCounts;
+export declare function memoriaRetrieve(beam: BeamMemoryState, query: string, ability?: string | null, topK?: number): MemoriaRetrieveResult;
+export declare function getEpisodicStats(beam: BeamMemoryState, authorId?: string | null, authorType?: string | null, channelId?: string | null): BeamStats;
+export declare function getMemoriaStats(beam: BeamMemoryState): BeamStats;
+export declare function degradeEpisodic(beam: BeamMemoryState, dryRun?: boolean): Record<string, JsonValue>;
+export declare function getContaminated(beam: BeamMemoryState, limit?: number, minImportance?: number): Row[];
+export declare function health(beam: BeamMemoryState, staleThresholdHours?: number): Record<string, JsonValue | Record<string, JsonValue>>;
+export declare function sleep(beam: BeamMemoryState, dryRun?: boolean): SleepResult;
+export declare function sleepAllSessions(beam: BeamMemoryState, dryRun?: boolean): SleepResult;
+export declare function getConsolidationLog(beam: BeamMemoryState, limit?: number): Row[];
+export {};

package/dist/types/core/beam/helpers.d.ts

@@ -0,0 +1,59 @@
+import type { Database } from "bun:sqlite";
+import { sha256Hex16 } from "../../util/ids";
+import type { BeamMemoryState, Metadata } from "./types";
+export type Vector = number[];
+export type HybridWeights = readonly [vecWeight: number, ftsWeight: number, importanceWeight: number];
+export interface VectorDistanceResult {
+    rowid: number;
+    distance: number;
+}
+export interface WorkingVectorResult {
+    id: string;
+    sim: number;
+}
+export interface FtsRankResult {
+    rowid: number;
+    rank: number;
+}
+export interface WorkingFtsRankResult {
+    id: string;
+    rank: number;
+}
+export declare function generateId(content: string, now?: Date): string;
+export declare function generateStableId(content: string, source?: string): string;
+export declare function normalizeWeights(vecWeight: number | null | undefined, ftsWeight: number | null | undefined, importanceWeight: number | null | undefined): HybridWeights;
+export declare function normalizeImportance(importance: number | null | undefined, fallback?: number): number;
+export declare function normalizeDateUtc(dt: Date): Date;
+export declare function parseIsoDateTimeUtc(value: string): Date;
+export declare function parseQueryTime(queryTime?: string | Date | null): Date;
+export declare function parseTimestampFast(ts: string | null | undefined, beam?: Pick<BeamMemoryState, "caches"> | null): Date | null;
+export declare function recencyDecay(timestamp: string | null | undefined, halflifeHours?: number, now?: Date): number;
+export declare function temporalBoost(memoryTimestamp: string | null | undefined, queryTime: Date | string, halflifeHours?: number, beam?: Pick<BeamMemoryState, "caches"> | null): number;
+export declare function recallTokens(text: string): string[];
+export declare function expandedQueryTokens(tokens: readonly string[]): string[];
+export declare function minimumRecallRelevance(queryTokens: readonly string[]): number;
+export declare function factMatchTokens(text: string): Set<string>;
+export declare function containsSpacelessCjk(text: string): boolean;
+export declare function hasCjk(text: string): boolean;
+export declare function cjkFtsTerms(text: string): string[];
+export declare function lexicalRelevance(queryTokens: readonly string[], content: string, queryLower?: string): number;
+export declare function strictFactMatches(query: string, factText: string): boolean;
+export declare function ftsQueryTerms(query: string): string[];
+export declare function buildFtsQuery(query: string): string;
+export declare function cjkLikeSearch(db: Database, query: string, k?: number, working?: boolean): Array<FtsRankResult | WorkingFtsRankResult>;
+export declare function ftsSearch(db: Database, query: string, k?: number): FtsRankResult[];
+export declare function ftsSearchWorking(db: Database, query: string, k?: number): WorkingFtsRankResult[];
+export declare function encodeVector(embedding: readonly number[]): string;
+export declare function decodeVector(value: string | null | undefined): Vector | null;
+export declare function vecAvailable(db: Database): boolean;
+export declare function effectiveVecType(db: Database): "float32" | "int8" | "bit";
+export declare function vecInsert(db: Database, rowid: number, embedding: readonly number[]): void;
+export declare function vecSearch(db: Database, embedding: readonly number[], k?: number): VectorDistanceResult[];
+export declare function inMemoryVecSearch(db: Database, queryEmbedding: readonly number[], k?: number): VectorDistanceResult[];
+export declare function workingMemoryVecSearch(db: Database, queryEmbedding: readonly number[], k?: number, now?: Date): WorkingVectorResult[];
+export declare function normalizeMetadata(input: unknown): Metadata;
+export declare function metadataJson(input: unknown): string;
+export declare function detectLanguage(text: string): string;
+export declare function memoryRowMetadata(row: unknown): Metadata;
+export { cosineSimilarity, hammingDistance, informationTheoreticScore, maximallyInformativeBinarization, quantizeInt8, } from "../binary-vectors";
+export { sha256Hex16 };

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

@@ -0,0 +1,59 @@
+import type { Database } from "bun:sqlite";
+import type { BeamCaches, BeamConfig, BeamEvent, BeamMemoryOptions, BeamMemoryState, BeamStats, ImportStats, MemoriaRetrieveResult, Metadata, RecallEnhancedOptions, RecallOptions, RecallResult, RememberBatchItem, RememberBatchOptions, RememberOptions, SleepResult } from "./types";
+export { initBeam } from "./schema";
+export type * from "./types";
+export declare class BeamMemory implements BeamMemoryState {
+    #private;
+    readonly db: Database;
+    readonly dbPath?: string;
+    readonly sessionId: string;
+    readonly authorId: string | null;
+    readonly authorType: string | null;
+    readonly channelId: string;
+    readonly useCloud: boolean;
+    readonly eventEmitter?: (event: BeamEvent) => void;
+    readonly pluginManager: BeamMemoryState["pluginManager"];
+    readonly annotations: BeamMemoryState["annotations"];
+    readonly triples: BeamMemoryState["triples"];
+    readonly episodicGraph: unknown | null;
+    readonly veracityConsolidator: unknown | null;
+    readonly caches: BeamCaches;
+    readonly config: BeamConfig;
+    readonly pendingExtractions: Set<Promise<void>>;
+    constructor(options?: BeamMemoryOptions);
+    constructor(sessionId?: string, dbPath?: string, authorId?: string | null, authorType?: string | null, channelId?: string | null, useCloud?: boolean, eventEmitter?: (event: BeamEvent) => void);
+    close(): void;
+    flushExtractions(): Promise<void>;
+    remember(content: string, options?: RememberOptions): string;
+    rememberBatch(items: readonly RememberBatchItem[], options?: RememberBatchOptions): string[];
+    getContext(limit?: number): unknown[];
+    invalidate(memoryId: string, replacementId?: string | null): boolean;
+    getWorkingStats(authorId?: string | null, authorType?: string | null, channelId?: string | null): BeamStats;
+    getGlobalWorkingStats(): BeamStats;
+    updateWorking(memoryId: string, content?: string | null, importance?: number | null): boolean;
+    get(memoryId: string): unknown | null;
+    forgetWorking(memoryId: string): boolean;
+    consolidateToEpisodic(summary: string, sourceWmIds: readonly string[], source?: string, importance?: number): string;
+    detectLanguage(text: string): string;
+    extractAndStoreFacts(content: string, messageIdx?: number, sourceMemoryId?: string | null): Record<string, unknown>;
+    memoriaRetrieve(query: string, ability?: string | null, topK?: number): MemoriaRetrieveResult;
+    recall(query: string, topK?: number, options?: RecallOptions): RecallResult[];
+    recallEnhanced(query: string, topK?: number, options?: RecallEnhancedOptions): RecallResult[];
+    formatContext(results: readonly RecallResult[], format?: string): string;
+    factRecall(query: string, topK?: number): RecallResult[];
+    getEpisodicStats(authorId?: string | null, authorType?: string | null, channelId?: string | null): BeamStats;
+    getMemoriaStats(): BeamStats;
+    scratchpadWrite(content: string): string;
+    scratchpadRead(): unknown[];
+    scratchpadClear(): void;
+    degradeEpisodic(dryRun?: boolean): Record<string, unknown>;
+    getContaminated(limit?: number, minImportance?: number): unknown[];
+    health(staleThresholdHours?: number): Record<string, unknown>;
+    sleep(dryRun?: boolean): SleepResult;
+    sleepAllSessions(dryRun?: boolean): SleepResult;
+    getConsolidationLog(limit?: number): unknown[];
+    exportToDict(): Record<string, unknown>;
+    importFromDict(data: Record<string, unknown>, force?: boolean): ImportStats;
+    protected emitEvent(type: string, data?: Omit<BeamEvent, "type" | "sessionId" | "timestamp">): void;
+    protected metadataJson(metadata: Metadata | null | undefined): string | null;
+}

package/dist/types/core/beam/recall.d.ts

@@ -0,0 +1,32 @@
+import type { BeamMemoryState, RecallEnhancedOptions, RecallOptions, RecallResult } from "./types";
+type RecallOptionsInternal = RecallOptions & {
+    source?: string | null;
+    topic?: string | null;
+    veracity?: string | null;
+    memoryType?: string | null;
+    temporalWeight?: number;
+    temporalHalflife?: number;
+    vecWeight?: number;
+    ftsWeight?: number;
+    importanceWeight?: number;
+    queryEmbedding?: readonly number[] | null;
+    useSynonyms?: boolean;
+    useIntent?: boolean;
+    useMmr?: boolean;
+    mmrLambda?: number;
+    ignoreSessionScope?: boolean;
+    currentSensitive?: boolean;
+    updateRecallCounts?: boolean;
+};
+type FactRecallResult = RecallResult & {
+    fact_id?: string;
+    subject?: string;
+    predicate?: string;
+};
+export declare function parseQueryTime(value: RecallOptionsInternal["queryTime"]): Date;
+export declare function temporalBoost(timestamp: unknown, queryTime: Date, halfLifeHours: number): number;
+export declare function recall(beam: BeamMemoryState, query: string, topK?: number, options?: RecallOptionsInternal): RecallResult[];
+export declare function recallEnhanced(beam: BeamMemoryState, query: string, topK?: number, options?: RecallEnhancedOptions & RecallOptionsInternal): RecallResult[];
+export declare function formatContext(beam: BeamMemoryState, results: readonly RecallResult[], format?: string): string;
+export declare function factRecall(beam: BeamMemoryState, query: string, topK?: number): FactRecallResult[];
+export {};

package/dist/types/core/beam/schema.d.ts

@@ -0,0 +1,2 @@
+import type { Database } from "bun:sqlite";
+export declare function initBeam(db: Database): void;

package/dist/types/core/beam/store.d.ts

@@ -0,0 +1,35 @@
+import type { BeamMemoryState, BeamStats, ImportStats, RememberBatchItem, RememberBatchOptions, RememberOptions } from "./types";
+type Row = Record<string, unknown>;
+type StoreRememberOptions = RememberOptions & {
+    memoryId?: string;
+    memory_id?: string;
+    validUntil?: string | null;
+    valid_until?: string | null;
+    authorId?: string | null;
+    author_id?: string | null;
+    authorType?: string | null;
+    author_type?: string | null;
+    extractEntities?: boolean;
+    extract_entities?: boolean;
+    channelId?: string | null;
+    channel_id?: string | null;
+};
+type StoreRememberBatchOptions = RememberBatchOptions & {
+    forceVeracity?: boolean;
+    force_veracity?: boolean;
+};
+export declare function remember(beam: BeamMemoryState, content: string, options?: StoreRememberOptions): string;
+export declare function rememberBatch(beam: BeamMemoryState, items: readonly RememberBatchItem[], options?: StoreRememberBatchOptions): string[];
+export declare function getContext(beam: BeamMemoryState, limit?: number): Row[];
+export declare function invalidate(beam: BeamMemoryState, memoryId: string, replacementId?: string | null): boolean;
+export declare function getWorkingStats(beam: BeamMemoryState, authorId?: string | null, authorType?: string | null, channelId?: string | null): BeamStats;
+export declare function getGlobalWorkingStats(beam: BeamMemoryState): BeamStats;
+export declare function updateWorking(beam: BeamMemoryState, memoryId: string, content?: string | null, importance?: number | null): boolean;
+export declare function get(beam: BeamMemoryState, memoryId: string): Row | null;
+export declare function forgetWorking(beam: BeamMemoryState, memoryId: string): boolean;
+export declare function scratchpadWrite(beam: BeamMemoryState, content: string): string;
+export declare function scratchpadRead(beam: BeamMemoryState): Row[];
+export declare function scratchpadClear(beam: BeamMemoryState): void;
+export declare function exportToDict(beam: BeamMemoryState): Record<string, unknown>;
+export declare function importFromDict(beam: BeamMemoryState, data: Record<string, unknown>, force?: boolean): ImportStats;
+export {};