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
/**
* Structural vault navmap (retrieval-quality-and-context-delivery, D1).
*
* The additive nav tier injects a navigation/map layer built ENTIRELY from
* deterministic structural surfaces - never LLM-authored text. The map is the
* vault's link-graph shape: its size (documents / edges) plus the highest-degree
* notes, which are the de-facto hubs and Maps of Content an agent should orient
* around before re-reading raw notes.
*
* This module reuses the existing {@link graphStats} surface (O(1) over the
* cached graph snapshot) rather than re-deriving any graph analysis, and keeps
* the pure rendering ({@link renderNavmap}) separate from the store access
* ({@link buildNavmap}) so the render is unit-testable without an index.
*/
import { fenceUntrustedContent, neutralizeSingleLine } from "./untrusted-source.ts";
import { graphStats, type GraphStats } from "./link-graph/graph-index.ts";
import { resolveSearchConfig } from "../search/index.ts";
import { Store } from "../search/store.ts";
import { SearchError } from "../search/types.ts";
/** Default number of hubs surfaced in the navmap. */
export const NAVMAP_DEFAULT_TOP_HUBS = 8;
/** `origin` label stamped on the navmap's untrusted-content fence. */
const NAVMAP_FENCE_ORIGIN = "nav-tier";
/** One hub note: a vault-relative path and its undirected link degree. */
export interface NavmapEntry {
readonly path: string;
readonly degree: number;
}
/** The structural navmap: vault-graph size plus the top hubs by degree. */
export interface Navmap {
readonly documentCount: number;
readonly nodeCount: number;
readonly edgeCount: number;
readonly hubs: ReadonlyArray<NavmapEntry>;
}
export interface BuildNavmapOptions {
readonly topHubs?: number;
}
/**
* Project the graph-stats surface onto the narrow navmap shape. Pure and
* I/O-free so it is trivially testable and deterministic.
*/
export function deriveNavmap(stats: GraphStats): Navmap {
return Object.freeze({
documentCount: stats.documentCount,
nodeCount: stats.nodeCount,
edgeCount: stats.edgeCount,
hubs: Object.freeze(
stats.topByDegree.map((e) => Object.freeze({ path: e.path, degree: e.degree })),
),
});
}
/**
* Render the navmap as a deterministic, fenced structural block. Returns an
* empty string when there are no hubs (an all-orphan or empty graph has no map
* worth injecting), so the caller can treat "empty" as "nothing to inject".
*/
export function renderNavmap(navmap: Navmap): string {
if (navmap.hubs.length === 0) return "";
const header = `Vault navmap (structural: ${navmap.documentCount} notes, ${navmap.edgeCount} links):`;
const hubHeader = "Top hubs by connectivity (query these before re-reading raw notes):";
const hubLines = navmap.hubs.map(
(hub) => `- ${neutralizeSingleLine(hub.path)} (deg ${hub.degree})`,
);
const body = [header, hubHeader, ...hubLines].join("\n");
return fenceUntrustedContent(body, NAVMAP_FENCE_ORIGIN);
}
/**
* Build the navmap for a vault by reading the existing search index's link
* graph. Returns `null` (fail-open) when there is no index yet or the graph has
* no hubs to map - the nav tier then injects nothing, exactly as when the tier
* is off. A genuinely unexpected store error is NOT swallowed here; the caller
* (a fail-soft hook) is the single place that decides how to degrade.
*/
export async function buildNavmap(
vault: string,
configPath: string,
opts: BuildNavmapOptions = {},
): Promise<Navmap | null> {
const searchConfig = resolveSearchConfig({ vault, configPath });
let store: Store;
try {
store = await Store.open(searchConfig, { mode: "read" });
} catch (exc) {
if (
exc instanceof SearchError &&
(exc.code === "INDEX_MISSING" || exc.code === "SCHEMA_MISMATCH")
) {
return null;
}
throw exc;
}
try {
const stats = graphStats(store, { top: opts.topHubs ?? NAVMAP_DEFAULT_TOP_HUBS });
const navmap = deriveNavmap(stats);
return navmap.hubs.length > 0 ? navmap : null;
} finally {
await store.close();
}
}