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
/**
* Link-graph traversal during recall. Two-stage retrieve-then-walk:
* after relevance ranking, follow outbound wikilinks from the top hits
* and surface linked documents scored as parent_score * hop_decay^hop,
* bounded by max_hops and max_expansion_per_hit, deduped against the
* existing result set. Pure function over precomputed inputs.
*/
import { test, expect } from "bun:test";
import { expandByTraversal } from "../../../src/core/search/traversal.ts";
import type { BrainSearchResult } from "../../../src/core/search/types.ts";
import type { TraversalDoc } from "../../../src/core/search/traversal.ts";
let nextChunk = 100;
function res(docId: number, score: number): BrainSearchResult {
const chunkId = nextChunk++;
return Object.freeze({
documentId: docId,
chunkId,
path: `doc${docId}.md`,
title: `Doc ${docId}`,
content: `content of ${docId}`,
startLine: 1,
endLine: 1,
score,
keywordScore: score,
semanticScore: 0,
linkBoost: 0,
recencyBoost: 0,
searchType: "keyword" as const,
reasons: Object.freeze([`fts5_bm25: ${score.toFixed(3)}`]),
});
}
function docFor(docId: number): TraversalDoc {
return {
documentId: docId,
chunkId: 900 + docId,
path: `doc${docId}.md`,
title: `Doc ${docId}`,
content: `content of ${docId}`,
startLine: 1,
endLine: 1,
};
}
const OPTS = { maxHops: 1, hopDecay: 0.5, maxExpansionPerHit: 3 };
test("maxHops == 0 returns the ranked set unchanged", () => {
const ranked = [res(1, 0.8)];
const out = expandByTraversal(
{
ranked,
outbound: new Map([[1, [2]]]),
expansionDoc: docFor,
},
{ ...OPTS, maxHops: 0 },
);
expect(out).toEqual(ranked);
});
test("a doc linked from a top hit is surfaced with a decayed score", () => {
const out = expandByTraversal(
{
ranked: [res(1, 0.8)],
outbound: new Map([[1, [2]]]),
expansionDoc: docFor,
},
OPTS,
);
const added = out.find((r) => r.documentId === 2);
expect(added).toBeDefined();
expect(added!.score).toBeCloseTo(0.4, 6); // 0.8 * 0.5
expect(added!.searchType).toBe("link");
expect(added!.reasons.some((x) => x.startsWith("link_traversal"))).toBe(true);
});
test("a doc already present is not duplicated and keeps its higher score", () => {
const out = expandByTraversal(
{
ranked: [res(1, 0.8), res(2, 0.7)],
outbound: new Map([[1, [2]]]),
expansionDoc: docFor,
},
OPTS,
);
const twos = out.filter((r) => r.documentId === 2);
expect(twos).toHaveLength(1);
expect(twos[0]!.score).toBeCloseTo(0.7, 6); // original relevance, not 0.4
});
test("expansion per hit is capped by maxExpansionPerHit", () => {
const out = expandByTraversal(
{
ranked: [res(1, 0.8)],
outbound: new Map([[1, [2, 3, 4, 5, 6]]]),
expansionDoc: docFor,
},
{ ...OPTS, maxExpansionPerHit: 2 },
);
const added = out.filter((r) => r.searchType === "link");
expect(added).toHaveLength(2);
});
test("decay compounds across hops up to maxHops", () => {
const out = expandByTraversal(
{
ranked: [res(1, 0.8)],
outbound: new Map([
[1, [2]],
[2, [3]],
]),
expansionDoc: docFor,
},
{ maxHops: 2, hopDecay: 0.5, maxExpansionPerHit: 3 },
);
const c = out.find((r) => r.documentId === 3);
expect(c).toBeDefined();
expect(c!.score).toBeCloseTo(0.2, 6); // 0.8 * 0.5 * 0.5
});
test("results stay sorted by score descending after expansion", () => {
const out = expandByTraversal(
{
ranked: [res(1, 0.8), res(9, 0.3)],
outbound: new Map([[1, [2]]]),
expansionDoc: docFor,
},
OPTS,
);
const scores = out.map((r) => r.score);
const sorted = [...scores].toSorted((a, b) => b - a);
expect(scores).toEqual(sorted);
});