@linxiraos/pi-mnemopi 1.0.0

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,38 @@
+import { type ExtractedFactCategories } from "../extraction.js";
+import type { BeamMemoryState, BeamStats, JsonValue, MemoriaRetrieveResult, Metadata, SleepResult } from "./types.js";
+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;
+type StoreFactStringOptions = {
+    routeHeuristicCategories?: boolean;
+};
+export declare function storeFactStrings(beam: BeamMemoryState, facts: readonly string[], messageIdx?: number, sourceMemoryId?: string | null, importance?: number, options?: StoreFactStringOptions): number;
+/** Store category-preserving LLM extraction output in MEMORIA and KG tables. */
+export declare function storeExtractedFactCategories(beam: BeamMemoryState, extracted: ExtractedFactCategories, 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,69 @@
+import type { Database } from "bun:sqlite";
+import { sha256Hex16 } from "../../util/ids.js";
+import { cjkFtsTerms, containsSpacelessCjk, ftsQueryTerms, recallTokens } from "../../util/regex.js";
+import type { BeamMemoryState, Metadata } from "./types.js";
+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 lexicalRelevance(queryTokens: readonly string[], content: string, queryLower?: string): number;
+export declare function strictFactMatches(query: string, factText: string): boolean;
+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.js";
+export { cjkFtsTerms, containsSpacelessCjk, ftsQueryTerms, recallTokens, sha256Hex16 };
+/** Identifies one freshly stored memory whose embedding still needs to be derived. */
+export interface EmbedItem {
+    readonly memoryId: string;
+    readonly content: string;
+}
+/**
+ * Schedule background embedding generation for one or more freshly stored memories.
+ *
+ * Mirrors the `scheduleFactExtraction` pattern in `beam/store.ts`: `remember()`,
+ * `rememberBatch()`, and `consolidateToEpisodic()` are synchronous, but `embed()` is
+ * async (it may hit an HTTP provider), so the task is fired-and-forgotten and tracked
+ * on `beam.pendingExtractions` so tests and graceful shutdown can drain it via
+ * `flushExtractions()`. The active runtime options (provider, model, API URL/key) are
+ * captured here and re-entered inside the task because the `AsyncLocalStorage` scope
+ * set by `Mnemopi.#withRuntimeOptions` has already exited by the time the task runs.
+ */
+export declare function scheduleEmbedding(beam: BeamMemoryState, items: readonly EmbedItem[]): void;

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.js";
+export { initBeam } from "./schema.js";
+export type * from "./types.js";
+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): Promise<RecallResult[]>;
+    recallEnhanced(query: string, topK?: number, options?: RecallEnhancedOptions): Promise<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,52 @@
+import type { BeamMemoryState, RecallEnhancedOptions, RecallOptions, RecallResult } from "./types.js";
+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;
+};
+/**
+ * Default per-result content preview cap enforced by {@link recall}. Content
+ * longer than this is clipped and the last character replaced with `…` so
+ * callers see the truncation; the full row remains reachable via
+ * `Mnemopi.get()` (and, in the coding-agent, `memory://<id>`). Overridable per
+ * call via {@link RecallOptions.contentPreviewChars}.
+ */
+export declare const RECALL_CONTENT_PREVIEW_CHARS = 500;
+/**
+ * Clip `content` to at most `limit` characters, replacing the tail with `…`
+ * when truncated so agents can distinguish a preview from a full row. Returns
+ * the original string (and `truncated: false`) when the limit is 0/negative or
+ * the content already fits. The single `…` occupies one character of the cap,
+ * so a 500-char cap yields at most 499 real characters plus the marker.
+ */
+export declare function clipRecallContent(content: string, limit?: number): {
+    content: string;
+    truncated: boolean;
+    fullLength: number;
+};
+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): Promise<RecallResult[]>;
+export declare function recallEnhanced(beam: BeamMemoryState, query: string, topK?: number, options?: RecallEnhancedOptions & RecallOptionsInternal): Promise<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,57 @@
+import type { BeamMemoryState, BeamStats, ImportStats, RememberBatchItem, RememberBatchOptions, RememberOptions } from "./types.js";
+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;
+    extract_text?: string;
+    embed_text?: string;
+    channelId?: string | null;
+    channel_id?: string | null;
+};
+type StoreRememberBatchOptions = RememberBatchOptions & {
+    forceVeracity?: boolean;
+    force_veracity?: boolean;
+};
+/**
+ * Reconcile stored embeddings against the active embedding model at store open.
+ *
+ * Every `memory_embeddings` row is stamped with the model that produced it (see
+ * `runEmbedding` in `helpers.ts`). When the configured embedding model changes,
+ * its vector dimension changes too, so the previously-stored vectors are no
+ * longer comparable. On a mismatch we wipe every stored vector — the
+ * `memory_embeddings` table, the `episodic_memory.binary_vector` column, and the
+ * sqlite-vec `vec_episodes` index — then enqueue all live memories for
+ * background re-embedding under the new model via `scheduleEmbedding`.
+ *
+ * Runs once per store open; a fresh store (no embeddings) or an already-current
+ * store is a no-op. The destructive wipe is skipped whenever it could not be
+ * rebuilt — embeddings disabled via the runtime option OR the
+ * `MNEMOPI_NO_EMBEDDINGS` env, or an unresolved (empty) active model — so a
+ * stale-but-valid corpus is never destroyed without a replacement. MUST run
+ * inside the active runtime-options scope so `currentEmbeddingModel()` /
+ * `embeddingsDisabled()` reflect the per-instance configuration.
+ */
+export declare function reconcileEmbeddingModel(beam: BeamMemoryState): void;
+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 {};

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

@@ -0,0 +1,268 @@
+import type { Database } from "bun:sqlite";
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type Metadata = Record<string, JsonValue>;
+export type MemoryScope = "global" | "session" | "channel" | string;
+export type TrustTier = "STATED" | "OBSERVED" | "INFERRED" | "SYSTEM" | string;
+export type Veracity = "unknown" | "likely_true" | "true" | "false" | "stated" | "inferred" | "tool" | "imported" | "contested" | string;
+export interface BeamPluginManager {
+    emit?(event: BeamEvent): void | Promise<void>;
+    close?(): void | Promise<void>;
+}
+export interface AnnotationStoreLike {
+    add?(memoryId: string, kind: string, value: string, options?: AnnotationWriteOptions): unknown;
+    addMany?(memoryId: string, kind: string, values: readonly string[], options?: AnnotationWriteOptions): unknown;
+    queryByMemory?(memoryId: string, kind?: string): unknown;
+    queryByKind?(kind: string, value?: string): unknown;
+    getDistinctValues?(kind: string): string[];
+}
+export interface TripleStoreLike {
+    add?(subject: string, predicate: string, object: string, options?: TripleWriteOptions): unknown;
+    query?(subject?: string, predicate?: string, asOf?: string): unknown;
+}
+export interface BeamCaches {
+    timestampParse: Map<string, Date>;
+    polyphonicEngine?: unknown;
+    extractionClient?: unknown;
+    extractionBuffer: unknown[];
+    [key: string]: unknown;
+}
+export interface BeamConfig {
+    workingMemoryLimit: number;
+    workingMemoryTtlHours: number;
+    recencyHalflifeHours: number;
+    vecWeight: number;
+    ftsWeight: number;
+    importanceWeight: number;
+    useCloud: boolean;
+    localLlmEnabled: boolean;
+    maxEpisodeChars: number;
+    proactiveLinking?: boolean;
+}
+export interface BeamMemoryOptions {
+    sessionId?: string;
+    dbPath?: string;
+    authorId?: string | null;
+    authorType?: string | null;
+    channelId?: string | null;
+    useCloud?: boolean;
+    proactiveLinking?: boolean;
+    eventEmitter?: (event: BeamEvent) => void;
+    pluginManager?: BeamPluginManager | null;
+    annotations?: AnnotationStoreLike | null;
+    triples?: TripleStoreLike | null;
+    config?: Partial<BeamConfig>;
+}
+export interface BeamMemoryState {
+    db: Database;
+    dbPath?: string;
+    sessionId: string;
+    authorId: string | null;
+    authorType: string | null;
+    channelId: string;
+    useCloud: boolean;
+    eventEmitter?: (event: BeamEvent) => void;
+    pluginManager: BeamPluginManager | null;
+    annotations: AnnotationStoreLike | null;
+    triples: TripleStoreLike | null;
+    episodicGraph: unknown | null;
+    veracityConsolidator: unknown | null;
+    caches: BeamCaches;
+    config: BeamConfig;
+    /** Tracks in-flight background fact-extraction tasks scheduled by `remember(..., { extract: true })`. */
+    pendingExtractions?: Set<Promise<void>>;
+}
+export interface AnnotationWriteOptions {
+    source?: string;
+    confidence?: number;
+}
+export interface TripleWriteOptions {
+    validFrom?: string;
+    source?: string;
+    confidence?: number;
+}
+export interface BeamEvent {
+    type: string;
+    memoryId?: string;
+    content?: string;
+    source?: string;
+    importance?: number;
+    sessionId: string;
+    timestamp: string;
+    metadata?: Metadata;
+}
+export interface RememberOptions {
+    source?: string;
+    importance?: number;
+    metadata?: Metadata | null;
+    extract?: boolean;
+    extractEntities?: boolean;
+    /**
+     * Override the text passed to fact and graph extraction. When unset
+     * (default) extraction runs over the stored `content`. Use this when the
+     * stored memory is a multi-author transcript but only a subset (e.g. the
+     * user-authored turns) should drive deterministic fact extraction — see
+     * coding-agent issue #3372 where assistant prose was being mis-attributed
+     * as user `Instruction:` memories.
+     */
+    extractText?: string;
+    /**
+     * Override the text passed to embeddings and FTS indexing. Stored `content`
+     * remains unchanged; when unset, embeddings and FTS use `content`.
+     */
+    embedText?: string;
+    veracity?: Veracity;
+    memoryType?: string;
+    scope?: MemoryScope;
+    trustTier?: TrustTier;
+    timestamp?: string;
+}
+export interface RememberBatchOptions {
+    extract?: boolean;
+    extractEntities?: boolean;
+    veracity?: Veracity;
+    memoryType?: string;
+    scope?: MemoryScope;
+    trustTier?: TrustTier;
+}
+export interface RememberBatchItem extends RememberOptions {
+    content: string;
+}
+export interface RecallOptions {
+    fromDate?: string | null;
+    toDate?: string | null;
+    authorId?: string | null;
+    authorType?: string | null;
+    channelId?: string | null;
+    includeWorking?: boolean;
+    queryTime?: string | Date | null;
+    temporalWeight?: number;
+    temporalHalflife?: number;
+    vecWeight?: number;
+    ftsWeight?: number;
+    importanceWeight?: number;
+    queryEmbedding?: readonly number[] | null;
+    useSynonyms?: boolean;
+    useIntent?: boolean;
+    useMmr?: boolean;
+    mmrLambda?: number;
+    /**
+     * Maximum characters of `content` returned per {@link RecallResult}. When the
+     * stored content exceeds this, the preview is clipped and the trailing
+     * character is replaced with `…` so callers can see it was truncated. The
+     * full row is always reachable via {@link BeamMemoryState.get}. `0` or a
+     * negative value disables clipping. Defaults to
+     * {@link RECALL_CONTENT_PREVIEW_CHARS} (500).
+     */
+    contentPreviewChars?: number;
+}
+export interface RecallEnhancedOptions extends RecallOptions {
+    useCache?: boolean;
+    includeFacts?: boolean;
+}
+export interface MemoryRow {
+    id: string;
+    content: string;
+    source: string | null;
+    timestamp: string | null;
+    session_id: string;
+    importance: number;
+    metadata_json: string | null;
+    veracity: Veracity;
+    memory_type?: string | null;
+    recall_count?: number;
+    last_recalled?: string | null;
+    valid_until?: string | null;
+    superseded_by?: string | null;
+    scope?: MemoryScope;
+    author_id?: string | null;
+    author_type?: string | null;
+    channel_id?: string | null;
+    trust_tier?: TrustTier;
+    validator?: string | null;
+    validated_at?: string | null;
+    validation_count?: number;
+    event_date?: string | null;
+    event_date_precision?: string | null;
+    temporal_tags?: string | null;
+    corrected_by?: number | null;
+    created_at: string;
+}
+export interface WorkingMemoryRow extends MemoryRow {
+    consolidated_at?: string | null;
+}
+export interface EpisodicMemoryRow extends MemoryRow {
+    rowid: number;
+    summary_of: string;
+    tier: number;
+    degraded_at?: string | null;
+    binary_vector?: Uint8Array | null;
+}
+export type RecallTierLabel = "working" | "episodic" | "fact" | string;
+export interface RecallVoiceScores {
+    vec?: number;
+    fts?: number;
+    keyword?: number;
+    importance?: number;
+    recency_decay?: number;
+    temporal?: number;
+    [key: string]: number | undefined;
+}
+type RecallRowFields = Omit<Partial<EpisodicMemoryRow>, "tier"> & Partial<WorkingMemoryRow>;
+export type RecallResult = RecallRowFields & {
+    [key: string]: unknown;
+    id: string;
+    content: string;
+    /**
+     * True when {@link content} is a clipped preview of the stored row. The
+     * clip is capped at {@link RecallOptions.contentPreviewChars} (default 500)
+     * and the last character is replaced with `…`. Fetch the full row via
+     * `memory://<id>` (mnemopi backend) or the `Mnemopi.get(id)` API.
+     */
+    truncated?: boolean;
+    /** Original character count of `content` before {@link truncated} clipping. */
+    full_length?: number;
+    score?: number;
+    distance?: number;
+    rank?: number;
+    tier?: RecallTierLabel;
+    tier_label?: RecallTierLabel;
+    degradation_tier?: number;
+    keyword_score?: number;
+    dense_score?: number;
+    fts_score?: number;
+    importance_score?: number;
+    recency_score?: number;
+    temporal_score?: number;
+    explanation?: string;
+    voice_scores?: RecallVoiceScores;
+    metadata?: Metadata;
+};
+export interface BeamStats {
+    count: number;
+    by_source?: Record<string, number>;
+    by_session?: Record<string, number>;
+    oldest?: string | null;
+    newest?: string | null;
+    [key: string]: JsonValue | Record<string, number> | undefined;
+}
+export interface MemoriaRetrieveResult {
+    ability: string;
+    query: string;
+    results: unknown[];
+}
+export interface SleepResult {
+    dry_run: boolean;
+    sessions?: Record<string, unknown>;
+    items_consolidated?: number;
+    [key: string]: unknown;
+}
+export interface ImportStats {
+    working_memory: Record<string, number>;
+    episodic_memory: Record<string, number>;
+    scratchpad: Record<string, number>;
+    consolidation_log: Record<string, number>;
+}
+export {};

package/dist/types/core/binary-vectors.d.ts

@@ -0,0 +1,54 @@
+import type { Database } from "bun:sqlite";
+import { type VecType } from "../config.js";
+import { type DatabasePath } from "../db.js";
+export { cosineSimilarity } from "./vector-math.js";
+export declare const BITS_PER_BYTE = 8;
+export declare const EMBEDDING_DIM: number;
+export declare const BYTES_PER_VECTOR: number;
+export interface BinaryVectorSearchResult {
+    memory_id: string;
+    distance: number;
+    score: number;
+}
+export interface BinaryVectorStats {
+    total_vectors: number;
+    avg_bytes_per_vector: number;
+    max_bytes: number;
+    min_bytes: number;
+    compression_ratio: number;
+    theoretical_size_mb: number;
+}
+export interface BinaryVectorStoreOptions {
+    dbPath?: DatabasePath;
+    tableName?: string;
+    conn?: Database;
+}
+export declare function getVecType(env?: NodeJS.ProcessEnv): VecType;
+export declare const VEC_TYPE: VecType;
+export declare function quantizeInt8(embedding: readonly number[]): Int8Array;
+export declare function maximallyInformativeBinarization(embedding: readonly number[]): Uint8Array;
+export declare function hammingDistance(binaryA: Uint8Array | ArrayBuffer, binaryB: Uint8Array | ArrayBuffer): number;
+export declare function informationTheoreticScore(distance: number, dim?: number): number;
+export declare class BinaryVectorStore {
+    readonly conn: Database;
+    readonly dbPath: DatabasePath;
+    readonly tableName: string;
+    private readonly ownsConnection;
+    constructor(options?: BinaryVectorStoreOptions);
+    private initTable;
+    static maximallyInformativeBinarization(embedding: readonly number[]): Uint8Array;
+    static hammingDistance(binaryA: Uint8Array | ArrayBuffer, binaryB: Uint8Array | ArrayBuffer): number;
+    static informationTheoreticScore(distance: number, dim?: number): number;
+    storeVector(memoryId: string, embedding: readonly number[]): void;
+    search(queryEmbedding: readonly number[], topK?: number): BinaryVectorSearchResult[];
+    searchBatch(queryEmbeddings: readonly (readonly number[])[], topK?: number): BinaryVectorSearchResult[][];
+    deleteVector(memoryId: string): void;
+    getStats(): BinaryVectorStats;
+    close(): void;
+}
+export declare class FastBinarySearch {
+    private readonly memoryIds;
+    private readonly vectors;
+    constructor(binaryVectors: ReadonlyMap<string, Uint8Array | ArrayBuffer> | Record<string, Uint8Array | ArrayBuffer>);
+    search(queryBinary: Uint8Array | ArrayBuffer, topK?: number): BinaryVectorSearchResult[];
+}

package/dist/types/core/chat-normalize.d.ts

@@ -0,0 +1,13 @@
+type ExtractionRate = {
+    total: number;
+    survived: number;
+    dropped: number;
+    rate: number;
+    dropped_samples: string[];
+};
+export declare function normalizeChat(text: string, options?: {
+    add_implicit_subjects?: boolean;
+}): string | null;
+export declare function normalizeBatch(messages: string[]): (string | null)[];
+export declare function extractionRate(messages: string[]): ExtractionRate;
+export {};

package/dist/types/core/content-sanitizer.d.ts

@@ -0,0 +1,18 @@
+export declare const SIZE_HARD_CAP = 1000000;
+export declare const SIZE_BASE64_CHECK = 100000;
+export declare const ENTROPY_THRESHOLD = 5;
+export interface BlobMetadata {
+    blob_ref?: string;
+    original_size?: number;
+    mime?: string;
+    extraction_reason?: "data_uri" | "size_cap" | "high_entropy";
+    entropy?: number;
+}
+export declare function blobRoot(env?: NodeJS.ProcessEnv): string;
+export declare function computeSha256(data: Uint8Array | string): string;
+export declare function isDataUri(content: string): boolean;
+export declare function parseDataUri(content: string): [mimeType: string, raw: Buffer] | null;
+export declare function shannonEntropy(text: string): number;
+export declare function looksLikeBase64Blob(content: string): boolean;
+export declare function storeBlob(rawBytes: Uint8Array): string;
+export declare function sanitizeContent(content: string): [sanitizedContent: string, blobMetadata: BlobMetadata];