jeopi-mnemopi 16.2.13

package/CHANGELOG.md

@@ -0,0 +1,172 @@
+# Changelog
+
+## [Unreleased]
+
+## [16.2.2] - 2026-06-27
+
+### Fixed
+
+- Improved resilience during API extraction calls by enhancing the handling of rate limits and transient errors.
+
+## [16.1.17] - 2026-06-24
+
+### Fixed
+
+- Fixed `remember(..., { extract: true })` fact/entity extraction accepting an `extractText` override so hosts can store full transcripts while mining facts from a safer projection; also tightened deterministic `Instruction:` extraction to require an explicit `I`/`you` subject instead of treating every `always`/`never` clause as a user instruction. ([#3372](https://github.com/can1357/oh-my-pi/issues/3372))
+
+## [16.1.8] - 2026-06-20
+
+### Fixed
+
+- Capped per-input length in `embed()` at `MNEMOPI_EMBEDDING_MAX_INPUT_CHARS` (default 8192 chars, override via the env var or `embeddings.maxInputChars` runtime option; `0` disables) so a long retention transcript can no longer overflow the embedding model's context window. Oversized inputs are clipped with a head/tail split so chronological transcripts keep both the opening setup and the most recent turns instead of losing the latest content under a naive prefix slice. llama.cpp's `/embeddings` server used to reject the request with `request (N tokens) exceeds the available context size`, silently dropping vector recall for that memory ([#3126](https://github.com/can1357/oh-my-pi/issues/3126)).
+- Fixed the proactive-linking write path ignoring host configuration: `proactiveLinkIfEnabled` read `MNEMOPI_PROACTIVE_LINKING` directly, so a host that enabled proactive linking through `configureRecallFeatures()` had no effect unless the environment variable was also set. `proactiveLinking` is now a `RecallFeatureFlags` option resolved through a `proactiveLinkingEnabled()` fallback, matching the existing polyphonic and enhanced recall flags, with the `MNEMOPI_PROACTIVE_LINKING` environment variable still taking precedence whenever it is set. ([#2440](https://github.com/can1357/oh-my-pi/issues/2440))
+
+## [16.1.3] - 2026-06-19
+
+### Added
+
+- Exposed `setLocalModelInitializer` (and the `LocalEmbeddingModel`, `LocalModelInitializer`, `LocalModelInitOptions`, `StandardEmbeddingModel` types) so hosts can route fastembed loads through a dedicated subprocess and keep `onnxruntime-node`'s NAPI constructor + finalizer out of their own address space. Same wipe semantics as the existing `setLocalModelInitializerForTests` seam; the agent CLI uses it to crash-proof Windows when `memory.backend: mnemopi` is enabled ([#3031](https://github.com/can1357/oh-my-pi/issues/3031)).
+
+### Fixed
+
+- Fixed background fact extraction skipping runtime-configured remote LLM endpoints when `MNEMOPI_LLM_BASE_URL` was unset, so `remember(..., { extract: true })` now stores remote-distilled facts from `mnemopi.llm` config instead of falling back to regex heuristics. ([#3041](https://github.com/can1357/oh-my-pi/issues/3041))
+- Fixed local fastembed startup on macOS ARM64 by letting `fastembed@2.1.0` install its matching `onnxruntime-node@1.21.0` native runtime instead of forcing `1.26.0`, and by repairing missing tokenizer sidecars from the upstream Hugging Face model cache when a stale fastembed archive lacks them. ([#3054](https://github.com/can1357/oh-my-pi/issues/3054))
+
+## [16.0.6] - 2026-06-18
+
+### Fixed
+
+- Forced the on-demand fastembed runtime install to override fastembed's archived `onnxruntime-node@1.21.0` transitive pin with Mnemopi's `onnxruntime-node@1.26.0` pin, fixing local embedding startup on macOS ARM64. ([#2920](https://github.com/can1357/oh-my-pi/issues/2920))
+
+### Changed
+
+- Updated OpenRouter request headers to use standard shared headers from the pi-ai package
+
+## [16.0.5] - 2026-06-17
+
+### Fixed
+
+- Capped `sleep_consolidation` episodic rows at `maxEpisodeChars` (default 100KB, `MNEMOPI_MAX_EPISODE_CHARS`) so raw session transcripts cannot be stored and extracted as multi-megabyte episodes. ([#2869](https://github.com/can1357/oh-my-pi/issues/2869))
+- Skipped regex-only entity and pattern fact extraction for oversized raw transcripts so progress/log noise cannot flood MEMORIA with junk facts. ([#2868](https://github.com/can1357/oh-my-pi/issues/2868))
+
+## [15.13.1] - 2026-06-15
+
+### Added
+
+- Added a wipe-and-rebuild reconcile (`reconcileEmbeddingModel`) that runs when the configured embedding model changes. At store open, if the model stamped on stored `memory_embeddings` rows differs from the active `currentEmbeddingModel()`, the stale embeddings and their binary vectors are dropped and every existing memory is enqueued for background re-embedding (in bounded batches) at the new model/dimension. The destructive wipe is skipped whenever it could not be rebuilt — embeddings disabled via the runtime option or the `MNEMOPI_NO_EMBEDDINGS` env, an unresolved (empty) active model, or a read-only open (`reconcile: false`, used by ephemeral stats readers that would exit before the async rebuild finished) — so a stale-but-valid corpus is never destroyed without a replacement. Recall degrades gracefully (FTS-only) for memories whose vectors are not yet rebuilt ([#2476](https://github.com/can1357/oh-my-pi/issues/2476))
+
+### Fixed
+
+- Normalized enhanced recall fact scoring against lexical coverage so high-confidence facts that only match generic query tokens no longer outrank exact working-memory hits. ([#2441](https://github.com/can1357/oh-my-pi/issues/2441))
+
+## [15.12.4] - 2026-06-13
+
+### Fixed
+
+- Fixed `consolidateToEpisodic` (the function backing `sleep` / `sleepAllSessions`) never populating the episodic graph: the `gists` and `graph_edges` tables stayed at 0 rows across every bank even after multiple consolidation cycles, so Polyphonic Recall's `graph` voice (BFS over `findGistsByParticipant` / `findRelatedMemories`) always returned nothing. Consolidation now best-effort ingests the new episodic memory into `EpisodicGraph` so the gist row, gist→memory `ctx` edge, fact edges, and cross-memory similarity/entity/temporal edges land alongside the episodic row. Independent of the existing `MNEMOPI_PROACTIVE_LINKING` flag, which still gates the same enrichment on the `remember()` write path. ([#2435](https://github.com/can1357/oh-my-pi/issues/2435))
+
+## [15.12.0] - 2026-06-12
+
+### Changed
+
+- Moved `fastembed` and `onnxruntime-node` from `dependencies` to optional `peerDependencies` pinned to exact versions. When the peers are absent (bundled CLI, compiled binary, or installs that skip optional peers), the local embedding path `bun install`s the pinned pair into `~/.omp/cache/fastembed-runtime/<version-key>` on first use and loads fastembed from there — restoring local embeddings in bundled distributions and removing ~270MB of eager native downloads from default installs ([#2389](https://github.com/can1357/oh-my-pi/issues/2389))
+
+## [15.11.4] - 2026-06-12
+
+### Added
+
+- Added `configureRecallFeatures()` (exported from the package root, `core`, and `config`) so hosts can enable the polyphonic recall engine and the enhanced recall query cache programmatically. `polyphonicRecallEnabled()`, `enhancedRecallEnabled()`, and `isEnhancedRecallEnabled()` now fall back to these configured defaults, with the `MNEMOPI_POLYPHONIC_RECALL` / `MNEMOPI_ENHANCED_RECALL` environment variables still taking precedence whenever they are set. ([#2323](https://github.com/can1357/oh-my-pi/issues/2323))
+
+### Fixed
+
+- Fixed the embedding pipeline's silent `catch {}` blocks (`runEmbedding()`, `getLocalModel()`, and the local-model path of `embed()`) swallowing failures with zero diagnostics. These best-effort paths still degrade gracefully (return `null` / skip the write), but now emit structured `logger.debug` entries with the error and per-site context (item count, model name). The `mnemopi.debug` config flag now propagates into the core library via runtime options (`MnemopiOptions.debug` → `ResolvedMnemopiRuntimeOptions.debug`) and escalates these logs to `warn` so they surface at the default log level. ([#2322](https://github.com/can1357/oh-my-pi/issues/2322))
+
+### Changed
+
+- Extraction, embedding, and remote-LLM clients now accept an `ApiKey` (static string or resolver) and resolve it per request through `withAuth`, so 401s force-refresh and rotate credentials via the central auth-retry policy instead of failing with a stale key. Empty-key setups (local/proxy endpoints without `Authorization`) and pinned literal keys behave exactly as before.
+- Embedding and remote-LLM 401 errors now throw pi-ai's typed `ProviderHttpError` instead of `Object.assign`-patched `Error`s, keeping the same structural `.status` contract for the auth-retry classifier.
+- SHMR consolidation clustering (`core/shmr`) now uses the real embedding provider when one is configured instead of always hashing: `embed()`, the new `embedBatch()`, `clusterBySimilarity()`, `computeHarmonyScore()`, `harmonize()`, and `recallBeliefs()` are now async, batch-embed candidate texts in a single provider call, and reuse precomputed vectors from `memory_embeddings` for episodic candidates. The SHA1 bag-of-words hash remains as the deterministic fallback when no provider is available or embedding fails. ([#2324](https://github.com/can1357/oh-my-pi/issues/2324))
+
+## [15.10.12] - 2026-06-10
+
+### Changed
+
+- Reworked the in-memory fallback vector search to build a normalized exact vector index per query, matching the shape needed for future quantized or TurboVec-style backends without adding a new dependency yet.
+
+## [15.10.11] - 2026-06-10
+
+### Fixed
+
+- Fixed embedding provider detection to match `openrouter` by URL host, so custom embedding endpoints are now recognized correctly instead of being misclassified by substring matching
+- Fixed the check for OpenRouter base URLs so only true `openrouter` hosts are treated as non-custom
+
+## [15.10.8] - 2026-06-09
+
+### Added
+
+- Added a `fetch` option to `ExtractionClient` to inject a custom fetch implementation for remote LLM requests
+- Added an optional `fetch` option to `extractFacts` to control the transport used for remote extraction calls
+- Added support for passing a custom `fetch` implementation through `complete` and `summarizeMemories` via remote LLM options
+
+## [15.9.1] - 2026-06-04
+
+### Breaking Changes
+
+- Changed `Mnemopi.recall()`, `Mnemopi.recallEnhanced()`, `Mnemopi.search()`, `Mnemopi.query()`, the module-level `recall`/`recallEnhanced`/`search`/`query` exports, the `BeamMemory.recall`/`recallEnhanced` methods, the free `recall`/`recallEnhanced` functions in `core/beam/recall`, and `orchestrateRecall` to return `Promise<RecallResult[]>` so the recall pipeline can auto-derive `queryEmbedding` from the query text via `embedQuery`. Callers must `await` recall calls; pass `queryEmbedding: null` to opt out of auto-embedding and stay on FTS-only.
+- Changed the MCP entrypoints `handleToolCall`, `callToolJson`, and `handleJsonRpc` in `mcp-server`/`mcp-tools` to async so the recall/shared-recall handlers can await the new `Promise<ToolResult[]>` shape; external MCP transports must `await` these.
+
+### Fixed
+
+- Fixed `memory_embeddings` never being populated by the production `remember`/`rememberBatch`/`updateWorking`/`consolidateToEpisodic` paths; embedding generation is now scheduled as a background task on `beam.pendingExtractions` (mirroring `scheduleFactExtraction`), so configured providers (fastembed, OpenAI-compatible API, custom) actually run and rows land in `memory_embeddings(memory_id, embedding_json, model)`. ([#1832](https://github.com/can1357/oh-my-pi/issues/1832))
+- Fixed `recall()`/`recallEnhanced()` never deriving a query embedding from the query text, which silently degraded every deployment to FTS-only regardless of provider configuration. The recall pipeline now auto-calls `embedQuery(query)` when `options.queryEmbedding` is undefined; pass `null` to keep the old FTS-only behaviour. ([#1832](https://github.com/can1357/oh-my-pi/issues/1832))
+- Fixed `toRecallOptions` dropping `queryEmbedding` between the `Mnemopi` facade and the beam layer, so callers can now explicitly pin or disable the query vector through the public API.
+- Fixed `withMemory` (CLI) and `withBeam`/`withSharedBeam` (MCP) closing the SQLite handle before background fact-extraction and embedding tasks finished, so short-lived `mnemopi store`/`mnemopi sleep` and MCP `remember`/`update` paths now drain `flushExtractions` before close instead of silently dropping `memory_embeddings` rows. CLI handlers and MCP `handleRemember`/`handleUpdate`/`handleSleep`/etc. are async as a result. ([#1832](https://github.com/can1357/oh-my-pi/issues/1832), follow-up to [#1833](https://github.com/can1357/oh-my-pi/pull/1833) review)
+- Fixed the process-wide `embedQuery()` cache in `core/embeddings.ts` keying by query text alone, which let two `Mnemopi` instances in the same process with different providers/models cross-contaminate their `dense_score` rankings. The cache key now includes a WeakMap-assigned provider identity, the resolved model name, and the configured `apiUrl`, so disjoint runtimes never read each other's cached vectors. ([#1832](https://github.com/can1357/oh-my-pi/issues/1832), follow-up to [#1833](https://github.com/can1357/oh-my-pi/pull/1833) review)
+
+## [15.7.4] - 2026-05-31
+
+### Fixed
+
+- Fixed the `darwin-x64` release build failing in `bun build --compile` because the Windows ORT 1.24 preload pulled `onnxruntime-node` into the static graph and there is no `darwin/x64` prebuilt for that line. The preload is now guarded behind a `process.platform === "win32"` literal that Bun dead-code-eliminates on non-Windows targets; macOS/Linux load fastembed's bundled ORT 1.21 binding as before.
+
+## [15.7.3] - 2026-05-31
+
+### Changed
+
+- Changed embedding result normalization to return `Float32Array` vectors so `embed` and `embedQuery` now cache and emit float32 rows
+- Changed the embedding provider contract to a single typed `EmbeddingOutput` (`AsyncIterable<number[][]>`) instead of `unknown`, matching fastembed's `embed()`, so `EmbeddingProvider.embed` and the `provider` runtime option stream the embedding matrix as async batches (`async *embed(texts) { yield texts.map(embedOne); }`)
+- Changed local model cache directory resolution for `fastembed` to use `getFastembedCacheDir` instead of the hard-coded `~/.hermes/cache/fastembed` path
+
+### Fixed
+
+- Fixed cosine similarity behavior across retrieval, clustering, and caching to consistently handle mismatched vector lengths as zero-padded and ignore non-finite values
+- Fixed embedding API requests to retry transient failures with backoff via shared retry logic before returning null
+- Fixed compiled `omp` binaries losing local Mnemopi embeddings by keeping `fastembed` and `onnxruntime-node` reachable to Bun's static compiler while preserving lazy runtime loading.
+
+## [15.7.2] - 2026-05-31
+
+### Fixed
+
+- Fixed Windows startup crashes by keeping fastembed's older ONNX Runtime binding lazy until local embeddings are used.
+- Fixed a segfault at startup from eagerly loading fastembed: importing the embeddings module pulled in `fastembed`, which eagerly loads the `onnxruntime-node` native addon. The import is now deferred until a local fastembed model is actually initialized, so API-model, disabled-embeddings, and test runtimes never load the native addon.
+
+## [15.6.0] - 2026-05-30
+
+### Added
+
+- Added `llm.extractionPrompt` runtime option to override the fact-extraction prompt template using `{text}` and `{lang}` placeholders
+- Added `llm.consolidationPrompt` runtime option to override the consolidation sleep prompt template using `{memories}`, `{source}`, and `{memory_count}` placeholders
+- Published `jeopi-mnemopi` to npm: the local SQLite memory engine is now built, checked, tested, and released through the monorepo CI pipeline alongside the other workspace packages.
+- Exported the diagnostic inspector as the `jeopi-mnemopi/diagnose` subpath for coding-agent memory maintenance commands.
+- Added `flushExtractions()` (on `Mnemopi`, `BeamMemory`, and as a module-level export) to drain in-flight background fact extraction; used by tests and graceful shutdown so facts are persisted before the database closes.
+
+### Changed
+
+- Changed fact extraction to prefer a configured runtime LLM completion path before host extraction, with automatic fallback when the configured completion returns no output or fails
+
+### Fixed
+
+- Fixed `rememberBatch(..., { extract: true })` to run background fact extraction for batch uploads (including per-item `extract` flags) so extracted facts are generated and recallable after extraction
+- Fixed `extract: true` fact extraction to continue safely when no LLM is configured by turning extraction failures into no-op background tasks
+- Fixed configured LLM fact extraction by using temperature 0 so re-ingesting the same text is deterministic and avoids near-duplicate extractions
+- Fixed `remember(..., { extract: true })` silently dropping the flag: it now schedules the LLM fact extractor (`extractFactsSafe`) over the stored content and persists the extracted facts so they become recallable. Previously the LLM extractor had no production callers and `extract` was dead.

package/README.md

@@ -0,0 +1,107 @@
+# jeopi-mnemopi
+
+Local SQLite memory engine for Oh My Pi agents.
+
+This package is the Bun/TypeScript port of the Mnemosyne memory engine. It provides:
+
+- `Mnemopi`, 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 { Mnemopi } from "jeopi-mnemopi";
+
+const memory = new Mnemopi({ dbPath: "./mnemopi.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
+
+`Mnemopi` accepts LLM and embedding options directly. `MNEMOPI_*` environment variables remain fallbacks/defaults when the matching constructor option is omitted.
+
+```ts
+import { Mnemopi } from "jeopi-mnemopi";
+import type { Model } from "jeopi-ai";
+
+const ftsOnly = new Mnemopi({ noEmbeddings: true });
+
+const remoteEmbeddings = new Mnemopi({
+	embeddingModel: "text-embedding-3-small",
+	embeddingApiUrl: "https://api.openai.com/v1",
+	embeddingApiKey: process.env.OPENAI_API_KEY,
+});
+
+const remoteLlm = new Mnemopi({
+	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 Mnemopi({ llm: smolModel });
+const dynamicLlm = new Mnemopi({
+	llm: async (prompt, opts) => {
+		const token = await getFreshOauthToken();
+		return await completeWithPiAi(prompt, {
+			token,
+			maxTokens: opts?.maxTokens,
+			temperature: opts?.temperature,
+		});
+	},
+});
+```
+
+### Banks and host scoping
+
+`Mnemopi` 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 `mnemopi.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:
+
+- `MNEMOPI_DATA_DIR` / `MNEMOPI_DB_PATH`: default storage location.
+- `MNEMOPI_NO_EMBEDDINGS=1`: force FTS-only recall.
+- `MNEMOPI_EMBEDDING_MODEL`: defaults to `BAAI/bge-small-en-v1.5`.
+- `MNEMOPI_EMBEDDING_API_URL` and `MNEMOPI_EMBEDDING_API_KEY`: OpenAI-compatible embedding endpoint.
+- `MNEMOPI_LLM_ENABLED=1`, `MNEMOPI_LLM_BASE_URL`, `MNEMOPI_LLM_API_KEY`, `MNEMOPI_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
+mnemopi remember "Use stable-cluster for production deploys"
+mnemopi recall "production deploy target"
+mnemopi stats
+mnemopi sleep
+```
+
+## Tests
+
+```sh
+bun --cwd packages/mnemopi test
+bun --cwd packages/mnemopi 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,108 @@
+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 = "mnemopi.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;
+/**
+ * Per-input character cap applied inside `embed()` before any provider sees the text.
+ *
+ * Long retention transcripts (full multi-turn session windows) routinely outgrow
+ * embedding model context windows: BGE/E5 defaults are 512 tokens, bge-m3 is
+ * 8192, and OpenAI's text-embedding-3-* is 8192. llama.cpp's `/embeddings`
+ * server rejects oversized requests with `request (N tokens) exceeds the
+ * available context size`; OpenAI silently right-truncates. Capping at the
+ * source gives both backends deterministic behavior and prevents the silent
+ * recall degradation we saw in issue #3126.
+ *
+ * Default `8192` chars is intentionally conservative for 8192-token embedding
+ * contexts (bge-m3, OpenAI text-embedding-3) and CJK-heavy transcripts. Raise
+ * it for larger local contexts (for example Qwen3-Embedding with 32k ctx).
+ * `0` disables the cap.
+ */
+export declare function embeddingMaxInputChars(env?: Env): number;
+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 maxEpisodeChars(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 interface RecallFeatureFlags {
+    polyphonicRecall?: boolean;
+    enhancedRecall?: boolean;
+    proactiveLinking?: boolean;
+}
+/**
+ * Sets process-wide defaults for the env-gated recall features. Host configuration
+ * (e.g. the coding-agent `mnemopi.polyphonicRecall` / `mnemopi.enhancedRecall` /
+ * `mnemopi.proactiveLinking` settings) lands here; the `MNEMOPI_POLYPHONIC_RECALL` /
+ * `MNEMOPI_ENHANCED_RECALL` / `MNEMOPI_PROACTIVE_LINKING` environment variables still
+ * win whenever they are set.
+ */
+export declare function configureRecallFeatures(flags: RecallFeatureFlags): void;
+export declare function polyphonicRecallEnabled(env?: Env): boolean;
+export declare function temporalHalflifeHours(env?: Env): number;
+export declare function enhancedRecallEnabled(env?: Env): boolean;
+export declare function proactiveLinkingEnabled(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 {};