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