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
/**
* Semantic candidate lane: the on/off policy the caller's options resolve
* to, the candidate-pool over-fetch sizing, and the guarded semantic
* phase that embeds the query and runs the vector top-K (self-degrading
* to keyword-only with warnings when the lane cannot run).
*/
import {
BLOCKED_TIER_ERROR_CODE,
isBlockedCapability,
resolveSemanticCapability,
semanticCapabilityLabel,
SEMANTIC_CAPABILITY_TIER,
} from "./capability-tier.ts";
import { classifyEmbeddingError } from "./embeddings/openai-compat.ts";
import { makeProvider } from "./embeddings/provider.ts";
import {
prepareQueryEmbed,
queryEmbedCutMessage,
queryEmbedEmptyFitMessage,
queryEmbedRefusalMessage,
} from "./embeddings/query-embed.ts";
import { providerConsentIsDeclined, resolveProviderConsent } from "./provider-consent.ts";
import { RETRIEVAL_DEGRADATION, noteDegradation } from "./retrieval-trail.ts";
import { Store } from "./store.ts";
import { EMBEDDING_QUOTA_MESSAGE, SearchError } from "./types.ts";
import type { TransportReach } from "../graph/transport-reach.ts";
import type { PropertyPushdown } from "./property-pushdown.ts";
import type { RetrievalDegradationSink } from "./retrieval-trail.ts";
import type { ResolvedSearchConfig, SearchOptions } from "./types.ts";
export interface SemanticPolicy {
/** caller asked for semantic on or off (true), or accepted the default (false). */
readonly explicit: boolean;
/** does the caller want semantic at all? */
readonly wantSemantic: boolean;
}
export function resolveSemanticPolicy(
config: ResolvedSearchConfig,
opts: SearchOptions,
): SemanticPolicy {
if (opts.keywordOnly === true) {
return { explicit: true, wantSemantic: false };
}
if (opts.semantic === true) return { explicit: true, wantSemantic: true };
if (opts.semantic === false) return { explicit: true, wantSemantic: false };
return { explicit: false, wantSemantic: config.semantic.enabled };
}
/**
* Semantic candidate-pool over-fetch policy: rank more than `limit` rows
* so downstream filtering (property/visibility scope, MMR diversify) has
* enough headroom to still fill the final window. `floor` is the minimum
* pool size regardless of `limit`; `overfetch` is the multiplier applied
* to `limit` itself.
*/
const POOL_OVERFETCH = 5;
const POOL_FLOOR = 50;
export function semanticPoolSize(limit: number): number {
return Math.max(limit * POOL_OVERFETCH, POOL_FLOOR);
}
/**
* The embed interval the phase stamps for the overlapped-lane timing
* (recall-lane-latency). A plain mutable record the JOIN caller owns: the
* lane forwards it, the phase writes it around the one caller wait it
* has, and the caller reads it at the join. Absent stamps mean the embed
* never ran - a pre-flight guard refused before any provider existed.
*/
export interface SemanticEmbedTiming {
/**
* The request's clock port: every stamp below reads through it, so the
* wall clock is read nowhere but the request module (the rank-clock
* census pins the site) and no stamp precedes the instant the request
* was resolved at.
*/
readonly clock: () => number;
/**
* The dispatch stamp: written by the provider's dispatch report, the
* moment the request actually leaves. A provider that never reports a
* dispatch leaves it unset, and the fold falls back to the pre-call
* stamp.
*/
embedStartMs?: number;
/**
* The resolution stamp: written when the phase's continuation around
* the provider promise ran - the answer or the failure came back. It
* is never a claim about any wire event past the call's own return.
*/
embedEndMs?: number;
/**
* The pre-call fallback start: stamped just before the provider call
* for providers that never report a dispatch, so their interval stays
* the whole awaited call, as before the dispatch report existed.
*/
preCallStartMs?: number;
}
interface SemanticPhaseOutcome {
readonly attempted: boolean;
readonly hits: ReturnType<Store["semanticTopK"]>;
readonly warnings: string[];
/**
* The typed half of {@link warnings} (evidence-at-the-boundary, C2).
* Every arm below that returns `attempted: false` names why it did, so
* a caller served keyword-only can tell an unconfigured provider from a
* quota-exhausted one without matching on a sentence.
*/
readonly degraded: RetrievalDegradationSink;
}
export async function runSemanticPhase(
store: Store,
config: ResolvedSearchConfig,
query: string,
opts: {
limit: number;
pathPrefix: string | undefined;
/** Chunk-kind pushdown (recall-quality, C4); absent leaves it unfiltered. */
readonly kind?: "page" | "section";
/** Promoted property pushdown (recall-quality, C4); absent leaves it unfiltered. */
readonly pushdown?: PropertyPushdown;
explicit: boolean;
/**
* The caller's cancellation (the composite hybrid deadline). Once it
* aborts, the query embed stops and the phase rejects with the
* signal's reason, so an abandoned lane never reaches the store.
*/
signal?: AbortSignal;
/**
* How far the caller reached (`SearchOptions.transportReach`). The
* query-embed gateway reads it: absent resolves to remote, as
* everywhere else in the tree.
*/
transportReach?: TransportReach;
/**
* The embed-interval record to stamp (recall-lane-latency), written
* around the embed await. Absent records nothing.
*/
timing?: SemanticEmbedTiming;
},
): Promise<SemanticPhaseOutcome> {
const warnings: string[] = [];
const degraded: RetrievalDegradationSink = [];
// The operator's WRITTEN decision comes before every other arm, and
// before the capability ladder below. A decline is a more specific fact
// than a tier: the tier says what the configuration can do, and it
// cannot say that the operator said no. Reporting the tier for a
// declined vault would answer "not configured" for a configuration that
// was configured on purpose - and the sentence it would use is the one
// that tells an operator to set a provider they deliberately declined.
//
// The record is read from the SAME configuration the search
// configuration was resolved from (`config.configPath`), so the two can
// never disagree about which file is in force.
const consent = resolveProviderConsent({
configPath: config.configPath ?? null,
env: process.env,
semantic: config.semantic,
});
if (providerConsentIsDeclined(consent)) {
if (opts.explicit) throw new SearchError("EMBEDDING_DISABLED", consent.detail);
warnings.push(consent.detail);
noteDegradation(degraded, RETRIEVAL_DEGRADATION.semanticCapabilityBlocked, {
tier: SEMANTIC_CAPABILITY_TIER.disabled,
});
return { attempted: false, hits: [], warnings, degraded };
}
const counts = store.counts();
if (counts.embeddings === 0) {
warnings.push("no compatible embeddings; run: o2b search index --embeddings");
noteDegradation(degraded, RETRIEVAL_DEGRADATION.semanticEmbeddingsAbsent);
return { attempted: false, hits: [], warnings, degraded };
}
if (!store.vecLoaded()) {
if (opts.explicit) {
throw new SearchError(
"VEC_EXTENSION_UNAVAILABLE",
"semantic search unavailable: sqlite-vec extension not loaded",
);
}
warnings.push("sqlite-vec unavailable, semantic disabled this session");
noteDegradation(degraded, RETRIEVAL_DEGRADATION.semanticVecExtensionUnavailable);
return { attempted: false, hits: [], warnings, degraded };
}
// What the OPERATOR CONFIGURED, from the one shared resolver
// (provenance-at-the-boundary, F1). The two runtime guards above stay
// where they are: an empty vector table and a missing extension are
// facts about this index and this machine, not about the configuration.
//
// The explicit arm is the one that ATTEMPTED something and could not,
// so it keeps reporting the typed `SearchError`; the implicit arm
// refused before attempting and reports the capability. Neither
// condition is reported both ways.
//
// EVERY blocked rung throws on the explicit arm, not just the missing
// credential: a caller who asked for semantic recall in so many words and
// was served lexical results with exit 0 was told the search succeeded.
// Both arms name the condition with the SAME registry sentence, so the
// warning and the error message cannot drift apart.
const capability = consent.capability ?? resolveSemanticCapability(config.semantic);
if (isBlockedCapability(capability)) {
const label = await semanticCapabilityLabel(capability.code);
if (opts.explicit) throw new SearchError(BLOCKED_TIER_ERROR_CODE[capability.tier], label);
warnings.push(label);
// The rung is already a closed vocabulary; the label is a registry
// sentence, which is exactly what the trail must not carry.
noteDegradation(degraded, RETRIEVAL_DEGRADATION.semanticCapabilityBlocked, {
tier: capability.tier,
});
return { attempted: false, hits: [], warnings, degraded };
}
// The query-embed gateway (honest-query-embed-and-safe-upgrades): the
// one place that decides whether a query embed is sent at all and with
// what text. It runs before any provider exists, so a refusal sends
// nothing. The explicit arm throws, like every other condition above
// that stops a lane the caller asked for by name; the implicit arm
// degrades by code and the lane is not attempted.
const prepared = prepareQueryEmbed(config, query, opts.transportReach);
if (prepared.kind === "refused") {
const message = queryEmbedRefusalMessage(prepared);
if (opts.explicit) throw new SearchError(prepared.code, message);
warnings.push(message);
noteDegradation(degraded, RETRIEVAL_DEGRADATION.semanticCostUnpriced);
return { attempted: false, hits: [], warnings, degraded };
}
if (prepared.truncated) {
const detail = { windowTokens: prepared.windowTokens };
if (prepared.emptyFit) {
// The instruction prefix alone fills the window: there is no query
// left to embed, and embedding the prefix would search for nothing.
const message = queryEmbedEmptyFitMessage(prepared);
if (opts.explicit) throw new SearchError("INVALID_INPUT", message);
warnings.push(message);
noteDegradation(degraded, RETRIEVAL_DEGRADATION.semanticQueryEmptyFit, detail);
return { attempted: false, hits: [], warnings, degraded };
}
// A cut the server would otherwise make silently (or refuse), made
// here and disclosed. The lane still runs on the cut query.
warnings.push(queryEmbedCutMessage(prepared, query));
noteDegradation(degraded, RETRIEVAL_DEGRADATION.semanticQueryTruncated, detail);
}
let queryVec: number[];
// The embed start is stamped by the provider's dispatch report - the
// moment the request actually leaves, which is the instant overlap is
// measured from. The pre-call stamp below is only the fallback for
// providers that never report a dispatch (the offline local embedder,
// or one built before the callback existed): their interval stays the
// whole awaited call, as before. With no sink there is no stamp and no
// callback, and the call options are exactly what they were.
const timing = opts.timing;
if (timing !== undefined) timing.preCallStartMs = timing.clock();
try {
const provider = makeProvider(config.semantic, consent);
const vectors = await provider.embed(
[prepared.text],
"query",
timing === undefined && opts.signal === undefined
? undefined
: {
...(opts.signal !== undefined ? { signal: opts.signal } : {}),
...(timing !== undefined
? {
onDispatch: () => {
timing.embedStartMs = timing.clock();
},
}
: {}),
},
);
if (timing !== undefined) timing.embedEndMs = timing.clock();
queryVec = vectors[0] ?? [];
} catch (e) {
// The interval closes even on the failure arm: the overlap figure
// stays coherent for a lane that ran and lost its embed.
if (
timing !== undefined &&
(timing.embedStartMs !== undefined || timing.preCallStartMs !== undefined)
) {
timing.embedEndMs = timing.clock();
}
if (opts.signal?.aborted === true) throw opts.signal.reason;
if (opts.explicit) {
// Defensive: provider methods are expected to throw SearchError,
// but wrap anything else (e.g. an unexpected runtime failure)
// so callers always see a typed code rather than a bare Error.
if (e instanceof SearchError) throw e;
const msg = e instanceof Error ? e.message : String(e);
throw new SearchError("EMBEDDING_PROVIDER_HTTP", `embedding provider failure: ${msg}`);
}
// Implicit path: degrade to keyword-only, but the warning must say WHY
// by naming the classification category, and for a quota exhaustion it
// carries the actionable billing message so the CLI/MCP caller learns
// the remediation, not just that semantic was skipped.
const cls = classifyEmbeddingError(e);
const detail =
cls.category === "quota"
? EMBEDDING_QUOTA_MESSAGE
: e instanceof Error
? e.message
: String(e);
warnings.push(`embedding provider unavailable [${cls.category}]: ${detail}`);
// The category is the classification the warning already computed and
// then buried in prose; the provider's own message stays out of the
// trail, which travels into logs and MCP payloads.
noteDegradation(degraded, RETRIEVAL_DEGRADATION.semanticProviderUnavailable, {
category: cls.category,
});
return { attempted: false, hits: [], warnings, degraded };
}
// The caller may have abandoned the lane while the embed was in flight;
// past that point the store it would read can already be closed.
if (opts.signal?.aborted === true) throw opts.signal.reason;
if (queryVec.length === 0) {
warnings.push("embedding provider returned an empty vector; semantic skipped");
noteDegradation(degraded, RETRIEVAL_DEGRADATION.semanticEmptyQueryVector);
return { attempted: false, hits: [], warnings, degraded };
}
const hits = store.semanticTopK(queryVec, {
limit: opts.limit,
pathPrefix: opts.pathPrefix,
...(opts.kind !== undefined ? { kind: opts.kind } : {}),
...(opts.pushdown !== undefined ? { pushdown: opts.pushdown } : {}),
});
return { attempted: true, hits, warnings, degraded };
}