@linxiraos/pi-mnemopi 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,248 @@
+# Changelog
+
+## [Unreleased]
+
+### Changed
+
+- Reset the version to 1.0.0 and republished under the `@linxiraos/*` scope, breaking from the `@oh-my-pi` version lineage.
+## [17.2.11] - 2026-08-07
+
+### Fixed
+
+- Fixed an issue where an interrupted local embedding model download could permanently corrupt the cache and silently disable semantic recall. The system now automatically detects incomplete model files, clears the corrupted cache, and retries the download.
+
+## [17.2.10] - 2026-08-06
+
+### Changed
+
+- Updated internal LRU cache implementation.
+
+## [17.2.6] - 2026-08-03
+
+### Added
+
+- Added opt-in SQLite page-size configuration for file-backed databases, configurable via the `MNEMOPI_DB_PAGE_SIZE` environment variable or the `pageSize` option in `openDatabase`. Existing databases retain their original page size.
+
+## [17.2.3] - 2026-08-01
+
+### Fixed
+
+- Stripped `<think>…</think>` reasoning blocks from remote LLM output in `cleanOutput`, so reasoning-model responses no longer leak into consolidated memories or corrupt fact extraction (the reasoning wrapper previously survived parsing and every stored fact became reasoning prose). ([#7231](https://github.com/can1357/oh-my-pi/issues/7231))
+
+## [17.2.2] - 2026-07-31
+
+### Fixed
+
+- Fixed a resource leak where SQLite prepared statements were not properly released, keeping the database connection alive after calling close(). This resolves file locking issues on Windows (which prevented deleting, moving, or rotating database files) and silent file handle leaks on POSIX systems.
+
+## [17.0.8] - 2026-07-22
+
+### Changed
+
+- Optimized vector operations (exact vector-index search, SHMR similarity clustering, and default-similarity MMR rerank) by migrating hot loops to native batch kernels, resulting in significant performance improvements (up to 1.8x faster top-K search, 2.4x faster pairwise clustering, and 22-36x faster MMR reranking).
+
+## [17.0.4] - 2026-07-18
+
+### Fixed
+
+- Fixed a corrupt cached embedding model (truncated `model_optimized.onnx`, `Protobuf parsing failed` on load) permanently disabling local embeddings: init now quarantines the broken cache file (rename to `*.corrupt-<ts>`, only when the path resolves inside the fastembed cache directory) and retries once so the model re-downloads.
+
+## [17.0.1] - 2026-07-16
+
+### Fixed
+
+- Fixed working-memory TTL trim silently deleting restored or imported durable rows: rows keeping `consolidated_at = NULL` with an old `timestamp` are no longer trimmed when flagged `IMPORTED`, `importFromDict` stamps imported rows as consolidated, and every working-memory delete path (trim, `forgetWorking`, force-import overwrite) now cascades linked annotations, embeddings, facts, memoria projections, gists, and graph edges instead of leaving orphans. ([#4819](https://github.com/can1357/oh-my-pi/issues/4819))
+- Fixed Mnemopi local embeddings on Windows loading an unrelated `onnxruntime.dll` from the inherited system path instead of fastembed's cached ORT runtime. ([#4849](https://github.com/can1357/oh-my-pi/issues/4849))
+
+## [16.3.9] - 2026-07-06
+
+### Fixed
+
+- Fixed extractor JSON parsing to correctly unwrap object-shaped facts, instructions, preferences, and timeline items from known text fields instead of persisting literal `[object Object]` rows.
+
+## [16.3.7] - 2026-07-05
+
+### Added
+
+- Added `RecallOptions.contentPreviewChars` to allow customizing or disabling the content preview cap (default is 500, set to 0 for full content).
+- Added `RecallResult.truncated` and `RecallResult.full_length` properties to easily identify clipped previews without parsing trailing markers.
+
+### Fixed
+
+- Fixed background LLM fact extraction to preserve specific extractor categories (`instructions`, `preferences`, `timelines`, and `kg` triples) in MEMORIA tables and graph triples instead of flattening them into generic `fact/entity` rows.
+- Improved recall previews and `factLine` context to append a trailing ellipsis (`…`) when content is clipped, preventing mid-word truncation without a marker.
+
+## [16.3.5] - 2026-07-04
+
+### Fixed
+
+- Fixed `remember(..., { embedText })` so hosts can store full transcripts while embedding, FTS-indexing, and rebuild-reembedding a marker-free projection. ([#4395](https://github.com/can1357/oh-my-pi/issues/4395))
+
+## [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 `@oh-my-pi/pi-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 `@oh-my-pi/pi-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,108 @@
+# @linxiraos/pi-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 "@linxiraos/pi-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 "@linxiraos/pi-mnemopi";
+import type { Model } from "@linxiraos/pi-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_DB_PAGE_SIZE`: optional SQLite page size for new file-backed databases; use a valid power of two from 512 to 65536 or `os` to request the detected system page size. Unset preserves SQLite's default.
+- `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/index.js";
+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.js";
+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 {};