Skip to content

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
9.6 KB
Raw Blame
/**
 * Persistent query-cache helpers (v0.20.0).
 *
 * The cache stores a serialized {@link SearchOutcome} keyed by a hash of
 * the result-affecting request (the search options + the query plan hash
 * + a fingerprint of the resolved config) and tagged with the corpus
 * generation it was computed under. A row is served only when its
 * generation matches the current one and it is within the TTL; otherwise
 * the caller recomputes. This module owns the key construction and the
 * (de)serialization; the SQLite I/O lives on `Store`.
 *
 * The expansion terms are deliberately NOT part of the key: they are a
 * deterministic function of (query, index content), and any index
 * content change bumps the corpus generation, so the generation gate
 * already covers them.
 */

import { normalizeScopeFilter } from "../scope-key.ts";
import { resolvedTransportReach } from "../graph/transport-reach.ts";
import { DISCLOSURE_MODE } from "./disclosure-mode.ts";
import { FTS_MATCH_MODE } from "./fts-match-mode.ts";
import { attributeNarrowingEntries } from "./property-pushdown.ts";
import type { Store } from "./store.ts";
import type { SearchOptions, SearchOutcome } from "./types.ts";

/** Deterministic FNV-1a 32-bit hash, hex-encoded. */
function fnv1a(input: string): string {
  let h = 0x811c9dc5;
  for (let i = 0; i < input.length; i++) {
    h ^= input.charCodeAt(i);
    h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
  }
  return h.toString(16).padStart(8, "0");
}

/** Canonicalise a property filter map: sort values per key, then keys. */
function canonicalProperties(
  props: ReadonlyMap<string, ReadonlyArray<string>> | undefined,
): Array<[string, string[]]> | null {
  if (!props || props.size === 0) return null;
  return [...props.entries()]
    .map(([k, v]) => [k, [...v].toSorted()] as [string, string[]])
    .toSorted((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
}

/**
 * Canonicalise the UNPROMOTED attribute-narrowing half of a property
 * filter map (recall-quality): keys in the NFC spelling the lanes narrow
 * with, values sorted, keys sorted. Null when no key narrows, so the
 * default key - and every row cached before the narrowing existed - stays
 * byte-identical.
 *
 * The fold exists because the narrowing changes the candidate pool, and
 * the pool width is what the retrieval trail counts: a row written by a
 * pre-narrowing binary must not be served under a key this binary computes
 * with narrowing on. The raw `properties` fold above cannot provide that
 * partition - it names the same map on both sides of the upgrade.
 */
export function canonicalAttributeNarrowing(
  props: ReadonlyMap<string, ReadonlyArray<string>> | undefined,
): Array<{ key: string; values: string[] }> | null {
  const entries = attributeNarrowingEntries(props);
  if (entries === null) return null;
  return entries
    .map((e) => ({ key: e.key, values: [...e.values].toSorted() }))
    .toSorted((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
}

function canonicalStructuredQuery(opts: SearchOptions): unknown {
  const structured = opts.structuredQuery;
  if (!structured) return null;
  return {
    intent: structured.intent,
    lexInclude: [...structured.lex.include],
    lexExclude: [...structured.lex.exclude],
    vec: [...structured.vec],
    hyde: [...structured.hyde],
  };
}

/**
 * Canonical composite scope filter for the cache key. Undefined (dropped
 * from the JSON) when no axis is requested, so a scopeless query keys
 * byte-identically to a pre-scope cached row. Normalized so equivalent
 * spellings share one entry.
 */
function canonicalScope(opts: SearchOptions): unknown {
  if (opts.scope === undefined) return undefined;
  const scope = normalizeScopeFilter(opts.scope);
  if (scope.session === null && scope.project === null) return undefined;
  return { session: scope.session, project: scope.project };
}

function canonicalSessionFocus(opts: SearchOptions): unknown {
  const focus = opts.sessionFocus;
  if (focus === undefined) return "persisted";
  if (focus === null) return null;
  return {
    query: focus.query,
    pathPrefix: focus.pathPrefix,
    expiresAt: focus.expiresAt,
  };
}

/**
 * Build a stable cache key from the result-affecting request. Every
 * option that can change the result set is folded in, in a canonical
 * (order-independent) form, alongside the plan hash and a fingerprint of
 * the resolved config.
 */
export function buildCacheKey(
  opts: SearchOptions,
  planHash: string,
  configFingerprint: string,
): string {
  const canonical = JSON.stringify({
    q: (opts.query ?? "").trim(),
    limit: opts.limit ?? null,
    semantic: opts.semantic ?? null,
    keywordOnly: opts.keywordOnly ?? false,
    pathPrefix: opts.pathPrefix ?? null,
    keywordWeight: opts.keywordWeight ?? null,
    semanticWeight: opts.semanticWeight ?? null,
    mmrLambda: opts.mmrLambda ?? null,
    maxHops: opts.maxHops ?? null,
    evidencePack: opts.evidencePack === true,
    properties: canonicalProperties(opts.properties),
    // The unpromoted attribute-narrowing fold partitions pre-narrowing
    // cache rows from post-narrowing ones; absent (no unpromoted key)
    // keeps the key byte-identical. See `canonicalAttributeNarrowing`.
    attributeNarrowing: canonicalAttributeNarrowing(opts.properties) ?? undefined,
    visibility: opts.visibility ? [...opts.visibility].toSorted() : null,
    agentScope: opts.agentScope ?? null,
    // The transport reach partitions the cache, and unconditionally.
    // It decides which pages are in the pool at all - a `local` outcome
    // holds rows the reserved-token rule withholds from `remote` - so a
    // key that omitted it would let one row serve both, in whichever
    // direction the operator's own CLI happened to warm it first. Folded
    // in RESOLVED rather than raw, so an absent reach and an explicit
    // `remote` key identically; and folded in unconditionally, because
    // every row written before this boundary existed was computed
    // without it and must not be served under it.
    transportReach: resolvedTransportReach(opts.transportReach),
    scope: canonicalScope(opts),
    // Relational arm (t_09b7ccea) changes the result set, so a per-query
    // override partitions the cache. Dropped when absent, so a query that
    // does not touch the flag keys byte-identically to a pre-arm row.
    relationalArm: opts.relationalArm ?? undefined,
    // Disclosure depth (D3) partitions the cache: a `cards` outcome and a
    // `full` outcome must not collide. Folded in only for `cards`, so the
    // default `full` key (and every pre-D3 cached row) stays byte-identical.
    disclosure: opts.disclosure === DISCLOSURE_MODE.cards ? DISCLOSURE_MODE.cards : undefined,
    // Match mode partitions the cache: an `any` (OR) outcome holds rows
    // the strict `all` default drops. Folded in only for `any`, so the
    // default key (and every row cached before the mode existed) stays
    // byte-identical.
    matchMode: opts.matchMode === FTS_MATCH_MODE.any ? FTS_MATCH_MODE.any : undefined,
    // Kind (recall-quality, C4) partitions the cache the same way: a
    // `page` outcome holds rows a kindless query would not. Folded in only
    // when set, so the default key stays byte-identical. The pushed
    // promoted properties need no separate input - they are part of
    // `properties`, already canonicalized above.
    kind: opts.kind ?? undefined,
    // The source filter (design D5) partitions the cache the same way; absent keeps the key.
    source: opts.source ?? undefined,
    // Per-source-session pool cap override (t_bb6ce095) partitions the
    // cache: an explicit `0` forces the cap off for this query, which
    // differs from the config default. Dropped when absent, so a query
    // that does not touch the knob keys byte-identically to a pre-knob
    // row.
    poolMaxPerSession: opts.poolMaxPerSession ?? undefined,
    structuredQuery: canonicalStructuredQuery(opts),
    sessionFocus: canonicalSessionFocus(opts),
    plan: planHash,
    cfg: configFingerprint,
  });
  return fnv1a(canonical);
}

/**
 * Return the cached outcome for `key` when it is present, computed under
 * the current `generation`, and within `ttlMs` of `nowMs`. Otherwise
 * null (the caller recomputes). A corrupt payload also returns null.
 */
export function getCachedOutcome(
  store: Store,
  key: string,
  generation: string,
  ttlMs: number,
  nowMs: number,
): SearchOutcome | null {
  const row = store.queryCacheGet(key);
  if (!row) return null;
  if (row.generation !== generation) return null;
  if (nowMs - row.createdAt > ttlMs) return null;
  try {
    const parsed = JSON.parse(row.payload) as SearchOutcome;
    // A row written before `idfWeightedCoverage` existed carries no match
    // quality, and a hit that served one would hand every downstream
    // confidence threshold `undefined` to compare against - the silent
    // fallback those thresholds are being repaired to stop making. Such a
    // row is a miss, so the outcome is recomputed with the number in it.
    if (typeof parsed.idfWeightedCoverage !== "number") return null;
    // Match the fresh-compute path's immutability: freeze the results
    // array and each result so a hit is indistinguishable from a miss.
    for (const r of parsed.results) Object.freeze(r);
    Object.freeze(parsed.results);
    Object.freeze(parsed.warnings);
    return Object.freeze(parsed);
  } catch {
    return null;
  }
}

/** Serialize and store an outcome under the current generation. */
export function putCachedOutcome(
  store: Store,
  key: string,
  generation: string,
  outcome: SearchOutcome,
  nowMs: number,
): void {
  store.queryCachePut(key, generation, JSON.stringify(outcome), nowMs);
}