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
/**
* Rerank-provider registry (retrieval-precision-quality-loop, card A /
* t_110867f5).
*
* Named cross-encoder provider profiles persisted to
* `Brain/search/rerank-providers.json`, added and removed at runtime
* through the CLI so users register an OpenAI-compatible rerank endpoint
* without editing config. A registered name resolves to `base_url +
* model + env-key` at config-resolution time (see
* {@link expandRegisteredRerankProvider}); an explicit `search_rerank_*`
* config/env value always wins over the profile's field.
*
* Only env-key NAMES are stored, never secret values - the file is safe
* to sync. Loading is fail-soft: an absent or malformed registry yields
* an empty list and never throws into the hot path.
*
* Mirrors `embeddings/registry.ts` deliberately: the two registries are
* the same shape so the CLI verbs, validation, and on-disk determinism
* stay consistent between the embedding and rerank surfaces.
*/
import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { dirname } from "node:path";
import { SearchError } from "../types.ts";
import { BRAIN_ROOT_REL } from "../../brain/path-constants.ts";
import { machineStatePath } from "../../state/machine-state.ts";
/** A registered OpenAI-compatible rerank provider profile. */
export interface RerankProviderProfile {
readonly name: string;
readonly baseUrl: string;
readonly defaultModel: string;
/** Environment variable NAME the API key is read from (never the key). */
readonly envKey: string;
}
const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
export function rerankRegistryPath(vault: string | null): string {
return machineStatePath(vault, BRAIN_ROOT_REL, "search", "rerank-providers.json");
}
function isProfile(value: unknown): value is RerankProviderProfile {
if (value === null || typeof value !== "object") return false;
const v = value as Record<string, unknown>;
return (
typeof v["name"] === "string" &&
typeof v["baseUrl"] === "string" &&
typeof v["defaultModel"] === "string" &&
typeof v["envKey"] === "string"
);
}
/** Load the registry, fail-soft: absent or malformed file -> empty list. */
export function loadRerankRegistry(vault: string | null): RerankProviderProfile[] {
let text: string;
try {
text = readFileSync(rerankRegistryPath(vault), "utf8");
} catch {
return [];
}
let parsed: unknown;
try {
parsed = JSON.parse(text);
} catch {
return [];
}
if (!Array.isArray(parsed)) return [];
return parsed.filter(isProfile).map((p) => Object.freeze({ ...p }));
}
function writeRerankRegistry(
vault: string | null,
registry: ReadonlyArray<RerankProviderProfile>,
): void {
const path = rerankRegistryPath(vault);
mkdirSync(dirname(path), { recursive: true });
// Sort by name so the on-disk file is deterministic across edits.
const sorted = [...registry].toSorted((a, b) => a.name.localeCompare(b.name));
writeFileSync(path, JSON.stringify(sorted, null, 2) + "\n");
}
function validateProfile(profile: RerankProviderProfile): void {
const name = profile.name.trim();
if (!NAME_RE.test(name)) {
throw new SearchError(
"INVALID_INPUT",
`rerank provider name must be a lowercase slug ([a-z0-9-], starting alphanumeric), got '${profile.name}'`,
);
}
if (profile.baseUrl.trim() === "") {
throw new SearchError("INVALID_INPUT", "rerank provider base-url must not be empty");
}
if (profile.defaultModel.trim() === "") {
throw new SearchError("INVALID_INPUT", "rerank provider default-model must not be empty");
}
if (profile.envKey.trim() === "") {
throw new SearchError("INVALID_INPUT", "rerank provider env-key must not be empty");
}
}
/**
* Add (or upsert by name) a rerank provider profile and persist. Returns
* the full registry after the change.
*/
export function addRerankProviderProfile(
vault: string | null,
profile: RerankProviderProfile,
): RerankProviderProfile[] {
validateProfile(profile);
const normalised: RerankProviderProfile = Object.freeze({
name: profile.name.trim(),
baseUrl: profile.baseUrl.trim(),
defaultModel: profile.defaultModel.trim(),
envKey: profile.envKey.trim(),
});
const without = loadRerankRegistry(vault).filter((p) => p.name !== normalised.name);
const next = [...without, normalised];
writeRerankRegistry(vault, next);
return loadRerankRegistry(vault);
}
/** Remove a profile by name; reports whether one was present. */
export function removeRerankProviderProfile(
vault: string | null,
name: string,
): { removed: boolean; registry: RerankProviderProfile[] } {
const current = loadRerankRegistry(vault);
const next = current.filter((p) => p.name !== name);
const removed = next.length !== current.length;
if (removed) writeRerankRegistry(vault, next);
return { removed, registry: loadRerankRegistry(vault) };
}
export function getRerankProviderProfile(
vault: string | null,
name: string,
): RerankProviderProfile | null {
return loadRerankRegistry(vault).find((p) => p.name === name) ?? null;
}
/** Fields a registered name expands into at config-resolution time. */
export interface ExpandedRerankProvider {
readonly baseUrl: string;
readonly model: string;
readonly envKey: string;
}
/**
* Expand a registered rerank provider name into its endpoint fields.
* Returns null when the name is not registered (the caller then relies on
* the explicit `search_rerank_*` config keys alone).
*/
export function expandRegisteredRerankProvider(
name: string,
registry: ReadonlyArray<RerankProviderProfile>,
): ExpandedRerankProvider | null {
const profile = registry.find((p) => p.name === name);
if (!profile) return null;
return Object.freeze({
baseUrl: profile.baseUrl,
model: profile.defaultModel,
envKey: profile.envKey,
});
}