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
import { appendContinuityRecord, listContinuityRecords } from "./continuity/store.ts";
import { CONTINUITY_CHANNEL_KEY, type ContinuityRecord } from "./continuity/types.ts";
import { jaccard, tokenise } from "./similarity.ts";
import type { DefaultRelationType } from "../graph/relation-vocab.ts";
import type { BrainSearchResult } from "../search/search-result.ts";
/**
* The transport a recall record was delivered over (C1, t_e5f447c1).
*
* `host` cannot answer this question and never could: it is an open,
* caller-supplied string capped at 200 characters, and its meaning is
* already overloaded between runtime identity ("claude-code") and
* transport (the `"mcp"` / `"cli"` defaults). One column answering both
* questions answers neither, which is why a hook that was never
* installed and a hook that ran and stayed quiet produce identical
* evidence today: none.
*
* Three members because three transports exist in this repository. There
* is no Hermes delivery path here - `hermes` appears as an agent name, an
* install document and a `telemetry_host` string in tests, which makes it
* a HOST - so no `hermes` member is minted. A channel nothing can write
* would hand the doctor a column that is silent by construction, which is
* the exact ambiguity this vocabulary removes.
*
* Anything finer than a transport belongs in `mode` or `metadata`.
*/
export const RECALL_CHANNEL = Object.freeze({
/** An MCP tool call on the server surface. */
mcp: "mcp",
/** An `o2b` verb run from a terminal or a script. */
cli: "cli",
/** A runtime hook that injects recall into a prompt. */
hook: "hook",
} as const);
/** Closed union over {@link RECALL_CHANNEL}. */
export type RecallChannel = (typeof RECALL_CHANNEL)[keyof typeof RECALL_CHANNEL];
/** Membership list, in the order the surfaces render their enums. */
export const RECALL_CHANNELS: ReadonlyArray<RecallChannel> = Object.freeze([
RECALL_CHANNEL.mcp,
RECALL_CHANNEL.cli,
RECALL_CHANNEL.hook,
]);
/** Narrow a string read back off disk or across a tool boundary. */
export function isRecallChannel(value: unknown): value is RecallChannel {
return typeof value === "string" && (RECALL_CHANNELS as ReadonlyArray<string>).includes(value);
}
/**
* The retrieval shape a record describes.
*
* Converted from a bare union plus a hand-rolled equality chain, which is
* how `query` came to be a mode the server records and three separate
* copies of the list did not know about - one of them a tool-schema enum
* that rejected it at the boundary. The members list below is now the
* only place the words are written down.
*/
export const RECALL_TELEMETRY_MODE = Object.freeze({
search: "search",
contextPack: "context_pack",
preCompress: "pre_compress",
query: "query",
} as const);
/** Closed union over {@link RECALL_TELEMETRY_MODE}. */
export type RecallTelemetryMode =
(typeof RECALL_TELEMETRY_MODE)[keyof typeof RECALL_TELEMETRY_MODE];
/** Membership list; every surface renders its enum from this array. */
export const RECALL_TELEMETRY_MODES: ReadonlyArray<RecallTelemetryMode> = Object.freeze([
RECALL_TELEMETRY_MODE.search,
RECALL_TELEMETRY_MODE.contextPack,
RECALL_TELEMETRY_MODE.preCompress,
RECALL_TELEMETRY_MODE.query,
]);
/** How a recall attempt ended. The injecting hook maps onto these too. */
export const RECALL_TELEMETRY_STATUS = Object.freeze({
/** Something was returned and delivered. */
ok: "ok",
/** The attempt ran to completion and returned nothing. */
empty: "empty",
/** The attempt failed. */
error: "error",
/** The attempt exceeded its time budget. */
timeout: "timeout",
} as const);
/** Closed union over {@link RECALL_TELEMETRY_STATUS}. */
export type RecallTelemetryStatus =
(typeof RECALL_TELEMETRY_STATUS)[keyof typeof RECALL_TELEMETRY_STATUS];
/** Membership list; every surface renders its enum from this array. */
export const RECALL_TELEMETRY_STATUSES: ReadonlyArray<RecallTelemetryStatus> = Object.freeze([
RECALL_TELEMETRY_STATUS.ok,
RECALL_TELEMETRY_STATUS.empty,
RECALL_TELEMETRY_STATUS.error,
RECALL_TELEMETRY_STATUS.timeout,
]);
export interface RecallTelemetryArtifactInput {
readonly id: string;
readonly path?: string;
readonly score?: number;
}
/**
* Recall-quality signals (what-the-index-already-knew, task G).
*
* SHADOW-ONLY INVARIANT, the same one `retrieval-plan.ts` states: this
* lane READS an already-ranked, already-frozen result window and returns
* numbers. It exposes no handle that could mutate ranking, weight
* policy, or the returned rows, and it is invoked only from inside the
* gated telemetry thunk - with the gate off, `emitGatedTelemetry` never
* calls the builder, so nothing here executes on the default path.
*
* Every signal is a value the retrieval pipeline ALREADY computed and
* then discarded before any surface could see it:
*
* - alignment - the fused `score` and the per-lane `keywordScore` /
* `semanticScore` the ranker produced;
* - trust - the read-time {@link BrainSearchResult.trust} metadata,
* attached only when the caller set `trust`, so `assessed` doubles
* as the record of whether the caller asked at all;
* - contradiction - the typed `contradicts` relation edges the
* pipeline already surfaces on the row, counted with no dependency
* on the trust opt-in;
* - diversity - the same deterministic token-set Jaccard measure the
* MMR reranker applies pair-by-pair, aggregated over the surfaced
* window. It goes through the shared brain-layer tokeniser
* ({@link ./similarity.ts}) rather than the reranker's private copy,
* so this lane adds no second tokeniser; that tokeniser drops
* single-character tokens, which makes the number comparable across
* queries but not equal to a given MMR pair score. No embedding
* round trip, no word list, no clock.
*
* ONE record per query. The continuity log has no retention policy, so
* per-result detail is refused outright: everything here is a pool-level
* count or mean, and the only quadratic walk is bounded by
* {@link RECALL_SIGNALS_DIVERSITY_MAX_ROWS}.
*
* Epistemic provenance is deliberately NOT derived here. Unlike the four
* above it is not a value the retrieval path already holds: no
* frontmatter is carried on the result row and none is stored on the
* index, so deriving it would add one file read and one frontmatter
* parse per surfaced document to a live query. The record already names
* every surfaced artifact by path, so an analysis pass over the log
* derives the same status against the vault at zero recall-time cost.
*
* Two further signals asked for by the original task are refused rather
* than invented; the reasons are recorded in
* `docs/brainstorm/what-the-index-already-knew/design.md` under "Out of
* scope", and a census test asserts their names appear nowhere in `src/`.
*/
/** Decimal places every derived signal is rounded to before recording. */
const SIGNAL_DECIMALS = 4;
/**
* Upper bound on the rows the pairwise diversity walk compares. The walk
* is quadratic, so an unbounded `limit` would make a gated query pay
* `limit^2` token-set comparisons; the top rows are the ones an operator
* reads, so the walk stops there and `diversity.compared` records the
* bound that was actually applied.
*/
export const RECALL_SIGNALS_DIVERSITY_MAX_ROWS = 10;
/** The typed edge that marks a surfaced row as declaring a contradiction. */
const CONTRADICTS_RELATION: DefaultRelationType = "contradicts";
export interface RecallAlignmentSignal {
/** Fused score of the top-ranked surfaced row. */
readonly top: number;
/** Mean fused score across the surfaced window. */
readonly mean: number;
/**
* Fused-score gap between rank 1 and rank 2 as returned. Absent - not
* zero - for a single-row window, where there is no second row to
* measure against. May be negative when a rerank reordered the window.
*/
readonly margin?: number;
/** Summed keyword-lane contribution across the surfaced window. */
readonly keyword_sum: number;
/** Summed semantic-lane contribution across the surfaced window. */
readonly semantic_sum: number;
}
export interface RecallTrustSignal {
/**
* Rows carrying read-time trust metadata. Zero means the caller did
* not opt into `trust`, so the counts below carry no information -
* they are not a clean bill of health.
*/
readonly assessed: number;
readonly superseded: number;
readonly conflict: number;
/** Oldest assessed row in whole days. Absent when `assessed` is 0. */
readonly max_age_days?: number;
}
export interface RecallContradictionSignal {
/** Surfaced rows declaring at least one `contradicts` edge. */
readonly rows: number;
/** Total `contradicts` edges across the surfaced window. */
readonly edges: number;
}
export interface RecallDiversitySignal {
/** Rows the pairwise walk actually compared (the applied bound). */
readonly compared: number;
/** Pairs compared: `compared * (compared - 1) / 2`. */
readonly pairs: number;
/** Mean pairwise token-set overlap. Absent when `pairs` is 0. */
readonly mean_similarity?: number;
/** Largest pairwise token-set overlap. Absent when `pairs` is 0. */
readonly max_similarity?: number;
}
export interface RecallQualitySignals {
/** Rows in the surfaced window the signals were derived from. */
readonly rows: number;
readonly alignment: RecallAlignmentSignal;
readonly trust: RecallTrustSignal;
readonly contradiction: RecallContradictionSignal;
readonly diversity: RecallDiversitySignal;
}
/**
* Recorded in place of the signals when the surface returned something
* the derivation cannot read. A check that cannot run says so rather
* than recording zeros that would read as a measured result.
*/
export interface RecallSignalsUnmeasured {
readonly unmeasured: "disclosure_cards";
}
/**
* Progressive-disclosure `cards` mode returns projected cards and an
* EMPTY `results` array, so none of the per-row values these signals are
* derived from exist on that path.
*/
export const RECALL_SIGNALS_UNMEASURED_CARDS: RecallSignalsUnmeasured = Object.freeze({
unmeasured: "disclosure_cards",
});
function roundSignal(value: number): number {
const factor = 10 ** SIGNAL_DECIMALS;
return Math.round(value * factor) / factor;
}
/**
* Derive the per-query recall signals from an already-ranked window.
*
* Returns `null` for an empty window: there is no pool to measure, and
* the record's `result_count: 0` already states that. Pure - no I/O, no
* clock - and non-mutating: the input array and its rows are read only.
*/
export function deriveRecallSignals(
rows: ReadonlyArray<BrainSearchResult>,
): RecallQualitySignals | null {
if (rows.length === 0) return null;
let scoreSum = 0;
let keywordSum = 0;
let semanticSum = 0;
let assessed = 0;
let superseded = 0;
let conflict = 0;
let maxAgeDays = 0;
let contradictionRows = 0;
let contradictionEdges = 0;
for (const row of rows) {
scoreSum += row.score;
keywordSum += row.keywordScore;
semanticSum += row.semanticScore;
if (row.trust !== undefined) {
assessed += 1;
if (row.trust.superseded) superseded += 1;
if (row.trust.conflict) conflict += 1;
if (row.trust.age_days > maxAgeDays) maxAgeDays = row.trust.age_days;
}
const edges = (row.relations ?? []).filter(
(relation) => relation.relation === CONTRADICTS_RELATION,
).length;
if (edges > 0) {
contradictionRows += 1;
contradictionEdges += edges;
}
}
const top = rows[0]!;
const second = rows[1];
return Object.freeze({
rows: rows.length,
alignment: Object.freeze({
top: roundSignal(top.score),
mean: roundSignal(scoreSum / rows.length),
...(second !== undefined ? { margin: roundSignal(top.score - second.score) } : {}),
keyword_sum: roundSignal(keywordSum),
semantic_sum: roundSignal(semanticSum),
}),
trust: Object.freeze({
assessed,
superseded,
conflict,
...(assessed > 0 ? { max_age_days: maxAgeDays } : {}),
}),
contradiction: Object.freeze({ rows: contradictionRows, edges: contradictionEdges }),
diversity: derivePoolDiversity(rows),
});
}
/**
* Pool-level redundancy: the mean and maximum pairwise token-set Jaccard
* over the top {@link RECALL_SIGNALS_DIVERSITY_MAX_ROWS} rows, using the
* shared brain-layer tokeniser. A window with fewer than two rows has no
* pair, so both means are absent rather than reported as a diversity of
* zero, which would read as "maximally diverse".
*/
function derivePoolDiversity(rows: ReadonlyArray<BrainSearchResult>): RecallDiversitySignal {
const compared = Math.min(rows.length, RECALL_SIGNALS_DIVERSITY_MAX_ROWS);
if (compared < 2) return Object.freeze({ compared, pairs: 0 });
const tokens = rows.slice(0, compared).map((row) => tokenise(row.content));
let sum = 0;
let max = 0;
let pairs = 0;
for (let i = 0; i < tokens.length; i++) {
for (let j = i + 1; j < tokens.length; j++) {
const similarity = jaccard(tokens[i]!, tokens[j]!);
sum += similarity;
if (similarity > max) max = similarity;
pairs += 1;
}
}
return Object.freeze({
compared,
pairs,
mean_similarity: roundSignal(sum / pairs),
max_similarity: roundSignal(max),
});
}
export interface RecallTelemetryInput {
readonly createdAt?: string;
readonly host: string;
/**
* The transport this record was delivered over. REQUIRED, not
* optional: an optional field lets a call site omit it and produce a
* record that reads as "no channel", which is the ambiguity C1 exists
* to remove. Required makes every emit site fail to compile until it
* names its channel, and that is the enforcement mechanism.
*/
readonly channel: RecallChannel;
readonly sessionId?: string;
readonly turnId?: string;
readonly mode: RecallTelemetryMode;
readonly status: RecallTelemetryStatus;
readonly durationMs: number;
readonly resultCount: number;
readonly topArtifacts?: ReadonlyArray<RecallTelemetryArtifactInput>;
readonly gaps?: ReadonlyArray<string>;
readonly metadata?: Readonly<Record<string, unknown>>;
/**
* Recall-quality signals for this query (task G). Additive and
* optional: a caller that supplies none produces a payload
* byte-identical to the pre-signal one - the key is absent, never
* null - so `CONTINUITY_SCHEMA_VERSION` does not move.
*/
readonly signals?: RecallQualitySignals | RecallSignalsUnmeasured;
}
export interface RecallTelemetryOptions {
readonly host: string;
/** See {@link RecallTelemetryInput.channel}: required for the same reason. */
readonly channel: RecallChannel;
readonly createdAt?: string;
readonly sessionId?: string;
readonly turnId?: string;
readonly metadata?: Readonly<Record<string, unknown>>;
}
/**
* The correlation fields every emit site copies onto its input.
*
* Five sites repeated the same four-line unpack of createdAt / host /
* sessionId / turnId, each with its own spelling of the
* omit-when-undefined idiom - which is how a sixth field (this release's
* `channel`) would have been added to four of them and forgotten in the
* fifth. The omissions are preserved exactly: an absent correlation id
* must not reach the payload as a present key.
*/
export interface RecallTelemetryEnvelope {
readonly createdAt?: string;
readonly host: string;
readonly channel: RecallChannel;
readonly sessionId?: string;
readonly turnId?: string;
}
export function recallTelemetryEnvelope(options: RecallTelemetryOptions): RecallTelemetryEnvelope {
return {
...(options.createdAt !== undefined ? { createdAt: options.createdAt } : {}),
host: options.host,
channel: options.channel,
...(options.sessionId !== undefined ? { sessionId: options.sessionId } : {}),
...(options.turnId !== undefined ? { turnId: options.turnId } : {}),
};
}
export interface RecallTelemetryFilter {
readonly mode?: RecallTelemetryMode;
readonly status?: RecallTelemetryStatus;
readonly host?: string;
readonly channel?: RecallChannel;
readonly since?: string;
readonly until?: string;
readonly limit?: number;
}
export interface RecallTelemetrySummary {
readonly total: number;
readonly by_mode: Partial<Record<RecallTelemetryMode, number>>;
readonly by_status: Partial<Record<RecallTelemetryStatus, number>>;
/**
* Deliveries per transport. A channel with no record at all is ABSENT
* rather than zero, the same way `by_mode` reports only what arrived:
* whether a silent channel should have delivered is a question about
* its install state, which only the doctor check holds.
*/
readonly by_channel: Partial<Record<RecallChannel, number>>;
readonly total_results: number;
readonly empty_runs: number;
readonly gap_counts: Record<string, number>;
}
export function emitRecallTelemetry(
vault: string | null,
input: RecallTelemetryInput,
): ContinuityRecord {
const createdAt = input.createdAt ?? new Date().toISOString();
const topArtifacts = [...(input.topArtifacts ?? [])];
const gaps = [...new Set((input.gaps ?? []).map((gap) => gap.trim()).filter(Boolean))];
return appendContinuityRecord(vault, {
kind: "recall_telemetry",
createdAt,
sourceRefs: topArtifacts.map((artifact) => ({
id: artifact.id,
...(artifact.path ? { path: artifact.path } : {}),
})),
payload: {
host: input.host,
[CONTINUITY_CHANNEL_KEY]: input.channel,
...(input.sessionId ? { session_id: input.sessionId } : {}),
...(input.turnId ? { turn_id: input.turnId } : {}),
mode: input.mode,
status: input.status,
duration_ms: Math.max(0, Math.floor(input.durationMs)),
result_count: Math.max(0, Math.floor(input.resultCount)),
top_artifacts: topArtifacts.map((artifact) => ({
id: artifact.id,
...(artifact.path ? { path: artifact.path } : {}),
...(artifact.score !== undefined ? { score: artifact.score } : {}),
})),
gaps,
...(input.metadata ? { metadata: input.metadata } : {}),
...(input.signals ? { signals: input.signals } : {}),
},
});
}
export function listRecallTelemetry(
vault: string | null,
filter: RecallTelemetryFilter = {},
): ReadonlyArray<ContinuityRecord> {
let records = listContinuityRecords(vault, {
kind: "recall_telemetry",
...(filter.since !== undefined ? { since: filter.since } : {}),
...(filter.until !== undefined ? { until: filter.until } : {}),
}).filter((record) => matchesTelemetryFilter(record, filter));
records = records.toReversed();
if (filter.limit !== undefined) records = records.slice(0, Math.max(0, Math.floor(filter.limit)));
return Object.freeze(records);
}
export function summarizeRecallTelemetry(
vault: string | null,
filter: RecallTelemetryFilter = {},
): RecallTelemetrySummary {
return summarizeRecallTelemetryRecords(listRecallTelemetry(vault, filter));
}
/**
* The summary fold over an already-listed set of records. Split from
* {@link summarizeRecallTelemetry} so a reader that must apply its own
* record boundary first (the MCP tool applies the caller's reach and
* ownership view, dropping withheld records BEFORE the counts) folds the
* same numbers over the same shape without a second disk read.
*/
export function summarizeRecallTelemetryRecords(
records: ReadonlyArray<ContinuityRecord>,
): RecallTelemetrySummary {
const byMode: Partial<Record<RecallTelemetryMode, number>> = {};
const byStatus: Partial<Record<RecallTelemetryStatus, number>> = {};
const byChannel: Partial<Record<RecallChannel, number>> = {};
const gapCounts: Record<string, number> = {};
let totalResults = 0;
let emptyRuns = 0;
for (const record of records) {
const mode = record.payload["mode"];
if (isRecallTelemetryMode(mode)) byMode[mode] = (byMode[mode] ?? 0) + 1;
const status = record.payload["status"];
if (isRecallTelemetryStatus(status)) {
byStatus[status] = (byStatus[status] ?? 0) + 1;
if (status === "empty") emptyRuns += 1;
}
const channel = record.payload[CONTINUITY_CHANNEL_KEY];
if (isRecallChannel(channel)) byChannel[channel] = (byChannel[channel] ?? 0) + 1;
const resultCount = record.payload["result_count"];
if (typeof resultCount === "number") totalResults += resultCount;
const gaps = record.payload["gaps"];
if (Array.isArray(gaps)) {
for (const gap of gaps) {
if (typeof gap !== "string" || gap.length === 0) continue;
gapCounts[gap] = (gapCounts[gap] ?? 0) + 1;
}
}
}
return Object.freeze({
total: records.length,
by_mode: Object.freeze(byMode),
by_status: Object.freeze(byStatus),
by_channel: Object.freeze(byChannel),
total_results: totalResults,
empty_runs: emptyRuns,
gap_counts: Object.freeze(gapCounts),
});
}
/** Narrow a mode read back off disk or across a tool boundary. */
export function isRecallTelemetryMode(value: unknown): value is RecallTelemetryMode {
return (
typeof value === "string" && (RECALL_TELEMETRY_MODES as ReadonlyArray<string>).includes(value)
);
}
/** Narrow a status read back off disk or across a tool boundary. */
export function isRecallTelemetryStatus(value: unknown): value is RecallTelemetryStatus {
return (
typeof value === "string" &&
(RECALL_TELEMETRY_STATUSES as ReadonlyArray<string>).includes(value)
);
}
function matchesTelemetryFilter(record: ContinuityRecord, filter: RecallTelemetryFilter): boolean {
const payload = record.payload;
if (filter.mode !== undefined && payload["mode"] !== filter.mode) return false;
if (filter.status !== undefined && payload["status"] !== filter.status) return false;
if (filter.host !== undefined && payload["host"] !== filter.host) return false;
if (filter.channel !== undefined && payload[CONTINUITY_CHANNEL_KEY] !== filter.channel) {
return false;
}
return true;
}