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
/**
* Pure query analysis (v0.20.0): the single seam where a query is
* inspected before retrieval. It produces a {@link QueryPlan} carrying a
* structural intent, a bounded ranking {@link WeightProfile}, the
* synonym-expansion terms (populated by `synonyms.ts`), and a stable
* `planHash` used in the query-cache key.
*
* LANGUAGE-AGNOSTIC INVARIANT (audited here, in one place): intent and
* expansion derive ONLY from structural signals - quoted spans, FTS
* wildcards, wikilink shapes, the share of entity-like tokens (via the
* already-structural `extractEntities`), and token count. No
* natural-language word, synonym, or stopword list appears anywhere. The
* classifier behaves identically across scripts and locales. The
* summary-search router (t_7b96f242) obeys the same invariant: it routes on
* structured field tokens (`source:`, `kind:`/`type:`) and a caller-supplied
* artifact-kind vocabulary (the schema pack's page types), never a word list.
*
* Query-side temporal intent (t_58fc4720) is resolved here too, against
* an INJECTED clock - see `temporal-intent.ts`, which holds the same
* language-agnostic invariant.
*
* The module is pure and deterministic: same query string in, same plan
* out, with no I/O and no clock/random source of its own.
*/
import { WIKILINK_DETECT_RE } from "../brain/wikilink.ts";
import { extractEntities } from "./entities.ts";
import {
detectTemporalIntent,
stripTemporalDirectives,
type TemporalIntent,
} from "./temporal-intent.ts";
import type { QueryIntent, QueryPlan, QuerySurface, WeightProfile } from "./types.ts";
/** No-effect profile: every layer keeps its configured weight. */
export const NEUTRAL_PROFILE: WeightProfile = Object.freeze({
keywordMul: 1,
semanticMul: 1,
entityMul: 1,
recencyMul: 1,
});
/**
* Fixed structural-feature -> profile table. Every multiplier stays
* within [0.7, 1.4], so a (mis)classification can only re-weight an
* already-relevant set, never float an unrelated document.
*/
const PROFILES: Record<QueryIntent, WeightProfile> = Object.freeze({
neutral: NEUTRAL_PROFILE,
// Literal lookup: trust the keyword/FTS layer, discount fuzzy semantic.
exact: Object.freeze({
keywordMul: 1.3,
semanticMul: 0.7,
entityMul: 1,
recencyMul: 1,
}),
// Proper-noun lookup: amplify the entity layer, nudge keyword.
entity: Object.freeze({
keywordMul: 1.15,
semanticMul: 0.9,
entityMul: 1.4,
recencyMul: 1,
}),
// Open-ended exploration: lean on semantic similarity and recency.
broad: Object.freeze({
keywordMul: 0.9,
semanticMul: 1.2,
entityMul: 1,
recencyMul: 1.1,
}),
});
const QUOTED_PHRASE_RE = /"[^"\n]{2,}"/u;
const WILDCARD_RE = /\*/u;
/**
* Structured field-token grammar for surface routing: a `<field>:<value>`
* token anchored at a word boundary, value running to the next whitespace.
* Field names are a fixed structural vocabulary (never natural-language
* words); the value is compared against the caller-supplied artifact-kind
* vocabulary. `source:` targets a source and is vocabulary-independent.
*/
const KIND_TOKEN_RE = /(?:^|\s)(?:kind|type):(\S+)/u;
const SOURCE_TOKEN_RE = /(?:^|\s)source:\S/u;
/**
* Route a query to a retrieval surface from structural signals only
* (t_7b96f242). Returns `summary` when the query is source-targeted
* (`source:<x>`) or names an artifact kind from `vocabulary`
* (`kind:<v>` / `type:<v>` with `<v>` in the vocabulary); otherwise
* `default`. Pure and deterministic; the vocabulary is a config-derived
* token set (the schema pack's page types), never a word list. An empty
* vocabulary still honours the vocabulary-independent source signal.
*/
export function routeSummarySurface(query: string, vocabulary: ReadonlySet<string>): QuerySurface {
const normalized = query.toLowerCase();
if (SOURCE_TOKEN_RE.test(normalized)) return "summary";
if (vocabulary.size > 0) {
const kindMatch = KIND_TOKEN_RE.exec(normalized);
if (kindMatch && vocabulary.has(kindMatch[1]!)) return "summary";
}
return "default";
}
/** Lowercase + trim + collapse internal whitespace. No word lists. */
function normalize(query: string): string {
return query.trim().replace(/\s+/gu, " ").toLowerCase();
}
/** Deterministic FNV-1a 32-bit hash, hex-encoded. No crypto/I/O. */
function fnv1a(input: string): string {
let h = 0x811c9dc5;
for (let i = 0; i < input.length; i++) {
h ^= input.charCodeAt(i);
// 32-bit FNV prime multiply via shifts, kept in uint32.
h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
}
return h.toString(16).padStart(8, "0");
}
/** Token count over normalized whitespace. Empty string -> 0. */
function tokenCount(normalized: string): number {
if (normalized === "") return 0;
return normalized.split(" ").length;
}
function classify(query: string, normalized: string): QueryIntent {
if (normalized === "") return "neutral";
// Rule 1: a literal phrase or prefix wildcard means the caller wants
// an exact textual hit - favour the keyword layer.
if (QUOTED_PHRASE_RE.test(query) || WILDCARD_RE.test(query)) return "exact";
const entities = extractEntities(query);
const tokens = tokenCount(normalized);
const entityShare = tokens === 0 ? 0 : entities.length / tokens;
// Rule 2: explicit wikilinks or a query dominated by entity-like
// tokens is a proper-noun lookup.
if (WIKILINK_DETECT_RE.test(query) || entityShare >= 0.5) return "entity";
// Rule 3: a long query with few entities reads as open-ended.
if (tokens >= 6 && entityShare < 0.2) return "broad";
return "neutral";
}
/** Hash field for the resolved temporal window; absent leaves the hash intact. */
const TEMPORAL_HASH_FIELD = "t";
/**
* Analyse a query into a deterministic plan. `expandedTerms` is empty
* here; synonym expansion (a later layer) fills it before the hash is
* meaningful for caching. The hash folds in the normalized query, the
* intent, any expanded terms, and the resolved temporal window -
* everything that changes results.
*
* `nowMs` is the clock temporal-intent detection resolves against.
* Omitting it disables detection entirely, exactly as omitting
* `surfaceVocabulary` pins the surface to `default`, so an existing call
* site keeps a byte-identical plan.
*
* `temporalIntentOverride` is the window a caller ALREADY resolved from
* the ORIGINAL query text. It exists because `search()` restructures the
* keyword text before it plans - expansion rewrites the query into bare
* lexical include terms, which destroys the `field:value` grammar - so
* detection there must read the untouched query and hand the result in.
* Detection and stripping then operate on the same text, which is the
* invariant a plan built from restructured text silently broke. Omitted
* (every other call site) means detect from `query` against `nowMs`.
*/
export function buildQueryPlan(
query: string,
expandedTerms: ReadonlyArray<string> = [],
intentOverride?: QueryIntent | null,
surfaceVocabulary?: ReadonlySet<string>,
nowMs?: number,
temporalIntentOverride?: TemporalIntent | null,
): QueryPlan {
const temporalIntent =
temporalIntentOverride !== undefined
? temporalIntentOverride
: nowMs === undefined
? null
: detectTemporalIntent(query, nowMs);
// A `since:` / `until:` directive states the window; it is not content.
// Everything downstream of detection analyses the residual query, so a
// directive never reaches the classifier or the keyword lane as a term.
const analysed = temporalIntent === null ? query : stripTemporalDirectives(query);
const normalized = normalize(analysed);
const intent = intentOverride ?? classify(analysed, normalized);
const terms = Object.freeze([...expandedTerms]);
// Surface routing is advisory and does NOT enter the hash: it re-weights
// nothing, so a query's cache identity and ranking stay byte-identical
// regardless of surface. Omitting the vocabulary keeps the pure default
// provably inert (always `default`), so existing call sites are unchanged.
const planHash = fnv1a(
`${normalized}|${intent}|${terms.join(",")}` +
(temporalIntent === null ? "" : `|${TEMPORAL_HASH_FIELD}:${temporalIntent.signature}`),
);
const surface =
surfaceVocabulary === undefined ? "default" : routeSummarySurface(analysed, surfaceVocabulary);
return Object.freeze({
intent,
weightProfile: PROFILES[intent],
expandedTerms: terms,
planHash,
surface,
...(temporalIntent !== null ? { temporalIntent } : {}),
});
}