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
/**
* 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);
}