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
/**
* `SearchOutcome.total` is the pre-truncation ranked pool size
* (what-the-index-already-knew, task F).
*
* Before this unit `total` was assigned the length of the returned array,
* so it carried no information at all: a caller could not tell "the vault
* holds three matches" from "the vault holds thirty and you were handed
* three". The pool the final `limit` slice cuts from is a property of the
* answer, not a diagnostic, so it is reported inline on every outcome.
*/
import { afterEach, beforeEach, expect, test } from "bun:test";
import { utimesSync } from "node:fs";
import { indexVault } from "../../../src/core/search/indexer.ts";
import { search } from "../../../src/core/search/search.ts";
import { Store } from "../../../src/core/search/store.ts";
import { assembleRankedResults } from "../../../src/core/search/pipeline/assemble.ts";
import { collectCandidateSignals } from "../../../src/core/search/pipeline/candidate-signals.ts";
import { parseBenchPinnedKnobs } from "../../../src/cli/brain/verbs/bench.ts";
import {
RETRIEVAL_DEGRADATION,
type RetrievalDegradation,
} from "../../../src/core/search/retrieval-trail.ts";
import type { ResolvedRecallConfig, ResolvedSearchConfig } from "../../../src/core/search/types.ts";
import type { KeywordHit } from "../../../src/core/search/store.ts";
import { createTempVault, makeConfig, writeMd } from "../../helpers/search-fixtures.ts";
/** Matching notes, comfortably above the `limit` the queries below use. */
const MATCHING_NOTES = 12;
const LIMIT = 3;
let vault: string;
let dbPath: string;
let cleanup: () => void;
beforeEach(async () => {
({ vault, dbPath, cleanup } = createTempVault("pool-total"));
for (let i = 0; i < MATCHING_NOTES; i += 1) {
writeMd(
vault,
`notes/note-${i}.md`,
`---\ntitle: Note ${i}\n---\n\n# Note ${i}\n\nThe widget calibration routine number ${i}.\n`,
);
}
await indexVault(makeConfig({ vault, dbPath, maxHops: 0 }), {});
});
afterEach(() => cleanup());
function config() {
return makeConfig({ vault, dbPath, maxHops: 0 });
}
test("total is the ranked pool the limit slice cut from, not the row count", async () => {
const out = await search(config(), { query: "widget calibration", limit: LIMIT });
expect(out.results.length).toBe(LIMIT);
expect(out.total).toBeGreaterThan(out.results.length);
// The pool is the candidate set retrieval actually ranked, which is
// widened past `limit` but still bounded by the lane fetch - so it is a
// lower bound on the corpus matches, never an over-count.
expect(out.total).toBeLessThanOrEqual(MATCHING_NOTES);
});
test("a limit wider than the pool reports the pool, so total never exceeds the corpus", async () => {
const out = await search(config(), { query: "widget calibration", limit: MATCHING_NOTES + 5 });
expect(out.results.length).toBe(MATCHING_NOTES);
expect(out.total).toBe(MATCHING_NOTES);
});
test("cards disclosure reports the same pool as the full path", async () => {
const full = await search(config(), { query: "widget calibration", limit: LIMIT });
const cards = await search(config(), {
query: "widget calibration",
limit: LIMIT,
disclosure: "cards",
});
expect(cards.cards!.length).toBe(LIMIT);
expect(cards.total).toBe(full.total);
expect(cards.total).toBeGreaterThan(cards.cards!.length);
});
test("a query with no candidates still reports zero", async () => {
const out = await search(config(), { query: "zzzznonexistentterm", limit: LIMIT });
expect(out.results).toEqual([]);
expect(out.total).toBe(0);
});
// ββ per-source-session pool cap (t_bb6ce095) βββββββββββββββββββββββββββββββββ
/** One recall patch over the harness config, the way trail tests patch it. */
function withRecall(
base: ResolvedSearchConfig,
patch: Partial<ResolvedRecallConfig>,
): ResolvedSearchConfig {
return Object.freeze({ ...base, recall: Object.freeze({ ...base.recall, ...patch }) });
}
/** The crowded fixture: six hot notes in one source session, three elsewhere. */
const CROWDED_HOT_NOTES = 6;
const CROWDED_QUERY = "widget calibration";
/**
* One modification time for every note a fixture expects in a fixed order.
* Notes that tie on score reach the ranker's tie-break ladder, which orders
* by `mtime` (newest first, at the index's one-second resolution) before
* the chunk id. Notes written back to back usually share one second and so
* fall through to the chunk id, but a run whose writes straddle a second
* boundary (seen on a Windows runner) answers with the newest notes first.
* A fixed time makes each fixture as clock-free as its config claims.
*/
const FIXTURE_MTIME = new Date("2026-01-01T00:00:00Z");
function writeCrowdedVault(vaultDir: string): void {
for (let i = 0; i < CROWDED_HOT_NOTES; i += 1) {
const path = writeMd(
vaultDir,
`a-${i}.md`,
`---\ntitle: Crowded ${i}\nsession_ref: sess-a\n---\n\n# Crowded ${i}\n\n` +
`The widget calibration routine number ${i}. Widget calibration is repeated here. ` +
`Widget calibration matters to this note.\n`,
);
utimesSync(path, FIXTURE_MTIME, FIXTURE_MTIME);
}
for (const session of ["b", "c", "d"]) {
const path = writeMd(
vaultDir,
`${session}.md`,
`---\ntitle: Other ${session}\nsession_ref: sess-${session}\n---\n\n# Other ${session}\n\n` +
`The widget calibration routine of session ${session}.\n`,
);
utimesSync(path, FIXTURE_MTIME, FIXTURE_MTIME);
}
}
/** A clock-free fixture config: the recency layer is amplitude zero. */
async function indexedCrowdedVault() {
const v = createTempVault("pool-cap-crowded");
writeCrowdedVault(v.vault);
const cold = withRecall(
makeConfig({ vault: v.vault, dbPath: v.dbPath, maxHops: 0, mmrLambda: 1 }),
{
recencyAmplitude: 0,
},
);
await indexVault(cold, {});
return { ...v, cold };
}
function degradationOf(
out: { readonly retrievalTrail?: { readonly degraded: ReadonlyArray<RetrievalDegradation> } },
code: string,
): RetrievalDegradation | undefined {
return out.retrievalTrail?.degraded.find((d) => d.code === code);
}
test("the cap off returns today's crowded order byte-for-byte", async () => {
const v = await indexedCrowdedVault();
try {
const off = await search(v.cold, { query: CROWDED_QUERY, limit: LIMIT });
const explicitOff = await search(withRecall(v.cold, { poolMaxPerSession: 0 }), {
query: CROWDED_QUERY,
limit: LIMIT,
});
// The off path is the pre-knob pipeline: an explicit 0 answers with
// the default's exact bytes.
expect(JSON.stringify(explicitOff)).toBe(JSON.stringify(off));
// Frozen pre-change expectation, so the proof is anchored outside
// this build: a regression that shifts BOTH arms of the A/B above
// identically now goes red. Order and trail identity are pinned -
// never score magnitudes. The crowded session takes every window
// slot, and the only narrowing the off answer names is the pre-knob
// rank-cap truncation, never a session-cap note.
expect(off.results.map((r) => r.path)).toEqual(["a-0.md", "a-1.md", "a-2.md"]);
expect(off.retrievalTrail?.degraded).toEqual([
{ code: RETRIEVAL_DEGRADATION.rankCapTruncatedPool, detail: { cap: LIMIT } },
]);
} finally {
v.cleanup();
}
});
test("the cap on spreads the window across sessions and names its drop", async () => {
const v = await indexedCrowdedVault();
try {
const on = await search(withRecall(v.cold, { poolMaxPerSession: 2 }), {
query: CROWDED_QUERY,
limit: LIMIT,
});
expect(on.results.length).toBe(LIMIT);
// Two crowded-session rows keep the top slots; the rest of the window
// reaches other sessions.
// The crowd's best-ranked survivor leads whichever a- note the index
// ranked first - directory order must not decide the assertion.
expect(on.results[0]?.path.startsWith("a-")).toBe(true);
expect(on.results.some((r) => !r.path.startsWith("a-"))).toBe(true);
const entry = degradationOf(on, RETRIEVAL_DEGRADATION.sourceSessionCappedRows);
expect(entry?.detail).toEqual({ dropped: 4, cap: 2 });
} finally {
v.cleanup();
}
});
test("the per-query override alone activates the cap without a config value", async () => {
const v = await indexedCrowdedVault();
try {
// `cold` carries no poolMaxPerSession at all: the whole cap comes
// from the per-query SearchOptions field.
const overridden = await search(v.cold, {
query: CROWDED_QUERY,
limit: LIMIT,
poolMaxPerSession: 2,
});
expect(overridden.results.length).toBe(LIMIT);
expect(overridden.results[0]?.path.startsWith("a-")).toBe(true);
expect(overridden.results.some((r) => !r.path.startsWith("a-"))).toBe(true);
const entry = degradationOf(overridden, RETRIEVAL_DEGRADATION.sourceSessionCappedRows);
expect(entry?.detail).toEqual({ dropped: 4, cap: 2 });
// The same query without the override stays uncapped - the override,
// not the fixture, is what capped the answer. (The uncapped run
// still carries the pre-existing rank-cap note; the session-cap
// note is the one that must be absent.)
const plain = await search(v.cold, { query: CROWDED_QUERY, limit: LIMIT });
expect(degradationOf(plain, RETRIEVAL_DEGRADATION.sourceSessionCappedRows)).toBeUndefined();
expect(JSON.stringify(plain)).not.toBe(JSON.stringify(overridden));
} finally {
v.cleanup();
}
});
test("the per-query override wins over the config value when both are set", async () => {
const v = await indexedCrowdedVault();
try {
// Tighter than the config: 2 crowded rows survive under config cap
// 2, but the query's own cap 1 keeps only the first.
const tighter = await search(withRecall(v.cold, { poolMaxPerSession: 2 }), {
query: CROWDED_QUERY,
limit: LIMIT,
poolMaxPerSession: 1,
});
expect(tighter.results.map((r) => r.path)).toEqual(["a-0.md", "b.md", "c.md"]);
expect(degradationOf(tighter, RETRIEVAL_DEGRADATION.sourceSessionCappedRows)?.detail).toEqual({
dropped: 5,
cap: 1,
});
// Looser than the config: config cap 1 would keep one crowded row,
// but the query's own cap 3 keeps three.
const looser = await search(withRecall(v.cold, { poolMaxPerSession: 1 }), {
query: CROWDED_QUERY,
limit: LIMIT,
poolMaxPerSession: 3,
});
expect(looser.results.map((r) => r.path)).toEqual(["a-0.md", "a-1.md", "a-2.md"]);
expect(degradationOf(looser, RETRIEVAL_DEGRADATION.sourceSessionCappedRows)?.detail).toEqual({
dropped: 3,
cap: 3,
});
} finally {
v.cleanup();
}
});
test("an explicit per-query 0 forces the cap off over a config cap", async () => {
const v = await indexedCrowdedVault();
try {
const forcedOff = await search(withRecall(v.cold, { poolMaxPerSession: 2 }), {
query: CROWDED_QUERY,
limit: LIMIT,
poolMaxPerSession: 0,
});
const off = await search(v.cold, { query: CROWDED_QUERY, limit: LIMIT });
// The documented forced-off value: the config knob cannot reach past
// a per-query 0, and the answer is the default-off run's exact bytes
// (rank-cap trail and all - the session-cap note never appears).
expect(JSON.stringify(forcedOff)).toBe(JSON.stringify(off));
expect(degradationOf(forcedOff, RETRIEVAL_DEGRADATION.sourceSessionCappedRows)).toBeUndefined();
} finally {
v.cleanup();
}
});
test("a vault with no session identity ranks identically with the cap on", async () => {
// The module fixture holds ordinary notes only - no session_ref, no
// session_id - so with the cap on, every note is its own PATH group
// (the M2 fallback) holding a single chunk, and nothing can drop.
const cold = withRecall(config(), { recencyAmplitude: 0 });
const off = await search(cold, { query: "widget calibration", limit: LIMIT });
const on = await search(withRecall(cold, { poolMaxPerSession: 2 }), {
query: "widget calibration",
limit: LIMIT,
});
expect(JSON.stringify(on)).toBe(JSON.stringify(off));
expect(on.retrievalTrail).toBeUndefined();
});
test("the cap's drops trigger the one-shot re-widen when the window under-fills", async () => {
// Forty matching notes in ONE session: the window cannot fill (cap 2,
// limit 3), and the cap's own drops are the review-M3 trigger the older
// build lacked - the re-widen runs once at
// `limit * (widestGroupRows + 1)` = 3 * 31 = 93, ranks the whole
// corpus (40 rows), and reports the FINAL pass: 2 survived, 38
// dropped - the first 30-wide pass dropped 28. The answer stays 2 rows
// because the corpus holds one session only; the trail names that pass
// honestly instead of retrying forever.
const v = createTempVault("pool-cap-final");
try {
for (let i = 0; i < 40; i += 1) {
writeMd(
v.vault,
`solo-${i}.md`,
`---\ntitle: Solo ${i}\nsession_ref: sess-a\n---\n\n# Solo ${i}\n\n` +
`The widget calibration routine number ${i}.\n`,
);
}
const cold = withRecall(
makeConfig({ vault: v.vault, dbPath: v.dbPath, maxHops: 0, mmrLambda: 1 }),
{ recencyAmplitude: 0, poolMultiplier: 20, poolMaxPerSession: 2 },
);
await indexVault(cold, {});
const out = await search(cold, { query: CROWDED_QUERY, limit: LIMIT });
// The corpus holds nothing outside the one session, so the re-widen
// cannot add rows - but it RANKED them: dropped 38 witnesses the
// 40-row final pass, never the first pass's 28.
expect(out.results.length).toBe(2);
const entry = degradationOf(out, RETRIEVAL_DEGRADATION.sourceSessionCappedRows);
expect(entry?.detail).toEqual({ dropped: 38, cap: 2 });
// Once per answer: the re-widen's second pass replaces the first
// pass's note, it never stacks beside it.
const capNotes = out.retrievalTrail?.degraded.filter(
(d) => d.code === RETRIEVAL_DEGRADATION.sourceSessionCappedRows,
);
expect(capNotes).toHaveLength(1);
} finally {
v.cleanup();
}
});
test("the re-widen actually refills the window from deeper sessions", async () => {
// The review-M3 repro, ranked deterministically: forty rows of one
// session outrank ten single-row sessions, cap 1, limit 3. The first
// 30-wide pass keeps one row; the re-widen ranks past the crowded
// session and the window fills from the sessions the cap did not
// exhaust. Driven through `assembleRankedResults` directly so the rank
// order is pinned by the fixture, not by scoring.
const v = createTempVault("pool-cap-refill");
try {
for (let i = 0; i < 30; i += 1) {
writeMd(
v.vault,
`a-${i}.md`,
`---\ntitle: Wide ${i}\nsession_ref: sess-a\n---\n\n# Wide ${i}\n\nalpha beta gamma ${i}.\n`,
);
}
for (let i = 0; i < 10; i += 1) {
writeMd(
v.vault,
`b-${i}.md`,
`---\ntitle: Deep ${i}\nsession_ref: sess-b-${i}\n---\n\n# Deep ${i}\n\nalpha beta gamma deep ${i}.\n`,
);
}
const base = makeConfig({
vault: v.vault,
dbPath: v.dbPath,
maxHops: 0,
mmrLambda: 1,
intentEnabled: false,
});
const cfg = withRecall(base, {
recencyAmplitude: 0,
poolMaxPerSession: 1,
});
await indexVault(cfg, {});
const store = await Store.open(cfg, { mode: "read" });
try {
const documents = store.listDocuments();
const chunkIdFor = (path: string): number => {
const doc = documents.get(path);
if (doc === undefined) throw new Error(`fixture document missing from index: ${path}`);
const first = store.chunksForDocument(doc.id)[0];
if (first === undefined) throw new Error(`fixture document has no chunk: ${path}`);
return first.id;
};
const paths = [...documents.keys()].toSorted();
const ids = paths.map(chunkIdFor);
const hydrated = store.hydrateChunks(ids);
// Every crowded row outranks every deep row: bm25 is more negative
// for the crowded session, which ranks first.
const keywordHits: KeywordHit[] = paths.map((path, at) => ({
chunkId: ids[at]!,
documentId: hydrated.get(ids[at]!)!.documentId,
bm25: path.startsWith("a-") ? -(5 + at / 100) : -1,
}));
const frontmatterCache = new Map();
const signals = collectCandidateSignals({
store,
config: cfg,
ids,
hydrated,
query: CROWDED_QUERY,
frontmatterCache,
temporalIntentActive: false,
declaredEventTimeMs: () => null,
});
const degraded: RetrievalDegradation[] = [];
const pool = assembleRankedResults({
store,
config: cfg,
opts: { query: CROWDED_QUERY, limit: LIMIT },
keywordHits,
semanticHits: [],
hydrated,
signals,
relationalRankedChunkIds: [],
weightProfile: undefined,
sessionFocus: null,
semanticEnabled: false,
structured: undefined,
frontmatterCache,
timeRange: null,
temporalIntent: null,
declaredEventTimeMs: () => null,
limit: LIMIT,
nowMs: Date.now(),
degraded,
});
// The crowded session keeps its one row; every deep session row is
// in the pool the window draws from - the re-widen reached them.
expect(pool.length).toBe(11);
// The fixture's bm25 ladder makes a-9 (last in the sorted paths)
// the best-ranked crowded row - the one the cap keeps.
expect(pool[0]?.path).toBe("a-9.md");
expect(pool.filter((r) => r.path.startsWith("b-"))).toHaveLength(10);
// The note carries the FINAL pass's numbers: the crowded session
// still drops 29 of its ranked rows (1 kept), now beside the ten
// sessions the wider pool admitted.
const entry = degraded.find((d) => d.code === RETRIEVAL_DEGRADATION.sourceSessionCappedRows);
expect(entry?.detail).toEqual({ dropped: 29, cap: 1 });
expect(
degraded.filter((d) => d.code === RETRIEVAL_DEGRADATION.sourceSessionCappedRows),
).toHaveLength(1);
} finally {
await store.close();
}
} finally {
v.cleanup();
}
});
test("a pre-existing backfill under the cap notes the final pass's drops exactly once", async () => {
// The harder shape the once-per-answer contract claims: the backfill
// fires for its OWN pre-existing reason (default-scope visibility drops
// the private half of the session, leaving the window under-filled),
// the cap is re-applied over the wider 50-row pool, and the trail
// reports THAT pass's numbers - not the first pass's. Forty notes in
// one session, half `visibility: private`, cap 2, limit 3: the first
// (30-wide) pass sees 15 filter-passing rows and drops 13 of them to
// the cap, the second (50-wide) pass ranks all 40, filters to 20, and
// drops 18 - so `dropped: 18` is itself the witness that the window
// grew and the answer came from the final pass. And because the cap
// counts only FILTER-PASSING rows against the session's quota (the
// review-M4 ordering), both surviving public rows are in the answer -
// the older build spent quota on a private row the filters then
// withheld, and answered with one.
const v = createTempVault("pool-cap-backfill");
try {
for (let i = 0; i < 40; i += 1) {
const visibility = i % 2 === 1 ? "visibility: private\n" : "";
const path = writeMd(
v.vault,
`solo-${i}.md`,
`---\ntitle: Solo ${i}\n${visibility}session_ref: sess-a\n---\n\n# Solo ${i}\n\n` +
`The widget calibration routine number ${i}.\n`,
);
// Every row ties on score, so the expected order is the chunk id's
// (path order); a shared mtime keeps the newest-first rung out of it.
utimesSync(path, FIXTURE_MTIME, FIXTURE_MTIME);
}
const cold = withRecall(
makeConfig({ vault: v.vault, dbPath: v.dbPath, maxHops: 0, mmrLambda: 1 }),
{ recencyAmplitude: 0, poolMultiplier: 20, poolMaxPerSession: 2 },
);
await indexVault(cold, {});
const out = await search(cold, { query: CROWDED_QUERY, limit: LIMIT });
// The note names the FINAL pass: 18 dropped over the 50-wide pool's
// 20 filter-passing rows, never the first pass's 13. The two
// survivors are the two best-ranked PUBLIC rows (solo-1 is private
// and filters out before the cap ever sees it).
expect(out.results.map((r) => r.path)).toEqual(["solo-0.md", "solo-10.md"]);
const entry = degradationOf(out, RETRIEVAL_DEGRADATION.sourceSessionCappedRows);
expect(entry?.detail).toEqual({ dropped: 18, cap: 2 });
// Once per answer, even when the assemble closure ran twice.
const capNotes = out.retrievalTrail?.degraded.filter(
(d) => d.code === RETRIEVAL_DEGRADATION.sourceSessionCappedRows,
);
expect(capNotes).toHaveLength(1);
} finally {
v.cleanup();
}
});
test("the cap on joins the widening so a cross-encoder query keeps its topK pool", async () => {
// Thirty rows of one session ranked ahead of ten of another. With the
// cap active and the cross-encoder asking for a 40-wide pool, the
// widened rankLimit ranks past the crowded session: the second
// session's deep rows are in the pool the reader step draws from. A
// composition that lost the topK term would rank only the crowded
// session's top 30, and the cap would leave nothing else. Driven
// through `assembleRankedResults` directly - the cross-encoder call
// itself runs after this stage, so no endpoint is involved.
const v = createTempVault("pool-cap-widen");
try {
for (let i = 0; i < 30; i += 1) {
writeMd(
v.vault,
`a-${i}.md`,
`---\ntitle: Wide ${i}\nsession_ref: sess-a\n---\n\n# Wide ${i}\n\nalpha beta gamma ${i}.\n`,
);
}
for (let i = 0; i < 10; i += 1) {
writeMd(
v.vault,
`b-${i}.md`,
`---\ntitle: Deep ${i}\nsession_ref: sess-b\n---\n\n# Deep ${i}\n\nalpha beta gamma deep ${i}.\n`,
);
}
const base = makeConfig({
vault: v.vault,
dbPath: v.dbPath,
maxHops: 0,
mmrLambda: 1,
intentEnabled: false,
});
const cfg = withRecall(base, {
recencyAmplitude: 0,
poolMaxPerSession: 2,
});
const rerankCfg = Object.freeze({
...cfg,
rerank: Object.freeze({ ...cfg.rerank, enabled: true, topK: 40 }),
});
await indexVault(rerankCfg, {});
const store = await Store.open(rerankCfg, { mode: "read" });
try {
const documents = store.listDocuments();
const chunkIdFor = (path: string): number => {
const doc = documents.get(path);
if (doc === undefined) throw new Error(`fixture document missing from index: ${path}`);
const first = store.chunksForDocument(doc.id)[0];
if (first === undefined) throw new Error(`fixture document has no chunk: ${path}`);
return first.id;
};
const paths = [...documents.keys()].toSorted();
const ids = paths.map(chunkIdFor);
const hydrated = store.hydrateChunks(ids);
// Every crowded row outranks every deep row: bm25 is more negative
// for the crowded session, which ranks first.
const keywordHits: KeywordHit[] = paths.map((path, at) => ({
chunkId: ids[at]!,
documentId: hydrated.get(ids[at]!)!.documentId,
bm25: path.startsWith("a-") ? -(5 + at / 100) : -1,
}));
const frontmatterCache = new Map();
const signals = collectCandidateSignals({
store,
config: rerankCfg,
ids,
hydrated,
query: CROWDED_QUERY,
frontmatterCache,
temporalIntentActive: false,
declaredEventTimeMs: () => null,
});
const pool = assembleRankedResults({
store,
config: rerankCfg,
opts: { query: CROWDED_QUERY, limit: LIMIT },
keywordHits,
semanticHits: [],
hydrated,
signals,
relationalRankedChunkIds: [],
weightProfile: undefined,
sessionFocus: null,
semanticEnabled: false,
structured: undefined,
frontmatterCache,
timeRange: null,
temporalIntent: null,
declaredEventTimeMs: () => null,
limit: LIMIT,
nowMs: Date.now(),
degraded: [],
});
expect(pool.length).toBe(4); // the cap keeps two rows per session
// The widen witness: the deep session's rows were RANKED at all,
// which only the topK term of the widened composition allows.
expect(pool.some((r) => r.path.startsWith("b-"))).toBe(true);
} finally {
await store.close();
}
} finally {
v.cleanup();
}
});
test("a bench pin caps frontmatter-less bench session notes (path fallback)", async () => {
// The review-M2 repro on the bench this knob was added to measure:
// LongMemEval-style session notes carry NO frontmatter (the converter
// writes plain bodies - `sessionNoteBody`), and one long session note
// splits into several chunks that crowd the pool together. Grouped by
// frontmatter alone, the cap changed nothing here, byte for byte; with
// the path fallback every chunk of one note is one group, so the pinned
// cap drops real rows. The knob NAME and its value semantics ride the
// exported pin parser and the resolved search config - the two seams
// `--pin '{"recall":{"poolMaxPerSession":N}}'` flows through.
const v = createTempVault("pool-cap-bench-pin");
try {
for (const session of [1, 2, 3]) {
const body = Array.from(
{ length: 300 },
(_, i) =>
`Turn ${i}: the widget calibration routine number ${i % 40} appears in session ${session} ` +
`near marker ${i} of note ${session}, with enough surrounding words to force the chunker ` +
`to split this session note into several chunks.`,
).join("\n");
writeMd(
v.vault,
`sessions/q1/session-${session}.md`,
`# Session ${session} (question q1)\n\n${body}\n`,
);
}
const base = withRecall(
makeConfig({ vault: v.vault, dbPath: v.dbPath, maxHops: 0, mmrLambda: 1 }),
{ recencyAmplitude: 0 },
);
await indexVault(base, {});
const pin = parseBenchPinnedKnobs('{"recall":{"poolMaxPerSession":1}}');
expect(pin.recall?.poolMaxPerSession).toBe(1);
const pinned = withRecall(base, { poolMaxPerSession: pin.recall?.poolMaxPerSession });
const uncapped = await search(base, { query: "widget calibration", limit: LIMIT });
const capped = await search(pinned, { query: "widget calibration", limit: LIMIT });
// The uncapped pool is the crowding itself: one frontmatter-less
// session note fills the window with its own chunks.
expect(uncapped.total).toBeGreaterThanOrEqual(LIMIT);
const crowdedPath = uncapped.results[0]?.path;
expect(uncapped.results.filter((r) => r.path === crowdedPath).length).toBeGreaterThan(1);
// NON-ZERO drops: the pin measurably narrows the pool over notes
// that carry no session frontmatter at all.
const entry = degradationOf(capped, RETRIEVAL_DEGRADATION.sourceSessionCappedRows);
expect(entry?.detail?.dropped).toBeGreaterThan(0);
// Cap 1 per note: no session note contributes two rows to the answer
// any more, and the answer is not the uncapped bytes.
const byPath = new Map<string, number>();
for (const r of capped.results) byPath.set(r.path, (byPath.get(r.path) ?? 0) + 1);
expect([...byPath.values()].every((n) => n === 1)).toBe(true);
expect(JSON.stringify(capped)).not.toBe(JSON.stringify(uncapped));
} finally {
v.cleanup();
}
});
test("a fractional or negative per-query override is refused by name", async () => {
// The per-query override used to bypass the config validation: 1.5
// turned the cap on with a fractional comparison (seen >= 1.5 kept two
// rows), NaN read as off, a negative as drop-everything. The search
// entry refuses all three through the same named INVALID_INPUT path
// the config key is judged by.
const v = await indexedCrowdedVault();
try {
await expect(
search(v.cold, { query: CROWDED_QUERY, limit: LIMIT, poolMaxPerSession: 1.5 }),
).rejects.toThrow(/poolMaxPerSession/);
await expect(
search(v.cold, { query: CROWDED_QUERY, limit: LIMIT, poolMaxPerSession: Number.NaN }),
).rejects.toThrow(/poolMaxPerSession/);
await expect(
search(v.cold, { query: CROWDED_QUERY, limit: LIMIT, poolMaxPerSession: -2 }),
).rejects.toThrow(/poolMaxPerSession/);
} finally {
v.cleanup();
}
});
test("a cap at or above the pool width it would judge is treated as off", async () => {
// The review-L4 upper bound: a huge cap turned the phase on, read
// frontmatter for every row, and dropped nothing. At or above the
// resolved pool width the cap cannot drop a row, so it is off - the
// answer is the default-off run's exact bytes and no session-cap note
// appears. The configured value still folds into the fingerprint
// (pinned in config.test.ts), so crossing this boundary can never
// serve a stale cached row.
const v = await indexedCrowdedVault();
try {
const huge = await search(withRecall(v.cold, { poolMaxPerSession: 10_000 }), {
query: CROWDED_QUERY,
limit: LIMIT,
});
const off = await search(v.cold, { query: CROWDED_QUERY, limit: LIMIT });
expect(JSON.stringify(huge)).toBe(JSON.stringify(off));
expect(degradationOf(huge, RETRIEVAL_DEGRADATION.sourceSessionCappedRows)).toBeUndefined();
// The boundary is the width the cap would judge when on - for a
// plain limit-3 query, the widened 30. Below it the phase still runs
// and bites (the crowded session holds 6 rows, so cap 5 drops one);
// at or above it - 30 exactly, one past it, and far past it - the
// answer is the off run's bytes.
const justUnder = await search(withRecall(v.cold, { poolMaxPerSession: 5 }), {
query: CROWDED_QUERY,
limit: LIMIT,
});
expect(degradationOf(justUnder, RETRIEVAL_DEGRADATION.sourceSessionCappedRows)?.detail).toEqual(
{ dropped: 1, cap: 5 },
);
const atBoundary = await search(withRecall(v.cold, { poolMaxPerSession: 30 }), {
query: CROWDED_QUERY,
limit: LIMIT,
});
expect(JSON.stringify(atBoundary)).toBe(JSON.stringify(off));
const onePast = await search(withRecall(v.cold, { poolMaxPerSession: 31 }), {
query: CROWDED_QUERY,
limit: LIMIT,
});
expect(JSON.stringify(onePast)).toBe(JSON.stringify(off));
const farPast = await search(withRecall(v.cold, { poolMaxPerSession: 120 }), {
query: CROWDED_QUERY,
limit: LIMIT,
});
expect(JSON.stringify(farPast)).toBe(JSON.stringify(off));
} finally {
v.cleanup();
}
});