Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
/**
* Cross-vault union search (Workspace Insight Suite, t_72a22658):
* one query fans out over the active vault, registered profile vaults,
* and read-only recall sources; results merge by score with origin
* labels; a failing origin degrades to a warning, never an error.
*/
import { afterEach, beforeEach, expect, test } from "bun:test";
import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createProfile } from "../../../src/core/brain/portability/profiles.ts";
import { addRecallSource } from "../../../src/core/brain/portability/recall-sources.ts";
import { listSearchOrigins } from "../../../src/core/brain/portability/origins.ts";
import {
RETRIEVAL_DEGRADATION,
RETRIEVAL_DETAIL_IDENTIFIER,
} from "../../../src/core/search/retrieval-trail.ts";
import { searchAcrossVaults } from "../../../src/core/search/cross-vault.ts";
import { indexVault } from "../../../src/core/search/indexer.ts";
import { resolveSearchConfig } from "../../../src/core/search/index.ts";
import { writeMd } from "../../helpers/search-fixtures.ts";
let tmp: string;
let active: string;
let external: string;
let configPath: string;
beforeEach(async () => {
tmp = mkdtempSync(join(tmpdir(), "o2b-cross-vault-"));
active = join(tmp, "active-vault");
external = join(tmp, "external-vault");
mkdirSync(join(active, "Brain"), { recursive: true });
mkdirSync(join(external, "Brain"), { recursive: true });
configPath = join(tmp, "config.yaml");
writeFileSync(configPath, `vault: "${active}"\n`);
// The active note answers "griffin" completely and "aviary-keeper"
// only in part: SQLite's tokenizer splits the hyphen, so the row MATCHES
// on `aviary` + `keeper`, while the coverage engine's containment test
// looks for the literal term and does not find it. That is what gives
// the chain-stop test below an origin that genuinely returns rows and
// genuinely half-answers - see its own comment for why a fixture that
// returns no rows cannot test that gate at all.
writeMd(
active,
"Brain/notes/local-note.md",
"# Local\n\nThe griffin nests in the local vault beside the aviary keeper.",
);
writeMd(
external,
"Brain/notes/external-note.md",
"# External\n\nThe griffin also visits the external vault aviary-keeper.",
);
await indexVault(resolveSearchConfig({ vault: active, configPath }));
await indexVault(resolveSearchConfig({ vault: external, configPath }));
});
afterEach(() => {
rmSync(tmp, { recursive: true, force: true });
});
test("listSearchOrigins enumerates active, profiles, and sources, deduped by path", () => {
createProfile(configPath, "work", external);
createProfile(configPath, "same-as-active", active);
addRecallSource(configPath, active, "team", external);
const origins = listSearchOrigins(configPath, active);
// active first, then the profile; the source duplicates the profile's
// path and the profile duplicating the active vault is dropped.
expect(origins.map((o) => o.label)).toEqual(["local", "profile/work"]);
expect(origins[0]!.kind).toBe("active");
});
test("union search labels results with their origin and merges by score", async () => {
addRecallSource(configPath, active, "team", external);
const outcome = await searchAcrossVaults(configPath, active, { query: "griffin", limit: 10 });
const labels = new Set(outcome.results.map((r) => r.origin));
expect(labels).toEqual(new Set(["local", "source/team"]));
for (const r of outcome.results) {
expect(r.reasons.some((reason) => reason.startsWith("origin:"))).toBe(true);
}
const scores = outcome.results.map((r) => r.score);
expect([...scores].toSorted((a, b) => b - a)).toEqual(scores);
});
test("an origin without an index degrades to a warning and writes nothing", async () => {
const bare = join(tmp, "bare-vault");
mkdirSync(join(bare, "Brain"), { recursive: true });
addRecallSource(configPath, active, "bare", bare);
const outcome = await searchAcrossVaults(configPath, active, { query: "griffin", limit: 10 });
expect(outcome.results.length).toBeGreaterThan(0);
expect(outcome.warnings.some((w) => w.includes("source/bare"))).toBe(true);
// The failure's own message never reaches this channel: it can name the
// external index file, and warnings travel verbatim into MCP payloads.
// What travels instead is the origin label, the typed SearchError code
// and one fix.
expect(outcome.warnings.some((w) => w.includes(bare))).toBe(false);
expect(outcome.warnings.some((w) => w.includes("INDEX_MISSING"))).toBe(true);
// And the same fact as a code, so a caller does not have to read prose.
const entry = outcome.retrievalTrail?.degraded.find(
(d) => d.code === RETRIEVAL_DEGRADATION.crossVaultOriginFailed,
);
expect(entry?.detail).toEqual({ origin: "source/bare", cause: "INDEX_MISSING" });
// Read-only invariant: the union search never builds an index inside
// an external vault.
expect(existsSync(join(bare, ".open-second-brain", "brain.sqlite"))).toBe(false);
});
test("limit applies to the merged result set", async () => {
addRecallSource(configPath, active, "team", external);
const outcome = await searchAcrossVaults(configPath, active, { query: "griffin", limit: 1 });
expect(outcome.results).toHaveLength(1);
expect(outcome.total).toBeGreaterThanOrEqual(2);
});
test("single-origin union (no profiles, no sources) matches plain search shape", async () => {
const outcome = await searchAcrossVaults(configPath, active, { query: "griffin", limit: 5 });
expect(outcome.results.length).toBeGreaterThan(0);
expect(outcome.results.every((r) => r.origin === "local")).toBe(true);
});
// t_fd411665 - cards-mode (disclosure: "cards") must compose with the union:
// each origin returns its hits on `outcome.cards` with `results` empty, and the
// union has to merge the cards, not silently drop them.
test("cards mode: cards from every origin merge, labelled, with results empty", async () => {
addRecallSource(configPath, active, "team", external);
const outcome = await searchAcrossVaults(configPath, active, {
query: "griffin",
limit: 10,
disclosure: "cards",
});
expect(outcome.results).toHaveLength(0);
expect(outcome.cards).toBeDefined();
const labels = new Set((outcome.cards ?? []).map((c) => c.origin));
expect(labels).toEqual(new Set(["local", "source/team"]));
for (const c of outcome.cards ?? []) {
expect(c.reasons.some((reason) => reason.startsWith("origin:"))).toBe(true);
}
const scores = (outcome.cards ?? []).map((c) => c.score);
expect([...scores].toSorted((a, b) => b - a)).toEqual(scores);
});
test("cards mode: limit caps the merged card set", async () => {
addRecallSource(configPath, active, "team", external);
const outcome = await searchAcrossVaults(configPath, active, {
query: "griffin",
limit: 1,
disclosure: "cards",
});
expect(outcome.cards).toHaveLength(1);
expect(outcome.results).toHaveLength(0);
expect(outcome.total).toBeGreaterThanOrEqual(2);
});
test("cards mode: chain-stop gates on the top CARD score and skips remaining origins", async () => {
addRecallSource(configPath, active, "team", external);
// Threshold 0: the active origin's cards clear it, so the external origin is
// never searched. Proves the gate reads the card score when results is empty.
writeFileSync(
configPath,
`vault: "${active}"\nsearch_chain_stop_enabled: true\nsearch_chain_stop_score: 0\n`,
);
const outcome = await searchAcrossVaults(configPath, active, {
query: "griffin",
limit: 10,
disclosure: "cards",
});
expect((outcome.cards ?? []).every((c) => c.origin === "local")).toBe(true);
expect(outcome.chainStop?.triggered).toBe(true);
expect(outcome.chainStop?.stoppedAfter).toBe("local");
expect(outcome.chainStop?.skipped).toEqual(["source/team"]);
// Origins deliberately not searched are a narrowing, and the trail is
// the first surface that says so - `chainStop` reached no caller.
const stopped = outcome.retrievalTrail?.degraded.find(
(d) => d.code === RETRIEVAL_DEGRADATION.crossVaultChainStopped,
);
expect(stopped?.detail).toEqual({ stoppedAfter: "local", skipped: 1 });
});
// D4 t_23c1b929 - normalized-confidence chain-stop for cross-vault early termination.
function withChainStop(score: number): void {
// Re-resolve every origin from config.yaml, so the knob reaches the
// active origin the cross-vault loop gates on.
writeFileSync(
configPath,
`vault: "${active}"\nsearch_chain_stop_enabled: true\nsearch_chain_stop_score: ${score}\n`,
);
}
test("chain-stop on: a confident active origin skips the remaining origins", async () => {
addRecallSource(configPath, active, "team", external);
// Threshold 0: any non-empty origin clears it, so the active origin
// alone answers and the external origin is never searched.
withChainStop(0);
const outcome = await searchAcrossVaults(configPath, active, { query: "griffin", limit: 10 });
expect(outcome.results.every((r) => r.origin === "local")).toBe(true);
expect(outcome.chainStop).toBeDefined();
expect(outcome.chainStop?.triggered).toBe(true);
expect(outcome.chainStop?.stoppedAfter).toBe("local");
expect(outcome.chainStop?.skipped).toEqual(["source/team"]);
// Origins deliberately not searched are a narrowing, and the trail is
// the first surface that says so - `chainStop` reached no caller.
const stopped = outcome.retrievalTrail?.degraded.find(
(d) => d.code === RETRIEVAL_DEGRADATION.crossVaultChainStopped,
);
expect(stopped?.detail).toEqual({ stoppedAfter: "local", skipped: 1 });
});
test("chain-stop gates on coverage: an origin that half-answers does not stop the chain", async () => {
addRecallSource(configPath, active, "team", external);
// The active origin RETURNS A ROW for this query and covers only half
// of it: `aviary-keeper` matches its note through the tokenizer's
// hyphen split, and is not contained in it as a term. Under a 0.9
// coverage threshold the chain must walk on and find the origin that
// holds the missing half.
//
// The row count is the whole point of the fixture. An earlier version
// of this test asked for terms the active vault did not have at all, so
// the origin returned ZERO rows and the gate short-circuited on
// `hits.length > 0` before reading any threshold - reverting the gate
// to the old top-score rule left it green. A test of a threshold has to
// reach the threshold.
//
// This is the assertion the old score-based gate could not make. Its
// quantity was the top NORMALIZED result score, which the keyword lane
// min-max normalises within each origin's own pool - so it said the same
// thing about an origin that answered everything and one that answered a
// fragment, and it meant opposite things under the two fusion modes
// (unreachable in `linear`, always met in `rrf`).
// 0.6 rather than 0.9, and the band matters: the active origin's
// coverage here is 0.5 - the two terms carry equal IDF and one is
// covered - while its top SCORE is ~0.65, so this threshold sits
// BETWEEN the two quantities. A threshold above both (0.9) is cleared
// by neither, which is why the earlier 0.9 version of this test stayed
// green when the gate was reverted to the score.
withChainStop(0.6);
const outcome = await searchAcrossVaults(configPath, active, {
query: "griffin aviary-keeper",
limit: 10,
});
// The gate was reached with rows in hand…
expect(outcome.results.some((r) => r.origin === "local")).toBe(true);
// …and refused them, so the origin holding the other half is searched.
expect(outcome.chainStop).toBeUndefined();
expect(new Set(outcome.results.map((r) => r.origin))).toContain("source/team");
// The union's quality is the best origin's, and the external origin
// covers the query whole.
expect(outcome.idfWeightedCoverage).toBe(1);
});
test("chain-stop fires when the first origin covers the question", async () => {
addRecallSource(configPath, active, "team", external);
// The mirror of the case above: every significant term of this query is
// covered by the active origin, so the remaining origins add nothing the
// caller asked for and the chain stops - which is what the knob has
// always claimed to do and, on the shipped default fusion mode, never
// did.
withChainStop(0.9);
const outcome = await searchAcrossVaults(configPath, active, { query: "griffin", limit: 10 });
expect(outcome.chainStop?.triggered).toBe(true);
expect(new Set(outcome.results.map((r) => r.origin))).toEqual(new Set(["local"]));
});
/**
* The trail's `detail` rule is one rule for every lane, and these are the
* only codes whose identifiers are NAMESPACED: an origin label is
* `profile/<name>` or `source/<alias>`, the same string the results carry
* on `origin` and in their `origin:<label>` reason. A test that only ever
* exercises the trigram lane's `shadow_incomplete` cannot see that, which
* is how the rule and its writers came to disagree in silence.
*/
test("cross-vault detail values are identifiers under the trail's shared rule", async () => {
const other = join(tmp, "other-vault");
mkdirSync(join(other, "Brain"), { recursive: true });
writeMd(other, "Brain/notes/other-note.md", "# Other\n\nThe aviary keeper feeds the griffin.");
await indexVault(resolveSearchConfig({ vault: other, configPath }));
const bare = join(tmp, "bare-vault");
mkdirSync(join(bare, "Brain"), { recursive: true });
addRecallSource(configPath, active, "bare", bare);
addRecallSource(configPath, active, "team", external);
addRecallSource(configPath, active, "other", other);
withChainStop(0);
// "feeds" is absent from the active vault, so the union walks past it:
// source/bare cannot be read, source/other answers confidently, and
// source/team is deliberately skipped - one origin-failed entry and one
// chain-stopped entry, each keyed by a namespaced origin label.
const outcome = await searchAcrossVaults(configPath, active, { query: "feeds", limit: 10 });
const degraded = outcome.retrievalTrail?.degraded ?? [];
const codes = degraded.map((d) => d.code);
expect(codes).toContain(RETRIEVAL_DEGRADATION.crossVaultOriginFailed);
expect(codes).toContain(RETRIEVAL_DEGRADATION.crossVaultChainStopped);
const values = degraded.flatMap((d) => Object.values(d.detail ?? {}));
// The shape the trigram-only assertion could never reach.
expect(values.some((v) => typeof v === "string" && v.includes("/"))).toBe(true);
for (const value of values) {
if (typeof value === "number") {
expect(Number.isFinite(value)).toBe(true);
continue;
}
expect(value).toMatch(RETRIEVAL_DETAIL_IDENTIFIER);
}
});
test("chain-stop off (default) runs every origin bit-identically and records no chainStop", async () => {
addRecallSource(configPath, active, "team", external);
const outcome = await searchAcrossVaults(configPath, active, { query: "griffin", limit: 10 });
const labels = new Set(outcome.results.map((r) => r.origin));
expect(labels).toEqual(new Set(["local", "source/team"]));
expect(outcome.chainStop).toBeUndefined();
});