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
/**
* Ranked query mode on the context-pack lane (v1.53.0).
*
* The lane's only query facility was a case-insensitive SUBSTRING match of
* the whole query against `topic + principle`, so a natural-language turn
* `filter-miss`ed every candidate and the pack came back empty. Ranked mode
* ORDERS the already-collected candidates by structural token overlap
* instead of excluding them, which keeps the guard, the curated pool, the
* tip preference, the owner scope, the budget, and the receipt that only
* exist on this lane.
*
* Claims pinned here:
* 1. `queryMode` absent is byte-identical to `queryMode: "substring"` -
* the substring filter, and its `filter-miss` skips, are untouched.
* 2. A natural-language turn substring-misses everything (the defect).
* 3. Ranked mode excludes nothing: no `filter-miss` skip is ever emitted.
* 4. Ranked mode orders the query-relevant candidate first WITHIN its tier.
* 5. Tier stays the coarse gate: a relevant peripheral page never outranks
* an irrelevant core one.
* 6. Under a budget that fits one page, ranked mode spends it on the
* relevant page and reports the rest as `over-budget`, not `filter-miss`.
* 7. `queryMode: "ranked"` with no query changes nothing.
* 8. Receipt emission and the character budget are unaffected by the mode.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { packContext } from "../../../src/core/brain/context-pack.ts";
let vault: string;
const PRICING_TURN = "which pricing rule applies to this enterprise quote";
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-pack-ranked-"));
mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
mkdirSync(join(vault, "Brain", "retired"), { recursive: true });
});
afterEach(() => {
rmSync(vault, { recursive: true, force: true });
});
function writePref(
slug: string,
fields: { topic: string; principle: string; tier?: string; created_at?: string; body?: string },
): void {
const lines = [
"---",
`id: pref-${slug}`,
`topic: ${fields.topic}`,
`principle: ${fields.principle}`,
];
if (fields.tier) lines.push(`tier: ${fields.tier}`);
lines.push(`created_at: ${fields.created_at ?? "2026-01-01T00:00:00Z"}`);
lines.push("---", "", fields.body ?? fields.principle);
writeFileSync(join(vault, "Brain", "preferences", `pref-${slug}.md`), lines.join("\n"));
}
/** Three core preferences, only one of which is about pricing. */
function writeThreeCorePreferences(): void {
writePref("deploy", {
topic: "deployment window",
principle: "never ship on friday",
tier: "core",
created_at: "2026-01-03T00:00:00Z",
});
writePref("pricing", {
topic: "pricing rules",
principle: "quote the enterprise tier before applying any discount",
tier: "core",
created_at: "2026-01-02T00:00:00Z",
});
writePref("imports", {
topic: "module imports",
principle: "use explicit imports only",
tier: "core",
created_at: "2026-01-01T00:00:00Z",
});
}
describe("context pack ranked query mode", () => {
test("an absent queryMode is byte-identical to the substring default", () => {
writeThreeCorePreferences();
const absent = packContext(vault, { maxTokens: 10_000, query: "pricing" });
const explicit = packContext(vault, {
maxTokens: 10_000,
query: "pricing",
queryMode: "substring",
});
expect(JSON.stringify(explicit)).toBe(JSON.stringify(absent));
expect(absent.items.map((i) => i.id)).toEqual(["pref-pricing"]);
expect(absent.skipped.map((s) => s.reason)).toEqual(["filter-miss", "filter-miss"]);
});
test("substring mode misses every candidate on a natural-language turn", () => {
writeThreeCorePreferences();
const r = packContext(vault, { maxTokens: 10_000, query: PRICING_TURN });
expect(r.items).toEqual([]);
expect(r.skipped.every((s) => s.reason === "filter-miss")).toBe(true);
expect(r.skipped.length).toBe(3);
});
test("ranked mode excludes nothing and orders the relevant page first", () => {
writeThreeCorePreferences();
const r = packContext(vault, {
maxTokens: 10_000,
query: PRICING_TURN,
queryMode: "ranked",
});
expect(r.skipped).toEqual([]);
expect(r.items.map((i) => i.id)).toEqual(["pref-pricing", "pref-deploy", "pref-imports"]);
});
test("tier stays the coarse gate over relevance", () => {
writePref("pricing", {
topic: "pricing rules",
principle: "quote the enterprise tier before applying any discount",
tier: "peripheral",
});
writePref("deploy", {
topic: "deployment window",
principle: "never ship on friday",
tier: "core",
});
const r = packContext(vault, {
maxTokens: 10_000,
query: PRICING_TURN,
queryMode: "ranked",
});
expect(r.items.map((i) => i.id)).toEqual(["pref-deploy", "pref-pricing"]);
});
test("a budget that fits one page is spent on the relevant page", () => {
writeThreeCorePreferences();
const full = packContext(vault, {
maxTokens: 10_000,
query: PRICING_TURN,
queryMode: "ranked",
});
const pricingTokens = full.items.find((i) => i.id === "pref-pricing")!.tokens;
const r = packContext(vault, {
maxTokens: pricingTokens,
query: PRICING_TURN,
queryMode: "ranked",
});
expect(r.items.map((i) => i.id)).toEqual(["pref-pricing"]);
expect(r.skipped.map((s) => s.reason)).toEqual(["over-budget", "over-budget"]);
});
test("ranked mode with no query leaves the default ordering untouched", () => {
writeThreeCorePreferences();
const plain = packContext(vault, { maxTokens: 10_000 });
const ranked = packContext(vault, { maxTokens: 10_000, queryMode: "ranked" });
expect(JSON.stringify(ranked)).toBe(JSON.stringify(plain));
});
test("the receipt and the character budget survive ranked mode", () => {
writeThreeCorePreferences();
const r = packContext(vault, {
maxTokens: 10_000,
query: PRICING_TURN,
queryMode: "ranked",
maxCharsPerMemory: 12,
receipt: { trigger: "context_pack", host: "hermes" },
});
expect(typeof r.receiptId).toBe("string");
expect(r.receiptId!.length).toBeGreaterThan(0);
expect(r.items.every((i) => i.trimmed)).toBe(true);
expect(r.items.every((i) => i.body.length <= 12)).toBe(true);
});
});