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
/**
* Provider registry (Embedding Provider Suite).
*
* Named provider profiles persisted to
* `Brain/search/embedding-providers.json`, added and removed at runtime
* through the CLI so users register an OpenAI-compatible endpoint
* without editing config. A registered name resolves to `openai-compat`
* config at config-resolution time (see `expandRegisteredProvider`),
* AFTER the built-ins, so a configured built-in key is never shadowed
* and the resolved provider union stays closed.
*
* 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.
*/
import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { dirname } from "node:path";
import { resolveMergedValue } from "../../secret-resolver.ts";
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 provider profile. */
export interface ProviderProfile {
readonly name: string;
readonly baseUrl: string;
readonly defaultModel: string;
/**
* Environment variable NAME(s) the API key is read from (never the key).
* A single string keeps the original single-key behaviour; an ordered
* list is a probe list resolved first-present-wins, with the remaining
* present keys kept as request-time failover candidates.
*/
readonly envKey: string | ReadonlyArray<string>;
}
/** Normalise `envKey` (string | list) to an ordered list of env-var names. */
export function envKeyList(envKey: ProviderProfile["envKey"]): string[] {
const raw = typeof envKey === "string" ? [envKey] : [...envKey];
return raw.map((k) => k.trim()).filter((k) => k !== "");
}
/** Built-in provider names a profile may not reuse. */
export const RESERVED_PROVIDER_NAMES: ReadonlyArray<string> = Object.freeze([
"openai-compat",
"disabled",
"local",
"zeroentropy",
]);
const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
export function providerRegistryPath(vault: string | null): string {
return machineStatePath(vault, BRAIN_ROOT_REL, "search", "embedding-providers.json");
}
function isEnvKey(value: unknown): value is string | ReadonlyArray<string> {
if (typeof value === "string") return true;
return Array.isArray(value) && value.every((k) => typeof k === "string");
}
function isProfile(value: unknown): value is ProviderProfile {
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" &&
isEnvKey(v["envKey"])
);
}
/** Load the registry, fail-soft: absent or malformed file -> empty list. */
export function loadProviderRegistry(vault: string | null): ProviderProfile[] {
let text: string;
try {
text = readFileSync(providerRegistryPath(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 writeProviderRegistry(
vault: string | null,
registry: ReadonlyArray<ProviderProfile>,
): void {
const path = providerRegistryPath(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: ProviderProfile): void {
const name = profile.name.trim();
if (!NAME_RE.test(name)) {
throw new SearchError(
"INVALID_INPUT",
`provider name must be a lowercase slug ([a-z0-9-], starting alphanumeric), got '${profile.name}'`,
);
}
if (RESERVED_PROVIDER_NAMES.includes(name)) {
throw new SearchError(
"INVALID_INPUT",
`provider name '${name}' is reserved for a built-in provider`,
);
}
if (profile.baseUrl.trim() === "") {
throw new SearchError("INVALID_INPUT", "provider base-url must not be empty");
}
if (profile.defaultModel.trim() === "") {
throw new SearchError("INVALID_INPUT", "provider default-model must not be empty");
}
if (envKeyList(profile.envKey).length === 0) {
throw new SearchError(
"INVALID_INPUT",
"provider env-key must not be empty (and a probe list must hold at least one non-empty name)",
);
}
}
/**
* Add (or upsert by name) a provider profile and persist. Returns the
* full registry after the change.
*/
export function addProviderProfile(
vault: string | null,
profile: ProviderProfile,
): ProviderProfile[] {
validateProfile(profile);
const keys = envKeyList(profile.envKey);
const normalised: ProviderProfile = Object.freeze({
name: profile.name.trim(),
baseUrl: profile.baseUrl.trim(),
defaultModel: profile.defaultModel.trim(),
// Preserve the single-string shape for single-key profiles so existing
// registry files stay byte-identical; store a list only when given one.
envKey: typeof profile.envKey === "string" ? keys[0]! : Object.freeze(keys),
});
const without = loadProviderRegistry(vault).filter((p) => p.name !== normalised.name);
const next = [...without, normalised];
writeProviderRegistry(vault, next);
return loadProviderRegistry(vault);
}
/** Remove a profile by name; reports whether one was present. */
export function removeProviderProfile(
vault: string | null,
name: string,
): { removed: boolean; registry: ProviderProfile[] } {
const current = loadProviderRegistry(vault);
const next = current.filter((p) => p.name !== name);
const removed = next.length !== current.length;
if (removed) writeProviderRegistry(vault, next);
return { removed, registry: loadProviderRegistry(vault) };
}
export function getProviderProfile(vault: string | null, name: string): ProviderProfile | null {
return loadProviderRegistry(vault).find((p) => p.name === name) ?? null;
}
/** Fields a registered name expands into at config-resolution time. */
export interface ExpandedProvider {
readonly provider: "openai-compat";
readonly baseUrl: string;
readonly model: string;
/** First present probe key (backward-compatible single value); null if none set. */
readonly apiKey: string | null;
/** All present probe keys in profile order; request-time failover candidates. */
readonly apiKeys: ReadonlyArray<string>;
}
/** Options for expanding a registered name against merged key sources. */
export interface ExpandRegisteredProviderOptions {
/**
* Vault whose custody store joins the probe ahead of `env`: a probe
* name the store holds answers first, and a probe entry written as a
* `$secret:NAME` reference resolves through the same store (read-only,
* no usage stamp). Absent, the probe reads `env` exactly as before.
*/
readonly secretsVault?: string;
}
/**
* Expand a registered provider name into `openai-compat` config, resolving
* the API key(s) from the profile's `envKey` probe list (first-present
* wins; the rest are kept as failover candidates). Returns null when the
* name is not registered (the caller then falls back to built-in
* resolution).
*/
export function expandRegisteredProvider(
name: string,
registry: ReadonlyArray<ProviderProfile>,
env: Readonly<Record<string, string | undefined>>,
opts: ExpandRegisteredProviderOptions = {},
): ExpandedProvider | null {
const profile = registry.find((p) => p.name === name);
if (!profile) return null;
const present = envKeyList(profile.envKey)
.map((varName) =>
opts.secretsVault === undefined
? env[varName]
: resolveMergedValue(opts.secretsVault, env, varName),
)
.filter((v): v is string => v !== undefined && v !== "");
return Object.freeze({
provider: "openai-compat" as const,
baseUrl: profile.baseUrl,
model: profile.defaultModel,
apiKey: present[0] ?? null,
apiKeys: Object.freeze(present),
});
}