@monoes/monomindcli 2.16.12 → 2.16.14

package/dist/src/memory/memory-bridge.js

@@ -4,1564 +4,24 @@
  * Uses SQLiteBackend (better-sqlite3, sql.js WASM fallback) from @monoes/memory.
  * LanceDB was replaced by this SQLite engine 2026-07; the on-disk data
  * directory is still named `lancedb` for legacy/back-compat path resolution
- * (see getDbPath below) but no longer holds LanceDB data.
+ * (see getDbPath in memory-bridge-paths.ts) but no longer holds LanceDB data.
  * All exported function signatures are unchanged.
  *
  * @module v1/cli/memory-bridge
  */
-import * as crypto from 'node:crypto';
-import * as fs from 'node:fs';
-import * as os from 'node:os';
-import * as path from 'node:path';
-import { ettinHeadLogit, loadEttinHead, resolveRerankerSource } from './reranker-head.js';
-// ===== Embedding validation =====
-const MAX_EMBEDDING_DIMS = 8192;
-const MAX_EMBEDDING_JSON_BYTES = MAX_EMBEDDING_DIMS * 32; // ~256KB ceiling
-/**
- * R1: surface swallowed errors when DEBUG/MONOMIND_DEBUG is on. The bridge
- * has ~12 `} catch { return null; }` sites that collapse SQLITE_BUSY,
- * EACCES, disk-full, and schema mismatches into "no matches" with zero
- * diagnostic. Behavior contract (return null on failure) is unchanged;
- * observability is added. Caller passes the bridge fn name + the thrown
- * value so the log is greppable per call site.
- */
-function logBridgeError(label, err) {
-    if (!(process.env.DEBUG || process.env.MONOMIND_DEBUG))
-        return;
-    const msg = err instanceof Error ? `${err.name}: ${err.message}` : String(err);
-    console.error(`[bridge:${label}] ${msg}`);
-}
-export function safeParseEmbedding(raw) {
-    if (typeof raw !== 'string' || raw.length === 0)
-        return null;
-    if (raw.length > MAX_EMBEDDING_JSON_BYTES)
-        return null;
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (e) {
-        logBridgeError('safeParseEmbedding', e);
-        return null;
-    }
-    if (!Array.isArray(parsed))
-        return null;
-    if (parsed.length === 0 || parsed.length > MAX_EMBEDDING_DIMS)
-        return null;
-    for (let i = 0; i < parsed.length; i++) {
-        const v = parsed[i];
-        if (typeof v !== 'number' || !Number.isFinite(v))
-            return null;
-    }
-    return parsed;
-}
-// ===== Constants =====
-export const BRIDGE_EMBEDDING_MODEL = 'Alibaba-NLP/gte-modernbert-base';
-export const BRIDGE_EMBEDDING_DIMS = 768;
-const BRIDGE_MAX_KEY_LEN = 4 * 1024;
-const BRIDGE_MAX_VALUE_LEN = 16 * 1024;
-const MAX_TAGS = 32;
-const MAX_TAG_LEN = 64;
-// Search results serve the head of the stored content only — full values bloat
-// every MCP payload. Entries needing the full text can read the entry by key.
-const BRIDGE_RESULT_CONTENT_CAP = 500;
-function capResultContent(content) {
-    return content.length > BRIDGE_RESULT_CONTENT_CAP
-        ? `${content.slice(0, BRIDGE_RESULT_CONTENT_CAP)}…`
-        : content;
-}
-// ===== DB path resolution =====
-// LanceDB commits via atomic rename, which exFAT/SMB project volumes don't support
-// (ENOTSUP os error 45) — and non-APFS volumes grow ._ AppleDouble sidecars inside
-// the .lance datasets that corrupt reads. So the store always lives on the home
-// volume, namespaced per project directory.
-//
-// The slug is a hash of the full resolved path, not a character-substitution of
-// it — flattening separators to '-' is not collision-safe ('/x/foo-bar' and
-// '/x/foo/bar' would both flatten to 'x-foo-bar'). A short readable prefix is
-// kept purely so the directory name is browsable; only the hash guarantees
-// uniqueness.
-// o-16: `.git` and `.monomind` are NOT equivalent evidence of a project.
-// `.git` is created by the user, deliberately (`git init`/clone) — "this
-// directory is a repository". `.monomind` is created by monomind ITSELF, as
-// a side effect of running anywhere — "monomind once ran here", and nothing
-// more. Treating a bare `.monomind` ancestor as adoptable is a feedback
-// loop: a wrong resolution creates the very marker that captures every
-// future descendant. Measured against the actual incident:
-// `~/mdev-tmp/.monomind` and `~/.monomind` both exist,
-// neither has a `.git` or manifest, and neither is a project — both are
-// monomind's own state directories. `INDEPENDENT_PROJECT_MARKERS` (other
-// than `.git`, handled unconditionally) is what makes a `.monomind`
-// ancestor's claim independently checkable.
-const INDEPENDENT_PROJECT_MARKERS = ['package.json', 'pyproject.toml', 'go.mod', 'Cargo.toml'];
-function markerExists(p) {
-    try {
-        return fs.existsSync(p);
-    }
-    catch (e) {
-        logBridgeError('walkToProjectRoot', e); /* unreadable dir — treat as absent, keep walking */
-        return false;
-    }
-}
-/** o-16 revision 1 (reviewer MAJOR 1, measured not argued): the anchor used
- *  to be trusted unconditionally. Two proven harms: (a) a non-existent path
- *  (a typo) was adopted as-is, and `projectDataDir()` hashed it into a
- *  fresh, empty store directory — the exact split-store failure this item
- *  exists to eliminate, reintroduced by the escape hatch meant to fix it.
- *  (b) `MONOMIND_PROJECT_ROOT=/` disabled `getDbPath`'s MCP path-traversal
- *  guard entirely: the guard is `path.relative(getProjectRoot(), resolved)`
- *  not starting with `..`, and `path.relative('/', anything)` never does.
- *  `existsSync` + `isDirectory` alone catch (a) but NOT (b) — `/` exists and
- *  is a directory — so the filesystem-root check below is what closes (b)
- *  specifically; it is not redundant with the others. An invalid anchor is
- *  never silently accepted OR silently dropped: the caller falls through to
- *  the ordinary walk, and the fact that an anchor was set and rejected is
- *  preserved on the result (`invalidAnchor`) so `doctor` can say exactly
- *  what happened instead of the user just seeing an unexplained directory. */
-function validateAnchor(raw) {
-    if (!path.isAbsolute(raw))
-        return { ok: false, problem: 'not an absolute path' };
-    const lexical = path.resolve(raw);
-    // o-16 revision 2 (reviewer MAJOR): resolve symlinks BEFORE validating,
-    // and return the REAL path, not the lexical one. Without this, a symlink
-    // whose real target is '/' (e.g. MONOMIND_PROJECT_ROOT=<tmp>/link-to-root)
-    // passes every check below on its lexical form — dirname(lexical) !==
-    // lexical, since the link itself sits inside a normal directory — while
-    // getDbPath's traversal guard (memory-bridge.ts's realOrResolved(), i.e.
-    // fs.realpathSync) resolves the SAME anchor to '/' downstream. Two
-    // notions of "the root" in one module: the store gets hashed from the
-    // lexical path this function returned, the guard's boundary is computed
-    // from the real one, and path.relative('/', anything) never starts with
-    // '..' — the exact guard-disabling hole this function exists to close,
-    // reopened one indirection away. Validating and returning the SAME (real)
-    // path is what makes validation and consumption agree, for any
-    // symlinked anchor, not just a literal '/'.
-    let real;
-    try {
-        real = fs.realpathSync(lexical);
-    }
-    catch {
-        return { ok: false, problem: 'does not exist' };
-    }
-    let stat;
-    try {
-        stat = fs.statSync(real);
-    }
-    catch {
-        return { ok: false, problem: 'does not exist' };
-    }
-    if (!stat.isDirectory())
-        return { ok: false, problem: 'is not a directory' };
-    if (path.dirname(real) === real) {
-        return {
-            ok: false,
-            problem: 'is the filesystem root, which would disable the MCP path-traversal guard',
-        };
-    }
-    return { ok: true, resolved: real };
-}
-function walkToProjectRoot(start) {
-    // Explicit escape hatch: honored ahead of any walk, but only once valid —
-    // see validateAnchor's comment for why unconditional trust was wrong.
-    const anchorRaw = process.env.MONOMIND_PROJECT_ROOT;
-    let invalidAnchor;
-    if (anchorRaw) {
-        const check = validateAnchor(anchorRaw);
-        if (check.ok)
-            return { root: check.resolved, reason: 'explicit-anchor' };
-        invalidAnchor = { value: anchorRaw, problem: check.problem };
-        logBridgeError('walkToProjectRoot', new Error(`MONOMIND_PROJECT_ROOT ignored: "${anchorRaw}" ${check.problem} — falling back to the walk`));
-    }
-    // Retained from before o-16: protects the dotfiles-repo-at-$HOME case (a
-    // `.git` at $HOME must not swallow every loose project underneath it).
-    // Insufficient ALONE against the reported incident — that marker sat
-    // *inside* $HOME, so the walk reached it long before ever reaching home —
-    // which is why it is additive to, not a replacement for, the rule below.
-    const home = path.resolve(os.homedir());
-    let dir = start;
-    let ignoredBareMonomind;
-    let atStart = true;
-    for (;;) {
-        if (dir === home)
-            break;
-        if (markerExists(path.join(dir, '.git')))
-            return { root: dir, reason: 'git', invalidAnchor };
-        if (markerExists(path.join(dir, '.monomind'))) {
-            if (atStart)
-                return { root: dir, reason: 'monomind-at-start', invalidAnchor };
-            const corroborated = INDEPENDENT_PROJECT_MARKERS.some((m) => markerExists(path.join(dir, m)));
-            if (corroborated)
-                return { root: dir, reason: 'monomind-with-marker', invalidAnchor };
-            // The nearest marker found doesn't qualify — stop HERE. Continuing
-            // past it to adopt some more distant, unrelated ancestor's `.git`
-            // would break "nested projects keep their own brain" in a new way:
-            // a vendored sub-repo with only a bare `.monomind` would get silently
-            // merged into whatever repo happens to sit further up, which the
-            // original nearest-marker-wins design specifically existed to
-            // prevent. Not adopting is the fallback; walking past is not.
-            ignoredBareMonomind = dir;
-            break;
-        }
-        atStart = false;
-        const parent = path.dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    if (ignoredBareMonomind !== undefined) {
-        logBridgeError('walkToProjectRoot', new Error(`bare .monomind ancestor ignored at ${ignoredBareMonomind} (no independent project marker) — using ${start}`));
-    }
-    return { root: start, reason: 'start-fallback', ignoredBareMonomind, invalidAnchor };
-}
-// getBackend() resolves the store path on every store/search, so a bulk ingest
-// would otherwise repeat the stat walk thousands of times. A project does not
-// gain or lose its markers mid-process; the key is the starting directory, so a
-// chdir still re-resolves.
-let _rootCacheKey;
-let _rootCacheVal;
-/** The full resolution — root, reason and (when the walk found nothing
- *  adoptable) which bare `.monomind` ancestor it ignored. `doctor` uses this
- *  to disclose which directory a user's brain is keyed to and why, instead
- *  of a plausible-but-silent path (o-16). See `getProjectRoot` for the
- *  string-only form the other ~28 call sites use. */
-export function getProjectRootResolution(from = process.env.MONOMIND_CWD || process.cwd()) {
-    const start = path.resolve(from);
-    // Cache key must cover everything walkToProjectRoot's result depends on,
-    // not just `start` — MONOMIND_PROJECT_ROOT short-circuits the walk (o-16),
-    // so a cache keyed on `start` alone would replay a stale pre-anchor (or
-    // stale different-anchor) result for the same cwd once the env var changes
-    // mid-process, silently defeating the escape hatch it's supposed to be.
-    const cacheKey = `${start}\n${process.env.MONOMIND_PROJECT_ROOT ?? ''}`;
-    if (cacheKey === _rootCacheKey && _rootCacheVal !== undefined)
-        return _rootCacheVal;
-    const resolved = walkToProjectRoot(start);
-    _rootCacheKey = cacheKey;
-    _rootCacheVal = resolved;
-    return resolved;
-}
-/** The directory that identifies "this project" for every Second Brain store.
- *
- * Deliberately NOT the raw cwd: keying on cwd forked the brain per directory —
- * `doc ingest ./docs` from a package subdir wrote to a different store, and a
- * different metadata file, than the identical command at the repo root, and
- * neither could see the other. We walk up to the nearest ancestor carrying a
- * `.git` marker (any depth), or a `.monomind` marker corroborated by an
- * independent project marker, so every directory inside one project resolves
- * to one brain. Nested projects still win (the walk stops at the FIRST
- * eligible marker), which keeps worktrees and vendored sub-repos independent.
- *
- * o-16: a BARE `.monomind` ancestor (no `.git`, no manifest) is NOT adopted.
- * `.monomind` is created by monomind itself as a side effect of running
- * anywhere — it is not independent evidence of a project, and a wrong
- * resolution creates the very marker that would capture every future
- * descendant if it were trusted alone. See `walkToProjectRoot`'s comment for
- * the measured incident this fixes. The starting directory's OWN `.monomind`
- * is still trusted unconditionally — that is the user pointing at their own
- * project — and `.git` at any depth is untouched, so CI/devcontainer repos
- * and subdirectory unification behave exactly as before.
- *
- * The walk never crosses the home directory: a dotfiles repo at `~` would
- * otherwise swallow every loose project underneath it into one shared brain.
- * `MONOMIND_PROJECT_ROOT`, if set AND VALID (absolute, exists, is a
- * directory, is not itself the filesystem root — see `validateAnchor`), is
- * an explicit anchor that skips the walk entirely — the escape hatch for
- * the genuinely ambiguous case (design decision 4 / AC-3c: a real, non-git
- * project whose root has a bare `.monomind` and no manifest has no other
- * way to be found from a subdirectory). An invalid anchor falls through to
- * the walk rather than being adopted OR silently dropped — see
- * `ProjectRootResolution.invalidAnchor`.
- *
- * This is `MONOMIND_PROJECT_ROOT`'s SECOND consumer in this codebase —
- * `mcp-tools/guidance-tools.ts:findProjectRoot()` already reads the same
- * env var, for a DIFFERENT marker (`.claude`, not `.monomind`/`.git`), with
- * a stricter rule: `if (envRoot && existsSync(join(envRoot, '.claude')))`,
- * i.e. it only honors the anchor when `.claude` exists there, silently
- * falling through to its own walk otherwise. After this revision the two
- * converge on ANCHOR HANDLING for the cases that matter most — a typo'd or
- * missing path is rejected by both (this one via `validateAnchor`,
- * guidance-tools' because `.claude` is absent) — but "converge" describes
- * only whether each accepts or rejects the anchor, not the final resolved
- * root: a rejected anchor falls through to each resolver's OWN walk
- * (`walkToProjectRoot` here; guidance-tools' own Strategy 1/2/3 chain
- * there), which can still land on different directories for the same
- * unanchored cwd. Two residual disagreements remain, both legitimate rather
- * than oversights:
- * 1. An anchor that exists and is a real directory but has no `.claude` in
- *    it: this function honors it (memory has no reason to require a
- *    `.claude` folder — a project's knowledge store isn't gated on whether
- *    an agent config lives there), guidance-tools does not (`.claude` is
- *    the one thing it's searching FOR, so its absence is a real signal, not
- *    noise, for that consumer specifically).
- * 2. A RELATIVE anchor: `validateAnchor` rejects it outright (an anchor
- *    that silently depends on cwd defeats the point of an anchor).
- *    guidance-tools has no absolute-path check, so `existsSync(join(envRoot,
- *    '.claude'))` would resolve a relative `envRoot` against cwd and could
- *    accept it — narrower in practice (needs a `.claude` at that resolved
- *    location too) but a real gap in the two resolvers' shared assumptions.
- * Reconciling the two resolvers' semantics into one shared rule is a
- * separate, larger question (tracked as o-32), not something this fix
- * should decide as a side effect.
- *
- * For anyone who already ran from the project root — the normal case — the
- * resolved path is identical to before, so their store does not move.
- *
- * `MONOMIND_CWD` wins over the real cwd, matching `getProjectCwd()` in
- * mcp-tools/types.ts — an MCP server is launched with whatever cwd the client
- * chose, and that env var is already how monograph and swarm state learn which
- * project they belong to. Inlined rather than imported to keep this module on
- * node builtins only (see the static import in document-pipeline.ts).
- */
-export function getProjectRoot(from = process.env.MONOMIND_CWD || process.cwd()) {
-    return getProjectRootResolution(from).root;
-}
-function projectDataDir() {
-    const resolved = path.resolve(getProjectRoot());
-    const hash = crypto.createHash('sha256').update(resolved).digest('hex').slice(0, 16);
-    const readable = path
-        .basename(resolved)
-        .replace(/[^a-zA-Z0-9._-]+/g, '-')
-        .slice(0, 40) || 'project';
-    return path.join(os.homedir(), '.monomind', 'projects', `${readable}-${hash}`);
-}
-/** Resolve symlinks so the traversal check below can't be bypassed by a link
- * that lexically resolves inside the allowed trees but points outside them. */
-function realOrResolved(p) {
-    try {
-        return fs.realpathSync(p);
-    }
-    catch (e) {
-        logBridgeError('realOrResolved', e);
-        return p;
-    }
-}
-/** The personal, cross-project knowledge store. Deliberately a SIBLING of
- *  ~/.monomind/projects (never inside it) so per-project pruning heuristics
- *  (`cleanup --data`) can never touch it. Env-overridable for tests and for
- *  users who keep their brain on a synced/external location. Resolved lazily
- *  so the override works regardless of import order. */
-export function getGlobalBrainDir() {
-    return (process.env.MONOMIND_GLOBAL_BRAIN_DIR || path.join(os.homedir(), '.monomind', 'global-brain'));
-}
-/** Sentinel callers pass as dbPath to address the global brain. */
-export const GLOBAL_BRAIN = '@global';
-function getDbPath(customPath) {
-    const defaultDir = path.join(projectDataDir(), 'lancedb');
-    if (!customPath || customPath === ':memory:')
-        return defaultDir;
-    if (customPath === GLOBAL_BRAIN)
-        return getGlobalBrainDir();
-    // Treat legacy .db paths (and the legacy .swarm dir) as a signal to use the default
-    if (customPath.endsWith('.db'))
-        return defaultDir;
-    const resolved = realOrResolved(path.resolve(customPath));
-    // Guard against path traversal from MCP inputs: only allow paths inside the
-    // project, the per-project home data dir, or the global brain.
-    //
-    // STATED LIMIT (o-16 revision 2, corrected in revision 3 — verifier found
-    // the first version of this comment named the wrong path): `validateAnchor`
-    // resolves a `MONOMIND_PROJECT_ROOT` anchor to its REAL path ONCE via
-    // `fs.realpathSync`, and caches THAT REAL PATH STRING in `_rootCacheVal`
-    // (see above) — `getProjectRoot()` returns this cached real-path string on
-    // every subsequent call in this process; it does not re-read the anchor
-    // or re-run `validateAnchor`. So swapping the filesystem entry AT THE
-    // ANCHOR PATH after validation does nothing — the anchor itself is never
-    // consulted again. The actual gap is one level further in: the line below
-    // calls `realOrResolved()` (a fresh `fs.realpathSync`) on that cached
-    // REAL-PATH STRING every time `getDbPath` runs. If the filesystem entry
-    // AT THAT RESOLVED TARGET (not the anchor) is swapped for a symlink to
-    // `/` after validation but before a later call here, this re-resolves to
-    // the new real target live, and the guard is bypassed for that call — a
-    // TOCTOU gap between a one-time resolution and a re-resolved-every-call
-    // consumption of the same path string. NOT defended against: closing it
-    // properly means validating and consuming a single resolved handle rather
-    // than a path string, which is a real design change and out of scope for
-    // this fix. Accepted because it needs filesystem write access at the
-    // resolved target's path, timed against a live process — an attacker
-    // with that capability already has easier routes than this guard.
-    const relCwd = path.relative(realOrResolved(getProjectRoot()), resolved);
-    const relHome = path.relative(realOrResolved(projectDataDir()), resolved);
-    const relGlobal = path.relative(realOrResolved(getGlobalBrainDir()), resolved);
-    if (!relCwd.startsWith('..') && !path.isAbsolute(relCwd))
-        return resolved;
-    if (!relHome.startsWith('..') && !path.isAbsolute(relHome))
-        return resolved;
-    if (!relGlobal.startsWith('..') && !path.isAbsolute(relGlobal))
-        return resolved;
-    return defaultDir;
-}
-/** Resolve the real on-disk SQLite data-dir path for a given custom path (or the
- *  default) — the dir is still named `lancedb` for legacy path back-compat. */
-export function bridgeGetDbPath(customPath) {
-    return getDbPath(customPath);
-}
-function getAutomemConfig() {
-    const defaults = { dedupThreshold: 0.85, staleDays: 7, feedbackInfluence: 0.2 };
-    try {
-        const configPath = path.join(process.cwd(), '.monomind', 'automem-config.json');
-        if (!fs.existsSync(configPath))
-            return defaults;
-        const stat = fs.statSync(configPath);
-        if (stat.size > 64 * 1024)
-            return defaults;
-        const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
-        return {
-            dedupThreshold: typeof config?.scaffold?.dedupThreshold === 'number'
-                ? config.scaffold.dedupThreshold
-                : defaults.dedupThreshold,
-            staleDays: typeof config?.scaffold?.staleDays === 'number'
-                ? config.scaffold.staleDays
-                : defaults.staleDays,
-            feedbackInfluence: typeof config?.scaffold?.feedbackInfluence === 'number'
-                ? Math.max(0, Math.min(1, config.scaffold.feedbackInfluence))
-                : defaults.feedbackInfluence,
-        };
-    }
-    catch (e) {
-        logBridgeError('loadBridgeConfig', e);
-        return defaults;
-    }
-}
-// ===== Usage/feedback weights (cognee-style, stored in entry metadata) =====
-//
-// feedback_weight (0..1, default 0.5): EWMA of explicit/auto ratings applied to
-// the entries actually used to produce an answer. frequency_weight (>=0): how
-// often the entry was returned by a search. Both live in the entry's metadata
-// JSON — deliberately NOT backend schema columns, so no @monoes/memory publish
-// is needed and both backends work unchanged.
-const DEFAULT_FEEDBACK_WEIGHT = 0.5;
-const FEEDBACK_EWMA_ALPHA = 0.1;
-/** frequency_weight normalization ceiling: 10+ uses counts as fully reinforced. */
-const FREQUENCY_NORM_CAP = 10;
-function entryWeights(metadata) {
-    const md = (metadata ?? {});
-    const fw = typeof md.feedback_weight === 'number' && Number.isFinite(md.feedback_weight)
-        ? Math.max(0, Math.min(1, md.feedback_weight))
-        : DEFAULT_FEEDBACK_WEIGHT;
-    const freq = typeof md.frequency_weight === 'number' && Number.isFinite(md.frequency_weight)
-        ? Math.max(0, md.frequency_weight)
-        : 0;
-    return { feedback: fw, frequency: freq };
-}
-/** Blend learned usefulness into a GENUINE embedding-similarity score.
- *  Cognee guard: never applied to keyword-fallback scores — those carry no
- *  real relevance signal, and blending there lets a high-feedback stale entry
- *  outrank relevant matches and self-reinforce (rich-get-richer). */
-function blendScore(cosineSim, weights, influence) {
-    if (influence <= 0)
-        return cosineSim;
-    const usefulness = 0.7 * weights.feedback + 0.3 * Math.min(1, weights.frequency / FREQUENCY_NORM_CAP);
-    return (1 - influence) * cosineSim + influence * usefulness;
-}
-function generateId(prefix) {
-    return `${prefix}_${Date.now()}_${crypto.randomBytes(8).toString('hex')}`;
-}
-const backendSlots = new Map();
-const MAX_BACKEND_SLOTS = 5;
-let _embedder = null;
-let _embedderPromise = null;
-const MAX_INIT_ATTEMPTS = 3;
-// Process-local kill switch for both local ONNX models (embedder + reranker):
-// the in-process equivalent of MONOMIND_NO_LOCAL_EMBEDDINGS=1 plus
-// MONOMIND_RERANKER=0. Org runs flip this instead of setting those env vars,
-// because process.env is inherited by every child — each role's CLI and every
-// command a role runs through Bash — which silently degraded a role's own
-// `monomind memory search` to keyword-only (#249).
-let _localModelsDisabled = false;
-/** Disable local model loads for THIS process only (see `org run`/`org serve`). */
-export function disableLocalModels() {
-    _localModelsDisabled = true;
-}
-export function localEmbeddingsDisabled() {
-    return _localModelsDisabled || process.env.MONOMIND_NO_LOCAL_EMBEDDINGS === '1';
-}
-export function rerankerDisabled() {
-    return _localModelsDisabled || process.env.MONOMIND_RERANKER === '0';
-}
-// ===== Lazy cross-encoder reranker (ettin-32m) =====
-//
-// Same ORT constraints as the embedder (ADR-R001). Loaded only when the first
-// search with >1 candidate completes — never on store, never on startup.
-// Disabled with MONOMIND_RERANKER=0.
-//
-// The upstream HF ONNX file for ettin-reranker-32m-v1 only contains the base
-// ModernBERT encoder (outputs last_hidden_state, no logits). The classifier
-// head lives in separate sentence-transformers module safetensors files
-// (2_Dense, 3_LayerNorm, 4_Dense). Two ways to score, in order of preference:
-//  - a self-exported ONNX with the head baked in (scripts/export-ettin-onnx.py,
-//    needs PyTorch) under ~/.monomind/models/ettin-reranker-32m-v1-onnx/
-//  - the upstream encoder plus the head applied in JS (reranker-head.ts), from
-//    head files fetched by `doc eval --provision-model` into
-//    ~/.monomind/models/ettin-reranker-32m-v1-head/
-// With neither, the reranker does not load: the upstream encoder alone cannot
-// score, and loading it anyway ran the model on every search for nothing.
-export const BRIDGE_RERANKER_MODEL = 'cross-encoder/ettin-reranker-32m-v1';
-/** Where reranker export / head files live. */
-export function rerankerModelsDir() {
-    return path.join(os.homedir(), '.monomind', 'models');
-}
-/** How the reranker is scoring, or null when it is not loaded. */
-let _rerankerKind = null;
-export function rerankerKind() {
-    return _rerankerKind;
-}
-let _reranker = null;
-let _rerankerPromise = null;
-/** Pre-load the cross-encoder reranker model. Idempotent, no-op when
- *  MONOMIND_RERANKER=0. Exported so the eval harness can force-load before
- *  the network guard blocks model downloads. */
-export async function loadReranker() {
-    if (_reranker)
-        return;
-    if (rerankerDisabled())
-        return;
-    if (!_rerankerPromise) {
-        _rerankerPromise = (async () => {
-            try {
-                const source = resolveRerankerSource(rerankerModelsDir());
-                if (!source)
-                    return; // nothing that can score — stay unloaded (no per-search cost)
-                const hf = await import('@huggingface/transformers');
-                const opts = { local_files_only: true };
-                const sigmoid = (logit) => 1 / (1 + Math.exp(-logit));
-                if (source.kind === 'export') {
-                    const tokenizer = await hf.AutoTokenizer.from_pretrained(source.dir, opts);
-                    const model = await hf.AutoModelForSequenceClassification.from_pretrained(source.dir, opts);
-                    _reranker = async (query, passage) => {
-                        const inputs = await tokenizer(query, {
-                            text_pair: passage,
-                            padding: true,
-                            truncation: true,
-                        });
-                        const output = await model(inputs);
-                        // num_labels=1 → [1,1] regression score, apply sigmoid
-                        return sigmoid(output.logits.data[0]);
-                    };
-                }
-                else {
-                    const head = loadEttinHead(source.dir);
-                    const tokenizer = await hf.AutoTokenizer.from_pretrained(BRIDGE_RERANKER_MODEL, opts);
-                    const model = await hf.AutoModel.from_pretrained(BRIDGE_RERANKER_MODEL, {
-                        ...opts,
-                        dtype: 'fp32',
-                    });
-                    _reranker = async (query, passage) => {
-                        const inputs = await tokenizer(query, {
-                            text_pair: passage,
-                            padding: true,
-                            truncation: true,
-                        });
-                        const output = await model(inputs);
-                        return sigmoid(ettinHeadLogit(head, output.last_hidden_state.data));
-                    };
-                }
-                _rerankerKind = source.kind;
-            }
-            catch (e) {
-                _rerankerPromise = null; // allow retry
-                if (process.env.DEBUG || process.env.MONOMIND_DEBUG)
-                    console.error('[memory-bridge] reranker failed to load:', e);
-            }
-        })();
-    }
-    await _rerankerPromise;
-}
-/** Rerank an array of results using the cross-encoder. Mutates nothing; returns
- *  a new sorted array with reranker scores in provenance. */
-async function rerankResults(query, results, limit) {
-    const reranker = _reranker;
-    if (!reranker || results.length <= 1)
-        return { reranked: results, applied: false };
-    try {
-        const scored = await Promise.all(results.map(async (r) => {
-            const rerankerScore = await reranker(query, r.content || '');
-            return {
-                ...r,
-                score: rerankerScore,
-                provenance: `${r.provenance ?? ''}→rerank:${rerankerScore.toFixed(3)}`,
-            };
-        }));
-        scored.sort((a, b) => b.score - a.score);
-        return { reranked: scored.slice(0, limit), applied: true };
-    }
-    catch (e) {
-        if (process.env.DEBUG || process.env.MONOMIND_DEBUG)
-            console.error('[memory-bridge] reranking failed — returning original order:', e);
-        return { reranked: results, applied: false };
-    }
-}
-/** Flush after mutations: the sql.js fallback backend is in-memory WASM and
- *  only reaches disk via persist(); the CLI process is short-lived, so waiting
- *  for an auto-persist interval would lose writes. No-op on better-sqlite3. */
-async function flushBackend(backend) {
-    try {
-        await backend?.persist?.();
-    }
-    catch (e) {
-        logBridgeError('flushBackend', e); /* best effort */
-    }
-}
-/** Loads the local embedding model.
- *
- *  This is the single point where `onnxruntime-node` enters the CLI process
- *  (via @huggingface/transformers). Once it has run, the process is subject to
- *  docs/adrs/ADR-R001-onnxruntime-process-teardown.md: calling process.exit()
- *  will abort with SIGABRT ("mutex lock failed") instead of exiting cleanly,
- *  and disposing the pipeline first does not help.
- *
- *  Anything that reaches this — `doctor`, `memory store`, `memory search`, the
- *  MCP memory tools — inherits that constraint, which is why it bit commands
- *  that look nothing like ML work. Adding a new caller is fine; adding a new
- *  process-exit path is not. */
-async function loadEmbedder() {
-    if (_embedder)
-        return;
-    // MONOMIND_NO_LOCAL_EMBEDDINGS: skip the native pipeline() load entirely.
-    // On some machines @huggingface/transformers' ONNX runtime crashes the
-    // whole process with a native `libc++abi terminate` (a mutex failure
-    // inside the tokenizer backend) rather than throwing a catchable JS
-    // error — the try/catch below only protects against normal failures
-    // (missing cache, bad revision, offline), not that. Everything that
-    // reads _embedder already tolerates it being unset (keyword-only
-    // fallback), so skipping the call is the only way to actually avoid the
-    // crash rather than just failing to catch it. Org runs disable it
-    // in-process (disableLocalModels()) since a crashed org is much worse than
-    // degraded search; anyone else can opt in with the env var.
-    if (localEmbeddingsDisabled())
-        return;
-    if (!_embedderPromise) {
-        _embedderPromise = (async () => {
-            try {
-                const hf = await import('@huggingface/transformers');
-                // revision must be a git ref — 'main' is the HF default; 'default' 404s and
-                // silently killed embeddings (every search degraded to keyword matching)
-                // dtype pinned explicitly: transformers.js logs a "dtype not specified"
-                // warning to the console on every load otherwise (leaks into CLI output).
-                const extractor = await hf.pipeline('feature-extraction', BRIDGE_EMBEDDING_MODEL, {
-                    revision: 'main',
-                    dtype: 'q8',
-                    local_files_only: true,
-                });
-                _embedder = async (text) => {
-                    const output = await extractor(text, { pooling: 'cls', normalize: true });
-                    return new Float32Array(output.data);
-                };
-            }
-            catch (e) {
-                _embedderPromise = null; // allow retry (e.g. first call offline)
-                if (process.env.DEBUG || process.env.MONOMIND_DEBUG)
-                    console.error('[memory-bridge] embedding model failed to load — store and search without vectors:', e);
-            }
-        })();
-    }
-    await _embedderPromise;
-}
-/** Fetches the local embedding model into the transformers cache so later
- *  loadEmbedder() calls (local_files_only) find it. Same model, revision and
- *  dtype as loadEmbedder() — only the network is allowed here, which is why it
- *  is reserved for explicit opt-in steps (`init --with-embeddings`). Throws
- *  when the model cannot be fetched (offline, disabled, package missing);
- *  callers degrade. Loads onnxruntime, so ADR-R001 applies to the caller. */
-export async function downloadEmbeddingModel() {
-    if (localEmbeddingsDisabled())
-        throw new Error('local embeddings are disabled (MONOMIND_NO_LOCAL_EMBEDDINGS=1)');
-    const hf = await import('@huggingface/transformers');
-    await hf.pipeline('feature-extraction', BRIDGE_EMBEDDING_MODEL, {
-        revision: 'main',
-        dtype: 'q8',
-    });
-}
-async function getBackend(dbPath) {
-    const dir = getDbPath(dbPath);
-    let slot = backendSlots.get(dir);
-    if (!slot) {
-        if (backendSlots.size >= MAX_BACKEND_SLOTS) {
-            const oldest = backendSlots.keys().next().value;
-            const evicted = backendSlots.get(oldest);
-            // shutdownBridge() below uses .shutdown() — that's the real method these
-            // backends expose. .close() doesn't exist on either backend class, so this
-            // resolved to undefined via the optional chain every time and never actually
-            // released the connection: every 6th distinct database path opened in this
-            // process leaked the oldest slot's connection for the process lifetime.
-            try {
-                await evicted?.instance?.shutdown?.();
-            }
-            catch (e) {
-                logBridgeError('getBackend.evictedShutdown', e); /* best effort */
-            }
-            backendSlots.delete(oldest);
-        }
-        slot = { promise: null, instance: null, available: null, attempts: 0 };
-        backendSlots.set(dir, slot);
-    }
-    if (slot.available === false)
-        return null;
-    if (slot.attempts >= MAX_INIT_ATTEMPTS) {
-        slot.available = false;
-        return null;
-    }
-    if (slot.instance)
-        return slot.instance;
-    if (!slot.promise) {
-        slot.promise = (async () => {
-            try {
-                const mod = await import('@monoes/memory');
-                await loadEmbedder();
-                // Local SQLite engine (LanceDB replaced 2026-07): better-sqlite3 when its
-                // native binding loads, sql.js (pure WASM) otherwise — both persist text
-                // AND embeddings, so vectors are always recomputable/derivable data.
-                fs.mkdirSync(dir, { recursive: true });
-                // Origin marker: records which project this data dir belongs to, so
-                // `monomind cleanup --data` can verifiably prune dirs whose project
-                // no longer exists (the dir-name hash is one-way). Best-effort; never
-                // written for the global brain (it has no single origin project).
-                if (dir !== getGlobalBrainDir()) {
-                    try {
-                        // MUST be the same path projectDataDir() hashed into the slug. If
-                        // this recorded the raw cwd, running any memory command from a
-                        // package subdirectory would stamp that subdirectory into the
-                        // project-root-keyed dir — and deleting the subdirectory later
-                        // would make `cleanup --data` prune the WHOLE project's brain as
-                        // orphaned.
-                        const originFile = path.join(projectDataDir(), 'origin.json');
-                        fs.writeFileSync(originFile, JSON.stringify({ path: getProjectRoot(), updatedAt: new Date().toISOString() }) +
-                            '\n', 'utf-8');
-                    }
-                    catch (e) {
-                        logBridgeError('getBackend.originWrite', e); /* non-fatal */
-                    }
-                }
-                const cfg = {
-                    databasePath: path.join(dir, 'memory.db'),
-                    walMode: true,
-                    optimize: true,
-                    defaultNamespace: 'default',
-                    embeddingGenerator: _embedder ?? undefined,
-                    // R3: when the MCP server and a CLI hook subprocess hit the same
-                    // memory.db at the same time, SQLite returns SQLITE_BUSY and the
-                    // bridge silently no-ops. busy_timeout tells SQLite to wait up to
-                    // 5s for a lock before giving up, which covers the normal handoff
-                    // window. The native @monoes/memory backend reads this key.
-                    busyTimeoutMs: 5000,
-                };
-                const origLog = console.log;
-                console.log = (...args) => {
-                    const msg = String(args[0] ?? '');
-                    if (msg.includes('Transformers.js') || msg.includes('Loading model'))
-                        return;
-                    origLog.apply(console, args);
-                };
-                let backend;
-                try {
-                    try {
-                        backend = new mod.SQLiteBackend(cfg);
-                        await backend.initialize();
-                    }
-                    catch (e) {
-                        if (process.env.DEBUG || process.env.MONOMIND_DEBUG)
-                            console.error('[memory-bridge] better-sqlite3 unavailable — using sql.js backend:', e);
-                        backend = new mod.SqlJsBackend(cfg);
-                        await backend.initialize();
-                    }
-                }
-                finally {
-                    console.log = origLog;
-                }
-                slot.instance = backend;
-                slot.available = true;
-                return backend;
-            }
-            catch (e) {
-                slot.attempts++;
-                slot.promise = null;
-                if (slot.attempts >= MAX_INIT_ATTEMPTS)
-                    slot.available = false;
-                logBridgeError('getBackend', e);
-                return null;
-            }
-        })();
-    }
-    return slot.promise;
-}
-// ===== Core CRUD =====
-export async function bridgeStoreEntry(options) {
-    const backend = await getBackend(options.dbPath);
-    if (!backend)
-        return null;
-    try {
-        const key = typeof options.key === 'string' && options.key.length > BRIDGE_MAX_KEY_LEN
-            ? options.key.slice(0, BRIDGE_MAX_KEY_LEN)
-            : options.key;
-        if (typeof options.value === 'string' && options.value.length > BRIDGE_MAX_VALUE_LEN) {
-            return {
-                success: false,
-                id: '',
-                error: `Value exceeds the ${BRIDGE_MAX_VALUE_LEN}-character cap (BRIDGE_MAX_VALUE_LEN = 16 KB); got ${options.value.length}. Split the content into smaller entries.`,
-            };
-        }
-        const value = options.value;
-        const namespace = options.namespace ?? 'default';
-        const tags = Array.isArray(options.tags)
-            ? // src: tags carry the ingest source path for excerpt provenance — paths
-                // routinely exceed the general 64-char tag cap, so they get 512.
-                options.tags
-                    .filter((t) => typeof t === 'string' &&
-                    t.length > 0 &&
-                    t.length <= (t.startsWith('src:') ? 512 : MAX_TAG_LEN))
-                    .slice(0, MAX_TAGS)
-            : [];
-        const now = Date.now();
-        // Upsert resolves the EXISTING identity BEFORE minting anything: a
-        // re-ingest must update the row in place and keep the id the caller was
-        // already handed. The old store-new-then-delete-old order silently
-        // orphaned every outstanding reference — feedback against a
-        // previously-returned id then matched nothing and reported
-        // `success: true, applied: 0`, i.e. success while training nothing (K5).
-        let existing = null;
-        if (options.upsert) {
-            try {
-                existing = await backend.getByKey(namespace, key);
-            }
-            catch (e) {
-                logBridgeError('bridgeStoreEntry.upsertLookup', e); /* treat as no existing entry */
-            }
-        }
-        const id = existing?.id ?? generateId('entry');
-        // Generate embedding
-        let embedding;
-        let embeddingInfo;
-        if (options.generateEmbeddingFlag !== false && value.length > 0 && _embedder) {
-            try {
-                embedding = await _embedder(value);
-                embeddingInfo = { dimensions: embedding.length, model: BRIDGE_EMBEDDING_MODEL };
-            }
-            catch (e) {
-                if (process.env.DEBUG || process.env.MONOMIND_DEBUG)
-                    console.error('[memory-bridge] embedding generation failed — storing entry without embedding:', e);
-            }
-        }
-        const mod = await import('@monoes/memory');
-        const entry = mod.createDefaultEntry({
-            key,
-            content: value,
-            namespace,
-            tags,
-            // On a revision the stored metadata merges UNDER the caller's, so
-            // learned signal (feedback_weight, frequency_weight) survives while every
-            // field the caller states explicitly still wins. Same merge semantics the
-            // backend's own update() uses.
-            metadata: existing
-                ? { ...(existing.metadata ?? {}), ...(options.metadata ?? {}) }
-                : options.metadata,
-            expiresAt: options.ttl ? now + options.ttl * 1000 : undefined,
-        });
-        // Override id and set embedding
-        entry.id = id;
-        if (embedding)
-            entry.embedding = embedding;
-        if (existing) {
-            // Carry the record's history forward. createdAt in particular anchors the
-            // entry in the backend's `created_at DESC` ordering: a revision keeps its
-            // position instead of jumping to the head of every scan.
-            entry.createdAt = existing.createdAt;
-            entry.updatedAt = now;
-            entry.version = (existing.version ?? 1) + 1;
-            entry.accessCount = existing.accessCount ?? 0;
-            entry.lastAccessedAt = existing.lastAccessedAt ?? now;
-        }
-        // Dedup gate: skip if a near-duplicate already exists IN THIS NAMESPACE —
-        // an unscoped search let a similar entry in some other namespace swallow
-        // the store entirely (returned duplicate:true, nothing written where asked).
-        const automemCfg = getAutomemConfig();
-        if (embedding && !options.upsert) {
-            try {
-                const similar = await backend.search(embedding, {
-                    k: 1,
-                    threshold: automemCfg.dedupThreshold,
-                    filters: { type: 'exact', namespace },
-                });
-                if (similar.length > 0 && similar[0].score >= automemCfg.dedupThreshold) {
-                    // Re-storing near-identical content is a usage signal: the fact keeps
-                    // being worth remembering. Reinforce the surviving entry.
-                    await recordUsageOnBackend(backend, [similar[0].entry.id]).catch(() => {
-                        /* best effort */
-                    });
-                    return { success: true, id: similar[0].entry.id, duplicate: true };
-                }
-            }
-            catch (e) {
-                logBridgeError('bridgeStoreEntry.dedupSearch', e); /* non-fatal — store anyway */
-            }
-        }
-        // Compare-and-swap path (K5): a caller merging onto a row it read earlier
-        // (or asserting the row is still absent) asks for that check to be part of
-        // the write, atomically, instead of trusting its own stale read.
-        if (options.ifVersion !== undefined) {
-            if (options.ifVersion === 'absent') {
-                if (existing)
-                    return {
-                        success: false,
-                        id: existing.id,
-                        conflict: true,
-                        error: 'ifVersion=absent but entry already exists',
-                    };
-                const created = typeof backend.storeIfAbsent === 'function' ? await backend.storeIfAbsent(entry) : null;
-                if (created === null) {
-                    // Backend predates storeIfAbsent (or is a test double) — fall back to
-                    // the plain unconditional write rather than fail every caller.
-                    await backend.store(entry);
-                }
-                else if (!created) {
-                    return { success: false, id: '', conflict: true, error: 'entry created concurrently' };
-                }
-            }
-            else {
-                if (!existing)
-                    return { success: false, id: '', conflict: true, error: 'entry no longer exists' };
-                const written = typeof backend.storeIfVersion === 'function'
-                    ? await backend.storeIfVersion(entry, options.ifVersion)
-                    : null;
-                if (written === null) {
-                    await backend.store(entry);
-                }
-                else if (!written) {
-                    return {
-                        success: false,
-                        id,
-                        conflict: true,
-                        error: `version conflict: entry changed concurrently (expected version ${options.ifVersion})`,
-                    };
-                }
-            }
-            await flushBackend(backend);
-            return { success: true, id, embedding: embeddingInfo };
-        }
-        // store() is INSERT OR REPLACE keyed on id, so reusing the existing id
-        // rewrites that row in place — there is no old row left to delete, and no
-        // window in which a failed store leaves the previous data destroyed.
-        await backend.store(entry);
-        await flushBackend(backend);
-        return { success: true, id, embedding: embeddingInfo };
-    }
-    catch (err) {
-        logBridgeError('bridgeStoreEntry', err);
-        const message = err instanceof Error ? err.message : String(err);
-        return { success: false, id: '', error: message };
-    }
-}
-export async function bridgeSearchEntries(options) {
-    const backend = await getBackend(options.dbPath);
-    if (!backend)
-        return null;
-    try {
-        const { query: queryStr, limit = 10, threshold = 0.3 } = options;
-        // CLI callers pass 'all' as a no-filter sentinel — never treat it as a literal namespace
-        const namespace = options.namespace && options.namespace !== 'all' ? options.namespace : undefined;
-        const startTime = Date.now();
-        // ── Knowledge removal support (issue #106) ──────────────────────
-        // Pre-compute live document hashes for knowledge namespaces so we can
-        // (a) over-fetch to compensate for superseded entries being filtered,
-        // (b) filter them out after retrieval — ensuring removed documents
-        //     are invisible to EVERY caller, not just searchKnowledge.
-        // Dynamic import breaks the circular dependency: document-pipeline
-        // imports getProjectRoot from this module.
-        let _knowledgeLive = null;
-        let _knowledgeHasMeta = false;
-        let _isSupersededKey = null;
-        const knowledgeFilterActive = namespace?.startsWith('knowledge:') && !options.includeSuperseded;
-        if (knowledgeFilterActive) {
-            try {
-                const dp = await import('../knowledge/document-pipeline.js');
-                const rootDir = options.dbPath === GLOBAL_BRAIN
-                    ? getGlobalBrainDir()
-                    : (options.rootDir ?? getProjectRoot());
-                _knowledgeLive = dp.liveContentHashes(rootDir);
-                _knowledgeHasMeta = dp.hasKnowledgeMetadata(rootDir);
-                _isSupersededKey = dp.isSupersededKey;
-            }
-            catch (e) {
-                logBridgeError('bridgeSearchEntries.knowledgeFilter', e); /* non-fatal: skip filtering when pipeline is unavailable */
-            }
-        }
-        // Over-retrieve when the reranker is available: fetch more candidates so the
-        // cross-encoder can reshuffle them. The reranker trims back to `limit`.
-        // For knowledge namespaces, also over-fetch to compensate for superseded
-        // document versions that will be filtered out below.
-        const rerankerActive = !options.skipRerank && _reranker !== null && !rerankerDisabled();
-        const knowledgeLimit = _knowledgeLive && _knowledgeLive.size > 0
-            ? Math.min(Math.max(limit * 20, limit), 300)
-            : limit;
-        const retrieveK = rerankerActive
-            ? Math.min(knowledgeLimit * 3, Math.max(20, knowledgeLimit))
-            : knowledgeLimit;
-        let results = [];
-        let searchMethod = 'keyword';
-        // Reported to callers so "(semantic)" can never be printed over keyword hits.
-        // The two reasons for skipping the vector path are distinct and must not be
-        // conflated: a healthy model given an empty query is not a missing model.
-        let fallbackReason = !_embedder
-            ? 'no-embedding-model'
-            : queryStr.length === 0
-                ? 'empty-query'
-                : undefined;
-        let semanticAttempted = false;
-        if (_embedder && queryStr.length > 0) {
-            semanticAttempted = true;
-            try {
-                const queryEmbedding = await _embedder(queryStr);
-                const searchResults = await backend.search(queryEmbedding, {
-                    k: retrieveK,
-                    threshold,
-                    filters: namespace ? { type: 'exact', namespace } : undefined,
-                });
-                const { feedbackInfluence } = getAutomemConfig();
-                results = searchResults
-                    .map((r) => {
-                    const weights = entryWeights(r.entry.metadata);
-                    // Blend only here (semantic path): r.score is a genuine cosine similarity.
-                    const blended = blendScore(r.score, weights, feedbackInfluence);
-                    return {
-                        id: r.entry.id,
-                        key: r.entry.key,
-                        content: capResultContent(r.entry.content || ''),
-                        score: blended,
-                        namespace: r.entry.namespace,
-                        provenance: `semantic:${r.score.toFixed(3)}${blended !== r.score ? `→${blended.toFixed(3)}` : ''}`,
-                        tags: r.entry.tags ?? [],
-                        _createdAt: r.entry.createdAt || 0,
-                    };
-                })
-                    .sort((a, b) => b.score - a.score);
-                searchMethod = 'semantic';
-                fallbackReason = undefined;
-            }
-            catch (e) {
-                // fall through to keyword search — but never claim this was semantic
-                fallbackReason = 'embedding-failed';
-                if (process.env.DEBUG || process.env.MONOMIND_DEBUG)
-                    console.error('[memory-bridge] semantic search failed — falling back to keyword matching:', e);
-            }
-        }
-        // Keyword search — always runs (not just as a fallback).
-        // Entries stored without embeddings are invisible to the vector path,
-        // so keyword results are merged into semantic results (union, deduplicated
-        // by key) to ensure every findable entry surfaces regardless of whether
-        // it has an embedding.  Semantic hits take priority on score.
-        //
-        // Issue #66: When the backend has FTS5, keyword matching runs inside
-        // SQLite via MATCH — orders of magnitude faster than the old path that
-        // loaded up to 50k rows and scanned them in JS. The JS fallback is
-        // kept for sql.js WASM builds that lack the FTS5 extension.
-        {
-            const tokens = queryStr
-                .toLowerCase()
-                .split(/[^a-z0-9]+/)
-                .filter((t) => t.length > 1);
-            let keywordHits = [];
-            if (tokens.length) {
-                // ── FTS5 fast path ──────────────────────────────────────────
-                const fts5Results = typeof backend.keywordSearch === 'function'
-                    ? await backend.keywordSearch(queryStr, { namespace, limit }).catch(() => null)
-                    : null;
-                if (fts5Results !== null && fts5Results.length > 0) {
-                    // FTS5 rank is negative (lower = better); normalise to 0–1 against
-                    // the BEST (largest-magnitude) result, not a hard floor of 1
-                    // (issue #224). BM25 IDF goes to zero/negative when a query term
-                    // appears in most or all of the matched rows — a small or
-                    // lexically-homogeneous result set (a duplicated FTS row for one
-                    // entry, per sql-schema.ts's `ensureFTS5Triggers`, was one way to
-                    // reach exactly this) — so a genuinely-best (or sole) match can
-                    // legitimately have |rank| < 1. A hard `Math.max(…,
-                    // 1)` floor then divides that down toward 0, displaying the
-                    // correct top match as ~0.00 instead of its best-available 1.0.
-                    // Mirrors the identical fix already applied to the JS BM25
-                    // fallback below (#126-review): only fall back to a floor of 1
-                    // when every rank is genuinely 0 (nothing to normalise against),
-                    // never merely because the raw magnitude is under 1.
-                    const rawMaxRank = Math.max(...fts5Results.map((r) => Math.abs(r.rank)));
-                    const maxRank = rawMaxRank > 0 ? rawMaxRank : 1;
-                    keywordHits = fts5Results.map((r) => {
-                        const score = rawMaxRank > 0 ? Math.abs(r.rank) / maxRank : 1;
-                        return {
-                            id: r.id,
-                            key: r.key,
-                            content: capResultContent(r.content || ''),
-                            score,
-                            namespace: r.namespace,
-                            provenance: `keyword-fts5:${score.toFixed(2)}`,
-                            tags: [],
-                            _createdAt: 0,
-                        };
-                    });
-                }
-                else {
-                    // ── JS fallback (no FTS5 or empty FTS5 result) ────────────
-                    const entries = await backend.query({
-                        type: 'exact',
-                        ...(namespace ? { namespace } : {}),
-                        limit: 50000,
-                    });
-                    // #126: Bm25Index.build() costs real time at scale (measured in
-                    // bm25-index.ts's own header: ~113ms/673 chunks, ~1.7s/12.5k
-                    // chunks) — this fallback can be handed up to 50,000 entries, so
-                    // building a fresh index on every call without a cap would make
-                    // large stores' searches slower, not better. Below the cap, BM25
-                    // (proper IDF weighting) replaces the naive token-overlap-fraction
-                    // scan; above it, the fast scan keeps running so latency never
-                    // regresses. MONOMIND_BM25=0 disables this arm entirely (mirrors
-                    // the MONOMIND_RERANKER kill-switch).
-                    const BM25_ENTRY_CAP = 1500;
-                    const bm25Enabled = (process.env.MONOMIND_BM25 ?? '1') !== '0';
-                    let bm25Ok = false;
-                    if (bm25Enabled && entries.length > 0 && entries.length <= BM25_ENTRY_CAP) {
-                        try {
-                            const { Bm25Index } = await import('./bm25-index.js');
-                            // #126-review: index by the entry's ARRAY POSITION, not e.key —
-                            // memory_entries only enforces UNIQUE(namespace, key), so a bare
-                            // key string can legitimately repeat across namespaces (e.g. two
-                            // agents each storing a 'summary' key in their own namespace).
-                            // Keying by e.key alone collided in that case: every BM25 hit
-                            // sharing that key string resolved to whichever entry happened
-                            // to be inserted last into the lookup map, silently returning
-                            // the wrong entry's id/content/namespace.
-                            const chunks = entries.map((e, i) => ({
-                                key: String(i),
-                                text: `${e.key || ''} ${e.content || ''}`,
-                            }));
-                            const idx = Bm25Index.build(chunks, () => false); // no superseded concept at this generic KV level — filtered later by callers that care
-                            const hits = idx.search(queryStr, limit);
-                            // #126-review: Math.max(..., 1) as a divide-by-zero guard also
-                            // silently floors the normalization divisor whenever every real
-                            // score is < 1 (common for small/sparse corpora — exactly the
-                            // regime this capped fallback runs in), so the top hit stopped
-                            // normalizing to 1.0 as the comment below claims. Only fall
-                            // back to 1 when there is no positive score to divide by.
-                            const rawMax = hits.length ? Math.max(...hits.map((h) => h.score)) : 0;
-                            const maxScore = rawMax > 0 ? rawMax : 1;
-                            keywordHits = hits.map((h) => {
-                                const e = entries[Number(h.key)];
-                                const normalized = h.score / maxScore; // BM25 scores aren't comparable across queries/corpora — normalise 0-1 like the FTS5 path does
-                                return {
-                                    id: e.id,
-                                    key: e.key,
-                                    content: capResultContent(e.content || ''),
-                                    score: normalized,
-                                    namespace: e.namespace,
-                                    provenance: `keyword-bm25:${normalized.toFixed(2)}`,
-                                    tags: e.tags ?? [],
-                                    _createdAt: e.createdAt || 0,
-                                };
-                            });
-                            bm25Ok = true;
-                        }
-                        catch (e) {
-                            // #126-review: BM25 build/search had no local try/catch, unlike
-                            // every other sub-path in this function — an exception here
-                            // used to propagate to the function's single outer catch,
-                            // discarding the whole call (including already-computed
-                            // semantic results) instead of degrading to the naive scan
-                            // below, which is what every other keyword-path failure does.
-                            if (process.env.DEBUG || process.env.MONOMIND_DEBUG)
-                                console.error('[memory-bridge] BM25 keyword search failed — falling back to token-overlap scan:', e);
-                        }
-                    }
-                    if (!bm25Ok) {
-                        keywordHits = entries
-                            .map((e) => {
-                            const haystack = `${e.key || ''} ${e.content || ''}`.toLowerCase();
-                            const hits = tokens.filter((t) => haystack.includes(t)).length;
-                            return { e, score: hits / tokens.length };
-                        })
-                            .filter((x) => x.score > 0)
-                            .sort((a, b) => b.score - a.score)
-                            .slice(0, limit)
-                            .map(({ e, score }) => ({
-                            id: e.id,
-                            key: e.key,
-                            content: capResultContent(e.content || ''),
-                            // Raw token-overlap fraction, NOT rescaled to look like a cosine.
-                            score,
-                            namespace: e.namespace,
-                            provenance: `keyword:${score.toFixed(2)}`,
-                            tags: e.tags ?? [],
-                            _createdAt: e.createdAt || 0,
-                        }));
-                    }
-                }
-                // Issue #223/#224 follow-up: FTS5/BM25 ranks above are normalised
-                // RELATIVE to the best result in this call's own small candidate set
-                // (score = |rank| / maxRank), so the top — or sole — hit always
-                // lands at ~1.0 by construction, no matter how weak the actual
-                // match is. `options.threshold` compared against that already-
-                // inflated score can never reject a top/sole hit, so a single
-                // coincidental partial-token overlap looks exactly as confident as
-                // a genuine strong match. Gate on independent evidence instead: how
-                // much of the QUERY the candidate actually covers. This can only
-                // narrow the result set (never rescue something already excluded),
-                // and doesn't touch the rank-normalisation math other callers rely on.
-                keywordHits = keywordHits.filter((h) => {
-                    if (h.score < threshold)
-                        return false;
-                    const haystack = `${h.key || ''} ${h.content || ''}`.toLowerCase();
-                    const matchedFraction = tokens.filter((t) => haystack.includes(t)).length / tokens.length;
-                    return matchedFraction >= threshold;
-                });
-                if (results.length === 0) {
-                    // No semantic results — keyword is all we have.
-                    results = keywordHits;
-                    searchMethod = semanticAttempted ? 'keyword-fallback' : 'keyword';
-                    if (semanticAttempted && !fallbackReason)
-                        fallbackReason = 'no-semantic-matches';
-                }
-                else {
-                    // Merge: union deduplicated by key, semantic wins on duplicates.
-                    // Extras are flagged _keywordOnly so the reranking step below can
-                    // skip them — the cross-encoder scores r.content, and an entry
-                    // findable ONLY by keyword (e.g. a placeholder/near-empty content
-                    // whose relevance lives in the key) reranks as noise and gets
-                    // sliced off by the final `limit`, silently defeating the whole
-                    // point of merging it in. Guaranteed inclusion has to survive
-                    // reranking, not just the merge.
-                    const seenKeys = new Set(results.map((r) => r.key));
-                    const extras = keywordHits.filter((kh) => !seenKeys.has(kh.key));
-                    if (extras.length) {
-                        results = [...results, ...extras.map((e) => ({ ...e, _keywordOnly: true }))];
-                        // searchMethod stays 'semantic' — the primary path succeeded;
-                        // keyword only supplemented entries that lacked embeddings.
-                    }
-                }
-            }
-            else if (results.length === 0) {
-                // Empty token list AND no semantic results — nothing to search.
-                searchMethod = semanticAttempted ? 'keyword-fallback' : 'keyword';
-                if (semanticAttempted && !fallbackReason)
-                    fallbackReason = 'no-semantic-matches';
-            }
-        }
-        // Filter stale entries based on automem config — skip for knowledge
-        // namespaces (documents should remain searchable indefinitely)
-        // Stale filtering is per-RESULT namespace (documents stay searchable
-        // forever) — keying it on the query's namespace filter meant an
-        // all-namespace search silently dropped knowledge:* results past the
-        // stale cutoff.
-        // org:* (cross-run org memory) and rules are durable learned state like
-        // documents — the stale cliff silently erased org recall after a week.
-        const durableNs = (ns) => ns.startsWith('knowledge:') ||
-            ns.startsWith('org:') ||
-            ns.startsWith('agent:') ||
-            ns.startsWith('kg:') ||
-            ns === 'rules';
-        const isKnowledgeNs = namespace ? durableNs(namespace) : false;
-        if (!isKnowledgeNs) {
-            const { staleDays } = getAutomemConfig();
-            const staleCutoff = Date.now() - staleDays * 86400000;
-            results = results.filter((r) => durableNs(String(r.namespace ?? '')) || !r._createdAt || r._createdAt > staleCutoff);
-        }
-        results.forEach((r) => delete r._createdAt);
-        // ── Knowledge superseded filtering (issue #106) ─────────────────
-        // Remove document chunks whose content hash is no longer current
-        // (i.e. the document was removed via `knowledge_remove` or replaced
-        // by a newer ingest). This runs inside the bridge so every caller —
-        // embeddings_search, CLI `memory search`, and searchKnowledge — gets
-        // the same removal guarantee.
-        if (_knowledgeLive && _isSupersededKey && results.length > 0) {
-            results = results.filter((r) => !_isSupersededKey?.(String(r.key ?? ''), _knowledgeLive, _knowledgeHasMeta));
-            // Trim back to the originally requested limit after overfetch — but
-            // never let this blind size-based cut drop a _keywordOnly extra (see
-            // the merge above): reserve its slot and trim the rest first.
-            if (results.length > limit) {
-                const extras = results.filter((r) => r._keywordOnly);
-                const main = results.filter((r) => !r._keywordOnly);
-                const keep = Math.max(0, limit - extras.length);
-                results = [...main.slice(0, keep), ...extras.slice(0, limit)];
-            }
-        }
-        // Keyword-only extras are guaranteed to survive to the final result —
-        // pull them out before reranking so the cross-encoder (which scores
-        // r.content only) can't outrank them into oblivion, then reserve their
-        // slots when re-merging below.
-        const keywordOnlyResults = results.filter((r) => r._keywordOnly);
-        let rerankPool = results.filter((r) => !r._keywordOnly);
-        // ── Cross-encoder reranking ──────────────────────────────────────
-        // Fires only when: reranker loaded, >1 result, not explicitly skipped.
-        // Lazy-load on first qualifying search so startup stays fast.
-        let reranked = false;
-        if (!options.skipRerank && !rerankerDisabled() && rerankPool.length > 1) {
-            if (!_reranker && !_rerankerPromise) {
-                // First qualifying search — kick off the lazy load. This search
-                // proceeds without reranking; the NEXT search will use it.
-                loadReranker().catch(() => {
-                    /* swallowed — retry next time */
-                });
-            }
-            if (_reranker) {
-                const rr = await rerankResults(queryStr, rerankPool, limit);
-                rerankPool = rr.reranked;
-                reranked = rr.applied;
-            }
-        }
-        if (keywordOnlyResults.length) {
-            const keep = Math.max(0, limit - keywordOnlyResults.length);
-            results = [...rerankPool.slice(0, keep), ...keywordOnlyResults.slice(0, limit)];
-        }
-        else {
-            results = rerankPool;
-        }
-        results.forEach((r) => delete r._keywordOnly);
-        return {
-            success: true,
-            results,
-            searchTime: Date.now() - startTime,
-            searchMethod,
-            reranked,
-            ...(searchMethod === 'semantic' ? {} : { fallbackReason }),
-        };
-    }
-    catch (e) {
-        logBridgeError('bridgeSearchEntries', e);
-        return null;
-    }
-}
-export async function bridgeListEntries(options) {
-    const backend = await getBackend(options.dbPath);
-    if (!backend)
-        return null;
-    try {
-        const entries = await backend.query({
-            type: 'exact',
-            // No namespace means "all namespaces" — the query builder (sql-backend.ts)
-            // already skips its filter clause on a falsy namespace. Defaulting to the
-            // literal string 'default' here (as this used to) overrode that legitimate
-            // "no filter" signal and silently scoped every unfiltered list/search to a
-            // namespace that's usually near-empty in practice.
-            namespace: options.namespace,
-            limit: options.limit ?? 100,
-            offset: options.offset,
-        });
-        return {
-            success: true,
-            entries: entries.map((e) => ({
-                id: e.id,
-                key: e.key,
-                namespace: e.namespace,
-                content: e.content,
-                accessCount: e.accessCount ?? 0,
-                createdAt: new Date(e.createdAt).toISOString(),
-                updatedAt: new Date(e.updatedAt).toISOString(),
-                hasEmbedding: !!(e.embedding && e.embedding.length > 0),
-                tags: e.tags ?? [],
-                metadata: e.metadata ?? {},
-            })),
-            total: entries.length,
-        };
-    }
-    catch (e) {
-        logBridgeError('bridgeListEntries', e);
-        return null;
-    }
-}
-/** A real database count for one namespace — `SELECT COUNT(*) WHERE
- *  namespace = ?` against the existing `idx_namespace` index — as opposed to
- *  `bridgeListEntries.total`, which is only the returned page's length (K7:
- *  "bridgeListEntries.total is the returned page length, not a database
- *  count"). Every row in a KG namespace (`kg:nodes`, `kg:edges`, `rules`) is
- *  exactly one node/edge/rule — the name/adjacency index namespaces are
- *  separate — so this count needs no per-row filtering to be exact, and costs
- *  one indexed query instead of paging the whole namespace.
- *
- *  @returns null when the backend is unavailable, or when the loaded backend
- *  predates `count()` — callers fall back to the paginated scan they already
- *  had rather than fail. */
-export async function bridgeCountEntries(namespace, dbPath) {
-    const backend = await getBackend(dbPath);
-    if (!backend || typeof backend.count !== 'function')
-        return null;
-    try {
-        return await backend.count(namespace);
-    }
-    catch (e) {
-        logBridgeError('bridgeCountEntries', e);
-        return null;
-    }
-}
-export async function bridgeGetEntry(options) {
-    const backend = await getBackend(options.dbPath);
-    if (!backend)
-        return null;
-    try {
-        const { key, namespace = 'default' } = options;
-        const entry = await backend.getByKey(namespace, key);
-        if (!entry)
-            return { success: true, found: false };
-        return {
-            success: true,
-            found: true,
-            entry: {
-                id: entry.id,
-                key: entry.key,
-                namespace: entry.namespace,
-                content: entry.content,
-                accessCount: entry.accessCount ?? 0,
-                createdAt: new Date(entry.createdAt).toISOString(),
-                updatedAt: new Date(entry.updatedAt).toISOString(),
-                hasEmbedding: !!(entry.embedding && entry.embedding.length > 0),
-                tags: entry.tags ?? [],
-                metadata: entry.metadata ?? {},
-                ...(typeof entry.version === 'number' ? { version: entry.version } : {}),
-            },
-        };
-    }
-    catch (e) {
-        logBridgeError('bridgeGetEntry', e);
-        return null;
-    }
-}
-export async function bridgeDeleteEntry(options) {
-    const backend = await getBackend(options.dbPath);
-    if (!backend)
-        return null;
-    try {
-        const namespace = options.namespace ?? 'default';
-        let deleted = false;
-        if (options.id) {
-            deleted = await backend.delete(options.id);
-        }
-        else if (options.key) {
-            const entry = await backend.getByKey(namespace, options.key);
-            if (entry)
-                deleted = await backend.delete(entry.id);
-        }
-        if (deleted)
-            await flushBackend(backend);
-        return { success: true, deleted };
-    }
-    catch (e) {
-        logBridgeError('bridgeDeleteEntry', e);
-        return { success: false, deleted: false };
-    }
-}
-// ===== Embeddings =====
-export async function bridgeGenerateEmbedding(text, dbPath) {
-    await getBackend(dbPath); // ensure embedder is initialized
-    if (!_embedder)
-        return null;
-    try {
-        const emb = await _embedder(text);
-        return { embedding: Array.from(emb), dimensions: emb.length, model: BRIDGE_EMBEDDING_MODEL };
-    }
-    catch (e) {
-        logBridgeError('bridgeEmbedText', e);
-        return null;
-    }
-}
-export async function bridgeLoadEmbeddingModel(dbPath) {
-    const startTime = Date.now();
-    await getBackend(dbPath);
-    if (!_embedder)
-        return null;
-    try {
-        const test = await _embedder('test');
-        if (!test)
-            return null;
-        return {
-            success: true,
-            dimensions: test.length,
-            modelName: BRIDGE_EMBEDDING_MODEL,
-            loadTime: Date.now() - startTime,
-        };
-    }
-    catch (e) {
-        logBridgeError('bridgeLoadEmbeddingModel', e);
-        return null;
-    }
-}
-export async function bridgeGetBackendStats(dbPath) {
-    const backend = await getBackend(dbPath);
-    if (!backend)
-        return null;
-    try {
-        const stats = await backend.getStats();
-        return {
-            totalEntries: stats?.totalEntries ?? 0,
-            entriesByNamespace: stats?.entriesByNamespace ?? {},
-            memoryUsage: stats?.memoryUsage ?? 0,
-        };
-    }
-    catch (e) {
-        logBridgeError('bridgeGetBackendStats', e);
-        return null;
-    }
-}
-// ===== HNSW (real ANN status/build; search itself runs inside SqlBackend.search()) =====
-export async function bridgeAddToHNSW(options) {
-    // The SQLite backend indexes entries automatically on store — this is a no-op
-    const backend = await getBackend(options.dbPath);
-    if (!backend)
-        return null;
-    try {
-        const stats = await backend.getStats();
-        return { success: true, indexSize: stats?.totalEntries ?? 0 };
-    }
-    catch (e) {
-        logBridgeError('bridgeAddToHNSW', e);
-        return { success: true };
-    }
-}
-/**
- * Real status for the ANN (HNSW) fast path inside SqlBackend.search() —
- * whether the corpus is big enough to use it, whether it's currently built,
- * and where its on-disk cache lives. Read-only; does not build anything.
- */
-export async function bridgeGetHNSWStatus(dbPath) {
-    const backend = await getBackend(dbPath);
-    if (!backend || typeof backend.getAnnStatus !== 'function')
-        return null;
-    try {
-        return { available: true, ...backend.getAnnStatus() };
-    }
-    catch (e) {
-        logBridgeError('bridgeGetHNSWStatus', e);
-        return null;
-    }
-}
-/**
- * Force-build (or reload from disk cache) the ANN index regardless of
- * MONOMIND_HNSW_THRESHOLD — the real implementation behind
- * `memory search --build-hnsw`.
- */
-export async function bridgeForceBuildHNSW(dbPath) {
-    const backend = await getBackend(dbPath);
-    if (!backend || typeof backend.forceBuildAnnIndex !== 'function')
-        return null;
-    try {
-        return await backend.forceBuildAnnIndex(BRIDGE_EMBEDDING_DIMS);
-    }
-    catch (e) {
-        logBridgeError('bridgeForceBuildHNSW', e);
-        return null;
-    }
-}
-// ===== Availability / lifecycle =====
-export async function isBridgeAvailable(dbPath) {
-    const backend = await getBackend(dbPath);
-    return !!backend;
-}
-export async function shutdownBridge() {
-    for (const slot of backendSlots.values()) {
-        if (slot.instance) {
-            try {
-                await slot.instance.shutdown();
-            }
-            catch (e) {
-                logBridgeError('bridgeShutdown.slotShutdown', e); /* ignore */
-            }
-        }
-    }
-    backendSlots.clear();
-    _embedder = null;
-    _embedderPromise = null;
-    _reranker = null;
-    _rerankerPromise = null;
-}
+import { flushBackend, getBackend } from './memory-bridge-backend.js';
+import { capResultContent, entryWeights, generateId, logBridgeError, } from './memory-bridge-core.js';
+import { bridgeDeleteEntry } from './memory-bridge-entries.js';
+import { bridgeSearchEntries } from './memory-bridge-search.js';
+import { bridgeStoreEntry } from './memory-bridge-store.js';
+export { BRIDGE_RERANKER_MODEL, disableLocalModels, downloadEmbeddingModel, isBridgeAvailable, loadReranker, localEmbeddingsDisabled, rerankerDisabled, rerankerKind, rerankerModelsDir, shutdownBridge, } from './memory-bridge-backend.js';
+export { BRIDGE_EMBEDDING_DIMS, BRIDGE_EMBEDDING_MODEL, safeParseEmbedding, } from './memory-bridge-core.js';
+export { bridgeAddToHNSW, bridgeCountEntries, bridgeDeleteEntry, bridgeForceBuildHNSW, bridgeGenerateEmbedding, bridgeGetBackendStats, bridgeGetEntry, bridgeGetHNSWStatus, bridgeListEntries, bridgeLoadEmbeddingModel, } from './memory-bridge-entries.js';
+export { bridgeApplyFeedback, bridgeRecordFeedback, bridgeRecordUsage, } from './memory-bridge-feedback.js';
+export { bridgeGetDbPath, GLOBAL_BRAIN, getGlobalBrainDir, getProjectRoot, getProjectRootResolution, } from './memory-bridge-paths.js';
+export { bridgeSearchEntries } from './memory-bridge-search.js';
+export { bridgeLatestSession, bridgeSessionEnd, bridgeSessionStart, } from './memory-bridge-sessions.js';
+export { bridgeStoreEntry } from './memory-bridge-store.js';
 // ===== Pattern store =====
 export async function bridgeStorePattern(options) {
     return bridgeStoreEntry({
@@ -1607,139 +67,6 @@ export async function bridgeSearchPatterns(options) {
         }),
     };
 }
-async function recordUsageOnBackend(backend, entryIds) {
-    let updated = 0;
-    const skipped = [];
-    for (const id of entryIds) {
-        if (typeof id !== 'string' || !id)
-            continue;
-        try {
-            const entry = await backend.get(id);
-            if (!entry) {
-                skipped.push({ id, reason: 'not_found' });
-                continue;
-            }
-            const { frequency } = entryWeights(entry.metadata);
-            await backend.update(id, {
-                metadata: { frequency_weight: frequency + 1 },
-                lastAccessedAt: Date.now(),
-            });
-            updated++;
-        }
-        catch (e) {
-            logBridgeError('recordUsageOnBackend.entryUpdate', e);
-            skipped.push({ id, reason: 'error' });
-        }
-    }
-    return { updated, skipped };
-}
-/** Record that these entries were actually USED (returned to and consumed by a
- *  caller) — increments frequency_weight, which feeds the ranking blend.
- *
- *  Unresolvable ids are REPORTED, not dropped: this used to `continue` past
- *  every id it could not read, so a caller handing it a page of stale ids got
- *  `{success: true, updated: 0}` with nothing to say whether those entries had
- *  been deleted or the writes had failed. Same contract as
- *  `bridgeApplyFeedback`. */
-export async function bridgeRecordUsage(options) {
-    const backend = await getBackend(options.dbPath);
-    if (!backend)
-        return null;
-    try {
-        const { updated, skipped } = await recordUsageOnBackend(backend, (options.entryIds ?? []).slice(0, 100));
-        if (updated)
-            await flushBackend(backend);
-        return skipped.length ? { success: true, updated, skipped } : { success: true, updated };
-    }
-    catch (e) {
-        logBridgeError('bridgeRecordUsage', e);
-        return { success: false, updated: 0 };
-    }
-}
-/** Apply a usefulness rating to the entries that produced an answer:
- *  EWMA feedback_weight' = w + alpha*(score - w), clipped [0,1] (cognee's
- *  apply_feedback_weights). `ledgerKey` makes application idempotent — a
- *  daemon retry or duplicate MCP call must never compound the update. */
-export async function bridgeApplyFeedback(options) {
-    const backend = await getBackend(options.dbPath);
-    if (!backend)
-        return null;
-    try {
-        const score = Math.max(0, Math.min(1, options.score));
-        const alpha = typeof options.alpha === 'number'
-            ? Math.max(0, Math.min(1, options.alpha))
-            : FEEDBACK_EWMA_ALPHA;
-        const ledgerEntryKey = options.ledgerKey ? `applied_${options.ledgerKey.slice(0, 500)}` : null;
-        if (ledgerEntryKey) {
-            const existing = await backend.getByKey('feedback', ledgerEntryKey).catch(() => null);
-            if (existing)
-                return { success: true, applied: 0, alreadyApplied: true };
-        }
-        let applied = 0;
-        const skipped = [];
-        for (const id of (options.entryIds ?? []).slice(0, 100)) {
-            if (typeof id !== 'string' || !id)
-                continue;
-            try {
-                const entry = await backend.get(id);
-                if (!entry) {
-                    skipped.push({ id, reason: 'not_found' });
-                    continue;
-                }
-                const { feedback } = entryWeights(entry.metadata);
-                const next = Math.max(0, Math.min(1, feedback + alpha * (score - feedback)));
-                await backend.update(id, { metadata: { feedback_weight: next } });
-                applied++;
-            }
-            catch (e) {
-                logBridgeError('bridgeApplyFeedback.entryUpdate', e);
-                skipped.push({ id, reason: 'error' });
-            }
-        }
-        if (ledgerEntryKey) {
-            await bridgeStoreEntry({
-                key: ledgerEntryKey,
-                value: JSON.stringify({
-                    score,
-                    entryIds: options.entryIds.slice(0, 100),
-                    appliedAt: Date.now(),
-                    applied,
-                    skipped,
-                }),
-                namespace: 'feedback',
-                generateEmbeddingFlag: false,
-                dbPath: options.dbPath,
-                upsert: true,
-            });
-        }
-        if (applied)
-            await flushBackend(backend);
-        return skipped.length ? { success: true, applied, skipped } : { success: true, applied };
-    }
-    catch (err) {
-        logBridgeError('bridgeApplyFeedback', err);
-        const message = err instanceof Error ? err.message : String(err);
-        return { success: false, applied: 0, error: message };
-    }
-}
-// ===== Feedback =====
-export async function bridgeRecordFeedback(options) {
-    return bridgeStoreEntry({
-        key: `feedback_${options.taskType}_${Date.now()}`,
-        value: JSON.stringify({
-            taskType: options.taskType,
-            action: options.action,
-            outcome: options.outcome,
-            confidence: options.confidence ?? 0.5,
-            metadata: options.metadata ?? {},
-            recordedAt: Date.now(),
-        }),
-        namespace: 'feedback',
-        tags: [options.taskType, options.outcome],
-        generateEmbeddingFlag: true,
-        dbPath: options.dbPath,
-    });
-}
 // ===== Causal edges =====
 export async function bridgeRecordCausalEdge(options) {
     return bridgeStoreEntry({
@@ -1757,106 +84,6 @@ export async function bridgeRecordCausalEdge(options) {
         upsert: true,
     });
 }
-// ===== Session lifecycle =====
-export async function bridgeSessionStart(options) {
-    return bridgeStoreEntry({
-        key: `session_${options.sessionId}`,
-        value: JSON.stringify({
-            sessionId: options.sessionId,
-            agentId: options.agentId,
-            startedAt: Date.now(),
-            status: 'active',
-            metadata: options.metadata ?? {},
-        }),
-        namespace: 'sessions',
-        tags: ['session', 'active'],
-        generateEmbeddingFlag: false,
-        dbPath: options.dbPath,
-        upsert: true,
-    });
-}
-export async function bridgeSessionEnd(options) {
-    const backend = await getBackend(options.dbPath);
-    if (!backend)
-        return null;
-    try {
-        const existing = await backend.getByKey('sessions', `session_${options.sessionId}`);
-        // Nothing is written for a session that was never started — do not report
-        // that as a recorded session end.
-        if (!existing)
-            return { success: false, error: `no session ${options.sessionId} to end` };
-        let data = {};
-        try {
-            data = JSON.parse(existing.content);
-        }
-        catch (e) {
-            if (process.env.DEBUG || process.env.MONOMIND_DEBUG)
-                console.error('[memory-bridge] session content failed to parse — ending session with empty prior state:', e);
-        }
-        const updated = await backend.update(existing.id, {
-            content: JSON.stringify({
-                ...data,
-                status: 'ended',
-                endedAt: Date.now(),
-                summary: options.summary,
-                metrics: options.metrics ?? {},
-            }),
-            tags: ['session', 'ended'],
-        });
-        if (!updated)
-            return { success: false, error: `session ${options.sessionId} vanished` };
-        await flushBackend(backend);
-        return { success: true };
-    }
-    catch (e) {
-        logBridgeError('bridgeSessionEnd', e);
-        return { success: false };
-    }
-}
-/** The most recently started session recorded by bridgeSessionStart, read
- *  back from its row — or null when there is none (or no backend). */
-export async function bridgeLatestSession(options) {
-    const backend = await getBackend(options.dbPath);
-    if (!backend)
-        return null;
-    try {
-        // Newest two rows: one of them may be the excluded (current) session.
-        const rows = await backend.query({
-            type: 'exact',
-            namespace: 'sessions',
-            keyPrefix: 'session_',
-            sortField: 'createdAt',
-            sortDirection: 'desc',
-            limit: 2,
-        });
-        for (const row of rows) {
-            let data;
-            try {
-                data = JSON.parse(row.content);
-            }
-            catch {
-                continue;
-            }
-            if (typeof data?.sessionId !== 'string' || data.sessionId === options.excludeSessionId)
-                continue;
-            return {
-                sessionId: data.sessionId,
-                status: typeof data.status === 'string' ? data.status : 'unknown',
-                startedAt: new Date(data.startedAt ?? row.createdAt).toISOString(),
-                ...(typeof data.endedAt === 'number'
-                    ? { endedAt: new Date(data.endedAt).toISOString() }
-                    : {}),
-                ...(typeof data.summary === 'string' ? { summary: data.summary } : {}),
-                ...(data.metrics && typeof data.metrics === 'object' ? { metrics: data.metrics } : {}),
-            };
-        }
-        return null;
-    }
-    catch (e) {
-        logBridgeError('bridgeLatestSession', e);
-        return null;
-    }
-}
 // ===== Task routing =====
 export async function bridgeRouteTask(options) {
     const result = await bridgeSearchEntries({