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
/**
* Embedding-provider contract. The interface every embedding provider
* implements, split out from the factory (`provider.ts`) so implementations
* depend only on this leaf and never on the module that constructs them.
*
* Anchored in docs/plans/2026-05-16-brain-search-design.md §11.
*/
/**
* Instruction-prefix kind for an embed call (memory-write-path-integrity B2).
* Asymmetric-instruction embedding families (e5) expect a different lead-in
* for a search query versus an indexed passage. The kind is optional and
* additive: a provider that ignores it, or a call that omits it, embeds the
* raw text unchanged.
*/
export type EmbedKind = "query" | "passage";
/** Per-call options a provider may honour. */
export interface EmbedCallOptions {
/** The caller's cancellation: an aborted call stops its requests. */
readonly signal?: AbortSignal;
/**
* The dispatch report (recall-lane-latency): invoked once per call,
* for the first batch whose request is about to go on the wire - the
* moment the caller's embed interval actually starts, not an earlier
* pre-call instant. A provider that never dispatches (the offline
* local embedder, or one built before the callback existed) never
* calls it, and callers keep their own fallback stamp for that case.
*/
readonly onDispatch?: () => void;
}
/**
* What a `ping` learned when it did not get a vector back.
*
* `timedOut` is set ONLY when the provider attributes the failure to its
* own request budget elapsing rather than to an answer it received. Absent
* means the provider makes no such claim - which is not a claim that it
* did not time out, and readers must treat it as "not stated" rather than
* as "false". It is optional and additive, in the same shape as
* {@link EmbeddingProvider.consumeRetryCount}: a provider that cannot tell
* the two apart keeps returning exactly what it returned before.
*
* The distinction is load-bearing for the `o2b search check` pre-flight
* (wiring-what-exists, E1): a provider that answered and refused is a
* fault, while a provider that never answered is a measurement that did
* not complete, and the two must not share an exit code.
*/
export interface PingFailure {
readonly ok: false;
readonly reason: string;
readonly timedOut?: boolean;
}
export type PingResult = { readonly ok: true; readonly dimension: number } | PingFailure;
export interface EmbeddingProvider {
readonly name: string;
readonly model: string;
readonly dimension: number | null;
embed(
texts: ReadonlyArray<string>,
kind?: EmbedKind,
opts?: EmbedCallOptions,
): Promise<number[][]>;
ping(): Promise<PingResult>;
/**
* Optional read-and-reset of provider-internal retry tally. The
* indexer consumes this after each `embed()` to populate
* `IndexStats.embeddingsRetries`. Providers that never retry
* (NullProvider) leave this undefined.
*/
consumeRetryCount?(): number;
/**
* Whether this provider produces vectors at all
* (provenance-at-the-boundary, F2). Read through
* {@link providerProducesVectors}, never directly.
*
* Four call sites used to answer this by comparing `name` to the
* literal `"null"`, so any provider registered under a different name
* bypassed all four silently. The question belongs to the contract, so
* the contract answers it.
*
* Optional and additive, in the same shape as `consumeRetryCount`
* above. An absent declaration means "produces vectors", which is the
* truthful default for every implementation that is a real embedder -
* it is not a fallback covering a failure, because there is no failure
* here to cover: a provider that CANNOT embed is a configuration
* sentinel, and a sentinel is written knowing it is one.
*/
readonly producesVectors?: boolean;
}
/**
* True when `provider` embeds text. The single predicate every site that
* needs to tell a real provider from the configuration sentinel calls -
* `resolveConfiguredEmbeddingProvider`, the hygiene dedup detector, and
* the readiness probe.
*/
export function providerProducesVectors(provider: EmbeddingProvider): boolean {
return provider.producesVectors ?? true;
}