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
5.4 KB
Raw Blame
/**
 * The embedding ABI an index was written under versus the one this build
 * would produce (context-integrity-gates, Unit E): reading the recorded
 * tokens, deriving the runtime ones, and naming the drift between them.
 *
 * Both sides of the comparison are built here so they can never cover
 * different fields.
 */

import type { StampMismatch, StampTokens } from "../../integrity/stamp.ts";
import { formatStampMismatch } from "../../integrity/stamp.ts";

import type { ResolvedSearchConfig } from "../types.ts";
import {
  EMBEDDING_DIMENSION_STATE_KEY,
  EMBEDDING_MODEL_STATE_KEY,
  EMBEDDING_VEC_VERSION_STATE_KEY,
  peekReadonlyIndex,
  type IndexPeek,
} from "./state.ts";

/**
 * The single remediation for embedding-ABI drift, named once so the
 * store's refusal, the status warning and the `search check`
 * recommendation cannot grow three spellings of the same instruction.
 */
export const EMBEDDING_ABI_FIX_COMMAND = "o2b search reindex --embeddings";

/**
 * The remediation for a drift confined to the sqlite-vec version
 * (nothing-writes-silently, unit G).
 *
 * That token is an ABI marker, not a property of any vector: two peers
 * on different sqlite-vec builds each read the other's store as
 * drifted, which is why the gate defaults to `warn`. Sending them to
 * the full reindex charges provider prices to correct a version string
 * no stored vector depends on, so this drift - and only this one -
 * names the restamp verb instead.
 */
export const EMBEDDING_VEC_VERSION_FIX_COMMAND = "o2b search restamp";

/**
 * Which remediation a given drift earns. The full rebuild, unless every
 * drifted field is the sqlite-vec version, in which case restamping is
 * the whole repair. Shared by the refusal, the warning and the
 * recommendation so no surface can name a different command for the
 * same drift.
 */
export function embeddingAbiFixCommand(mismatches: ReadonlyArray<StampMismatch>): string {
  const vecVersionOnly =
    mismatches.length > 0 && mismatches.every((m) => m.field === EMBEDDING_VEC_VERSION_STATE_KEY);
  return vecVersionOnly ? EMBEDDING_VEC_VERSION_FIX_COMMAND : EMBEDDING_ABI_FIX_COMMAND;
}

/** The ABI tokens an index recorded, read through any state accessor. */
export function recordedEmbeddingAbi(state: (key: string) => string | null): StampTokens {
  return {
    [EMBEDDING_MODEL_STATE_KEY]: state(EMBEDDING_MODEL_STATE_KEY),
    [EMBEDDING_DIMENSION_STATE_KEY]: state(EMBEDDING_DIMENSION_STATE_KEY),
    [EMBEDDING_VEC_VERSION_STATE_KEY]: state(EMBEDDING_VEC_VERSION_STATE_KEY),
  };
}

/**
 * The ABI tokens the CURRENT build and configuration would produce. The
 * counterpart of {@link recordedEmbeddingAbi}, kept beside it so the two
 * sides of the comparison can never cover different fields.
 */
export function runtimeEmbeddingAbi(
  config: ResolvedSearchConfig,
  vecVersion: string | null,
): StampTokens {
  return {
    [EMBEDDING_MODEL_STATE_KEY]: config.semantic.model,
    [EMBEDDING_DIMENSION_STATE_KEY]:
      config.semantic.dimension === null ? null : String(config.semantic.dimension),
    [EMBEDDING_VEC_VERSION_STATE_KEY]: vecVersion,
  };
}

/**
 * Embedding-ABI tokens recorded in an index, without opening a `Store`.
 *
 * `indexCheck` needs these and cannot get them from its own probe: it
 * deliberately runs against an IN-MEMORY database and never touches the
 * real index, so a stored-versus-runtime comparison there has no stored
 * side unless one is read explicitly.
 *
 * `null` means the index is absent or unreadable - not that its ABI
 * matches.
 */
export function readEmbeddingAbiSync(dbPath: string): StampTokens | null {
  const peek = peekEmbeddingAbiSync(dbPath);
  return peek.kind === "read" ? peek.value : null;
}

/**
 * {@link readEmbeddingAbiSync} with the three outcomes kept apart, for
 * a caller that must tell an index it could not open from one that is
 * not there - a repair verb refusing by name is exactly that caller.
 */
export function peekEmbeddingAbiSync(dbPath: string): IndexPeek<StampTokens> {
  return peekReadonlyIndex(dbPath, (read) => recordedEmbeddingAbi(read));
}

/**
 * The subset of an ABI comparison the index actually CONTRADICTS: it
 * recorded a token and that token disagrees with this build.
 *
 * A mismatch whose recorded side is `null` is an UNRECORDED field - a
 * store written before that token was stamped. An absent marker cannot
 * tell an old store from a wrong one, so it is reported on the
 * diagnostic surfaces and never drives a refusal or a per-read warning.
 * Both consumers of that distinction (the `fail` verdict's refusal and
 * the query path's warning) route through here rather than restating
 * the predicate, so they cannot drift on what counts as contradicted.
 */
export function contradictedAbiFields(
  mismatches: ReadonlyArray<StampMismatch>,
): ReadonlyArray<StampMismatch> {
  return mismatches.filter((m) => m.expected !== null);
}

/**
 * One operator-facing line for embedding-ABI drift. Shared by the read
 * open's refusal, the status warning and the `search check`
 * recommendation, so the three cannot describe the same condition
 * differently or name different fixes.
 */
export function formatEmbeddingAbiDrift(mismatches: ReadonlyArray<StampMismatch>): string {
  return (
    `embedding ABI drift between the stored index and this build ` +
    `(${mismatches.map(formatStampMismatch).join("; ")}); stored vectors are not ` +
    `comparable to queries embedded now. Run: ${embeddingAbiFixCommand(mismatches)}`
  );
}