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
/**
* Graph-index query pre-pass (Retrieval & Ranking Quality, t_59ae326f).
*
* A read-planning stage that decides WHICH notes are worth opening, and
* can answer from index metadata alone. Given a query it:
*
* 1. Ranks candidate notes by title / summary term match, wikilink
* degree, and (optional) tier weight - the "seeds".
* 2. Connects the top seeds through MULTI-HOP BFS over the resolved
* wikilink graph (the existing `getGraphSnapshot` undirected
* adjacency), so a note reachable only via several link hops is
* surfaced - the capability the 1-hop link boost in the ranker lacks.
* 3. Returns a `should_read` shortlist instead of hydrating chunks
* blindly.
*
* In `index_only` mode it ranks and answers from the index (path, title,
* degree, link paths) with ZERO note bodies read - only `documentTitles`
* (a `documents`-table read) is consulted. This complements `recall_gate`
* (decides IF to recall) and `context_pack` (budget-bounds WHAT is
* injected) with a WHICH-to-read planner. Pure-stdlib, no new dependency.
*/
import { Store } from "./store.ts";
import { getGraphSnapshot } from "../brain/link-graph/graph-index.ts";
import type { ResolvedSearchConfig } from "./types.ts";
/** One entry in the should-read shortlist. */
export interface ShouldReadEntry {
readonly documentId: number;
readonly path: string;
readonly title: string | null;
readonly degree: number;
/** Minimum link-hops from any seed (0 = the note is itself a seed). */
readonly hops: number;
readonly score: number;
/** Preview of the note head; null in index_only mode (no body read). */
readonly summary: string | null;
/** Explainable contributions, e.g. ["title", "degree", "bfs:2"]. */
readonly reasons: ReadonlyArray<string>;
}
export interface GraphPrepassResult {
readonly mode: "should_read" | "index_only";
readonly shortlist: ReadonlyArray<ShouldReadEntry>;
/** Count of note bodies hydrated (always 0 in index_only mode). */
readonly notesRead: number;
}
export interface GraphPrepassOptions {
/** Answer from index metadata with zero note bodies read. */
readonly indexOnly?: boolean;
/** Max seeds carried into BFS (default 10). */
readonly seedLimit?: number;
/** BFS hop depth over the wikilink graph (default 2). */
readonly maxHops?: number;
/** Per-hop score multiplier in (0, 1] (default 0.5). */
readonly hopDecay?: number;
/** Max shortlist entries returned (default 10). */
readonly shortlistLimit?: number;
/** Weight of the normalized wikilink degree signal (default 0.15). */
readonly degreeWeight?: number;
/** Summary-preview length in characters for should_read mode (default 200). */
readonly summaryChars?: number;
}
const WORD_RE = /[\p{L}\p{N}]{2,}/gu;
function queryTerms(query: string): string[] {
const out = new Set<string>();
for (const m of query.toLowerCase().matchAll(WORD_RE)) out.add(m[0]);
return [...out];
}
/** Fraction of query terms present in `text` (case-insensitive substring). */
function termMatchFraction(text: string | null, terms: ReadonlyArray<string>): number {
if (!text || terms.length === 0) return 0;
const hay = text.toLowerCase();
let hits = 0;
for (const t of terms) if (hay.includes(t)) hits++;
return hits / terms.length;
}
/**
* Plan a should-read shortlist for a query. Deterministic: ties break by
* ascending path, so identical index + query yields identical output.
*/
export function planReadShortlist(
store: Store,
query: string,
opts: GraphPrepassOptions = {},
): GraphPrepassResult {
const indexOnly = opts.indexOnly === true;
const seedLimit = Math.max(1, Math.floor(opts.seedLimit ?? 10));
const maxHops = Math.max(0, Math.floor(opts.maxHops ?? 2));
const hopDecay = opts.hopDecay ?? 0.5;
const shortlistLimit = Math.max(1, Math.floor(opts.shortlistLimit ?? 10));
const degreeWeight = opts.degreeWeight ?? 0.15;
const summaryChars = Math.max(0, Math.floor(opts.summaryChars ?? 200));
const snapshot = getGraphSnapshot(store);
const titles = store.documentTitles();
const terms = queryTerms(query);
const maxDegree = Math.max(1, ...[...snapshot.degree.values()], 1);
// ── seed ranking: title match + degree (+ summary match when bodies allowed).
const seedScore = new Map<number, number>();
const seedReasons = new Map<number, string[]>();
// A note becomes a seed only when the query matches its title - degree
// merely BOOSTS a matched seed, it never seeds an unrelated note. This
// keeps the pre-pass query-driven (no match -> no seeds -> empty plan)
// and index-light (title is a `documents`-column read, no body scan).
for (const [id, meta] of titles) {
const titleFrac = termMatchFraction(meta.title, terms);
if (titleFrac <= 0) continue;
const degree = snapshot.degree.get(id) ?? 0;
const degreeNorm = (degree / maxDegree) * degreeWeight;
const reasons = ["title"];
if (degreeNorm > 0) reasons.push("degree");
seedScore.set(id, titleFrac + degreeNorm);
seedReasons.set(id, reasons);
}
// In should_read mode, enrich seeds with a summary-match signal from the
// note head (one representative chunk per candidate seed).
const summaries = new Map<number, string>();
if (!indexOnly && seedScore.size > 0) {
const seedIds = [...seedScore.keys()];
const reps = store.representativeChunks(seedIds);
for (const [id, chunk] of reps) {
const head = chunk.content.slice(0, summaryChars);
summaries.set(id, head);
const frac = termMatchFraction(chunk.content, terms);
if (frac > 0) {
seedScore.set(id, (seedScore.get(id) ?? 0) + frac * 0.5);
const r = seedReasons.get(id) ?? [];
if (!r.includes("summary")) r.push("summary");
seedReasons.set(id, r);
}
}
}
const seeds = [...seedScore.entries()]
.toSorted((a, b) =>
a[1] !== b[1]
? b[1] - a[1]
: (titles.get(a[0])?.path ?? "") < (titles.get(b[0])?.path ?? "")
? -1
: 1,
)
.slice(0, seedLimit);
// ── multi-hop BFS from the seeds over the undirected wikilink graph.
// Each node keeps the best (score, hops) it is reached with.
const best = new Map<number, { score: number; hops: number }>();
for (const [seedId, sScore] of seeds) {
best.set(seedId, { score: sScore, hops: 0 });
}
for (const [seedId, sScore] of seeds) {
let frontier: number[] = [seedId];
const seen = new Set<number>([seedId]);
for (let hop = 1; hop <= maxHops; hop++) {
const next: number[] = [];
const decayed = sScore * hopDecay ** hop;
for (const node of frontier) {
for (const nb of snapshot.adjacency.get(node) ?? []) {
if (seen.has(nb)) continue;
seen.add(nb);
next.push(nb);
const prev = best.get(nb);
if (!prev || decayed > prev.score) best.set(nb, { score: decayed, hops: hop });
else if (decayed > 0 && hop < prev.hops) best.set(nb, { score: prev.score, hops: hop });
}
}
frontier = next;
if (frontier.length === 0) break;
}
}
const seedIdSet = new Set(seeds.map(([id]) => id));
const ranked = [...best.entries()]
.map(([id, v]) => ({ id, ...v }))
.toSorted((a, b) =>
a.score !== b.score
? b.score - a.score
: (titles.get(a.id)?.path ?? "") < (titles.get(b.id)?.path ?? "")
? -1
: 1,
)
.slice(0, shortlistLimit);
const shortlist: ShouldReadEntry[] = ranked.map((r) => {
const meta = titles.get(r.id);
const reasons = [...(seedReasons.get(r.id) ?? [])];
if (!seedIdSet.has(r.id) || r.hops > 0) reasons.push(`bfs:${r.hops}`);
return Object.freeze({
documentId: r.id,
path: meta?.path ?? String(r.id),
title: meta?.title ?? null,
degree: snapshot.degree.get(r.id) ?? 0,
hops: r.hops,
score: r.score,
summary: indexOnly ? null : (summaries.get(r.id) ?? null),
reasons: Object.freeze(reasons),
});
});
return Object.freeze({
mode: indexOnly ? "index_only" : "should_read",
shortlist: Object.freeze(shortlist),
notesRead: indexOnly ? 0 : summaries.size,
});
}
/**
* Config-level wrapper: open a read store, plan the shortlist, close.
* The CLI/MCP surface calls this; unit tests call {@link planReadShortlist}
* directly against an open store.
*/
export async function planRead(
config: ResolvedSearchConfig,
query: string,
opts: GraphPrepassOptions = {},
): Promise<GraphPrepassResult> {
const store = await Store.open(config, { mode: "read", loadVec: false });
try {
return planReadShortlist(store, query, opts);
} finally {
await store.close();
}
}