@monoes/monomindcli 2.16.12 → 2.16.14

package/dist/src/memory/memory-bridge-paths.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Memory Bridge — project-root resolution and store path resolution
+ * (per-project data dir, global brain, MCP path-traversal guard). Split out
+ * of memory-bridge.ts, which re-exports the public symbols.
+ */
+export interface ProjectRootResolution {
+    root: string;
+    /** Why `root` was chosen — for disclosure (doctor, debug logs), not
+     *  behavior. `explicit-anchor`: MONOMIND_PROJECT_ROOT set and valid.
+     *  `git`: a `.git` ancestor (any depth) was adopted. `monomind-at-start`:
+     *  the starting directory itself carries `.monomind` (the user is
+     *  standing in their own project — always trusted). `monomind-with-marker`:
+     *  an ancestor's `.monomind` was corroborated by an independent project
+     *  marker. `start-fallback`: nothing adoptable was found; `root` is
+     *  `start`. */
+    reason: 'explicit-anchor' | 'git' | 'monomind-at-start' | 'monomind-with-marker' | 'start-fallback';
+    /** Set only on `start-fallback`: the first bare `.monomind` ancestor that
+     *  was found but NOT adopted (no independent marker alongside it), so a
+     *  caller can tell a genuinely ambiguous user why their brain stayed put
+     *  instead of silently picking a directory that merely looked plausible. */
+    ignoredBareMonomind?: string;
+    /** Set whenever MONOMIND_PROJECT_ROOT was present in the environment but
+     *  failed validation — regardless of what `reason`/`root` ended up being,
+     *  so a typo'd anchor is never silently dropped just because the ordinary
+     *  walk happened to land somewhere reasonable anyway (o-16 revision 1). */
+    invalidAnchor?: {
+        value: string;
+        problem: string;
+    };
+}
+/** 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 declare function getProjectRootResolution(from?: string): ProjectRootResolution;
+/** 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 declare function getProjectRoot(from?: string): string;
+export declare function projectDataDir(): string;
+/** 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 declare function getGlobalBrainDir(): string;
+/** Sentinel callers pass as dbPath to address the global brain. */
+export declare const GLOBAL_BRAIN = "@global";
+export declare function getDbPath(customPath?: string): string;
+/** 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 declare function bridgeGetDbPath(customPath?: string): string;
+//# sourceMappingURL=memory-bridge-paths.d.ts.map

package/dist/src/memory/memory-bridge-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-bridge-paths.d.ts","sourceRoot":"","sources":["../../../src/memory/memory-bridge-paths.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA4CH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;mBAOe;IACf,MAAM,EACF,iBAAiB,GACjB,KAAK,GACL,mBAAmB,GACnB,sBAAsB,GACtB,gBAAgB,CAAC;IACrB;;;gFAG4E;IAC5E,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;+EAG2E;IAC3E,aAAa,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACpD;AA6HD;;;;qDAIqD;AACrD,wBAAgB,wBAAwB,CACtC,IAAI,GAAE,MAAkD,GACvD,qBAAqB,CAavB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,wBAAgB,cAAc,CAAC,IAAI,GAAE,MAAkD,GAAG,MAAM,CAE/F;AAED,wBAAgB,cAAc,IAAI,MAAM,CASvC;AAaD;;;;wDAIwD;AACxD,wBAAgB,iBAAiB,IAAI,MAAM,CAI1C;AACD,mEAAmE;AACnE,eAAO,MAAM,YAAY,YAAY,CAAC;AAEtC,wBAAgB,SAAS,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAsCrD;AAED;+EAC+E;AAC/E,wBAAgB,eAAe,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3D"}

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

@@ -0,0 +1,335 @@
+/**
+ * Memory Bridge — project-root resolution and store path resolution
+ * (per-project data dir, global brain, MCP path-traversal guard). Split out
+ * of memory-bridge.ts, which re-exports the public symbols.
+ */
+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 { logBridgeError } from './memory-bridge-core.js';
+// ===== 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-paths.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;
+}
+export 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';
+export 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);
+}
+//# sourceMappingURL=memory-bridge-paths.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memory-bridge-paths.js","sourceRoot":"","sources":["../../../src/memory/memory-bridge-paths.ts"],"names":[],"mappings":"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"}

package/dist/src/memory/memory-bridge-search.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Memory Bridge — the read/search path: bridgeSearchEntries (semantic +
+ * FTS5/BM25 keyword merge, stale and superseded-knowledge filtering,
+ * cross-encoder reranking). Split out of memory-bridge.ts, which re-exports
+ * it.
+ */
+export declare function bridgeSearchEntries(options: {
+    query: string;
+    namespace?: string;
+    limit?: number;
+    threshold?: number;
+    dbPath?: string;
+    /** Skip cross-encoder reranking even if the model is loaded. */
+    skipRerank?: boolean;
+    /** When true, superseded knowledge chunks are kept in the results
+     *  (flagged by the caller). Default false — removed documents are
+     *  filtered out for security. */
+    includeSuperseded?: boolean;
+    /** Project root to read document metadata from for the knowledge-superseded
+     *  check (default: getProjectRoot(), i.e. process.cwd()-derived). Callers
+     *  operating on an explicit project directory that differs from cwd — e.g.
+     *  searchKnowledge({ rootDir }) — must pass the SAME root here, or every
+     *  freshly-ingested doc in that directory reads as superseded (its content
+     *  hash won't be found in metadata read from the wrong place) and gets
+     *  filtered out despite matching the query. */
+    rootDir?: string;
+}): Promise<{
+    success: boolean;
+    results: {
+        id: string;
+        key: string;
+        content: string;
+        score: number;
+        namespace: string;
+        provenance?: string;
+        tags?: string[];
+    }[];
+    searchTime: number;
+    /** What actually ran, never what was requested. 'keyword-fallback' means the
+     *  vector path was attempted and did not produce the results. */
+    searchMethod?: 'semantic' | 'keyword' | 'keyword-fallback';
+    /** Whether a cross-encoder reranker was applied to the final results. */
+    reranked?: boolean;
+    /** Why the vector path did not serve these results (absent when it did). */
+    fallbackReason?: 'no-embedding-model' | 'empty-query' | 'embedding-failed' | 'no-semantic-matches';
+    error?: string;
+} | null>;
+//# sourceMappingURL=memory-bridge-search.d.ts.map

package/dist/src/memory/memory-bridge-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-bridge-search.d.ts","sourceRoot":"","sources":["../../../src/memory/memory-bridge-search.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAoBH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;qCAEiC;IACjC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;;mDAM+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC;IACV,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE;QACP,EAAE,EAAE,MAAM,CAAC;QACX,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;KACjB,EAAE,CAAC;IACJ,UAAU,EAAE,MAAM,CAAC;IACnB;qEACiE;IACjE,YAAY,CAAC,EAAE,UAAU,GAAG,SAAS,GAAG,kBAAkB,CAAC;IAC3D,yEAAyE;IACzE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,4EAA4E;IAC5E,cAAc,CAAC,EACX,oBAAoB,GACpB,aAAa,GACb,kBAAkB,GAClB,qBAAqB,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,IAAI,CAAC,CAoZR"}