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
12.1 KB
Raw Blame
/**
 * Curated embedding-model presets (Retrieval & Ranking Quality).
 *
 * A static, shippable catalog of known-good embedding models surfaced when
 * a user registers an OpenAI-compatible provider, plus a recommended
 * multilingual default. Advisory only: the free-form custom `--model`
 * entry stays first-class, and OSB targets arbitrary OpenAI-compatible
 * endpoints, so a preset is guidance (model string + dimension + a note),
 * never a constraint. No server, no network - the list is consulted
 * entirely at registration time.
 *
 * Presets are multilingual-first because OSB is language-agnostic: a
 * multilingual default avoids the dimension/quality mistakes that later
 * force a full re-embed. The `dimension` is the model's native embedding
 * width, useful when setting `embedding_dimension` up front.
 */

import type { EmbeddingProviderName, ResolvedEmbeddingConfig } from "../types.ts";

/**
 * Instruction prefix an e5-family model expects before a search query
 * (memory-write-path-integrity B2). Trailing space is intentional: the model
 * was trained on `"query: <text>"`.
 */
export const E5_QUERY_PREFIX = "query: ";
/** Instruction prefix an e5-family model expects before an indexed passage. */
export const E5_PASSAGE_PREFIX = "passage: ";

/** One curated embedding model the registration flow can recommend. */
export interface EmbeddingModelPreset {
  /** Model string sent to the endpoint (`embedding_model` / profile defaultModel). */
  readonly model: string;
  /** Short human label for CLI listings. */
  readonly label: string;
  /** Native embedding dimension. */
  readonly dimension: number;
  /**
   * The model's DECLARED maximum input length, in the model's own
   * tokenizer's tokens, taken from its published specification (the
   * `max_seq_length` a sentence-transformers checkpoint ships in
   * `sentence_bert_config.json`, or the context length the model card
   * states). Input past it is truncated by the serving stack, and no
   * OpenAI-compatible endpoint reports that it happened - the vector
   * comes back the right width, silently describing a prefix of the
   * passage.
   *
   * Declared here rather than probed: no provider in this system exposes
   * model metadata and the {@link EmbeddingProvider} contract has no
   * window field, so the only alternatives are a network round trip or
   * nothing. A model outside this table therefore has NO declared window,
   * and that is reported as a check that did not run - never as a pass.
   */
  readonly inputWindowTokens: number;
  /** True when the model is trained for cross-lingual retrieval. */
  readonly multilingual: boolean;
  /** One-line guidance shown alongside the model. */
  readonly note: string;
  /**
   * Instruction prefix for a search query (memory-write-path-integrity B2).
   * Present only for models trained with asymmetric instructions (e5). The
   * configured `embedding_prefix_query` overrides it; an explicit empty
   * string disables it.
   */
  readonly queryPrefix?: string;
  /** Instruction prefix for an indexed passage; see {@link queryPrefix}. */
  readonly passagePrefix?: string;
}

/**
 * Curated catalog. Ordered best-general-default first. These are the
 * widely-deployed open multilingual embedding models; a provider exposing
 * them under a different string can still be registered with a custom
 * `--model`.
 */
export const EMBEDDING_MODEL_PRESETS: ReadonlyArray<EmbeddingModelPreset> = Object.freeze([
  {
    model: "intfloat/multilingual-e5-small",
    label: "multilingual-e5-small",
    dimension: 384,
    // sentence_bert_config.json: max_seq_length 512; the model card states
    // inputs longer than 512 tokens are truncated.
    inputWindowTokens: 512,
    multilingual: true,
    note: "Small, fast, strong multilingual default. Prefix inputs with 'query:'/'passage:'.",
    queryPrefix: E5_QUERY_PREFIX,
    passagePrefix: E5_PASSAGE_PREFIX,
  },
  {
    model: "BAAI/bge-m3",
    label: "bge-m3",
    dimension: 1024,
    // Model card: multi-granularity, input lengths up to 8192 tokens.
    inputWindowTokens: 8192,
    multilingual: true,
    note: "High-quality multilingual, 100+ languages. Larger vectors, higher cost.",
  },
  {
    model: "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2",
    label: "paraphrase-multilingual-MiniLM-L12-v2",
    dimension: 384,
    // sentence_bert_config.json: max_seq_length 128. The narrowest window
    // in this table by a wide margin - the underlying encoder accepts
    // more, the shipped sentence-transformers configuration does not.
    inputWindowTokens: 128,
    multilingual: true,
    note: "Compact multilingual paraphrase model; good latency/quality balance.",
  },
  {
    model: "Alibaba-NLP/gte-multilingual-base",
    label: "gte-multilingual-base",
    dimension: 768,
    // Model card: long-context encoder, up to 8192 tokens.
    inputWindowTokens: 8192,
    multilingual: true,
    note: "Balanced multilingual retrieval model with long context.",
  },
  {
    model: "sentence-transformers/LaBSE",
    label: "LaBSE",
    dimension: 768,
    // sentence_bert_config.json: max_seq_length 256 (the sentence-transformers
    // port caps below the 512 the underlying BERT encoder allows).
    inputWindowTokens: 256,
    multilingual: true,
    note: "109-language sentence embeddings; strong cross-lingual alignment.",
  },
  {
    model: "BAAI/bge-small-zh-v1.5",
    label: "bge-small-zh-v1.5",
    dimension: 512,
    // sentence_bert_config.json: max_seq_length 512, matching the BERT
    // encoder's max_position_embeddings. Not the same number as the
    // embedding width above, which is 512 by coincidence.
    inputWindowTokens: 512,
    multilingual: false,
    note: "Chinese-optimized small model; pick when the vault is predominantly zh.",
  },
]);

/** The recommended general-purpose default model string. */
export const RECOMMENDED_EMBEDDING_MODEL: string = EMBEDDING_MODEL_PRESETS[0]!.model;

/** Look up a preset by exact model string (null when not curated). */
export function findEmbeddingPreset(model: string): EmbeddingModelPreset | null {
  return EMBEDDING_MODEL_PRESETS.find((p) => p.model === model) ?? null;
}

/**
 * The input window declared for `model`, or `null` when this table does
 * not declare one.
 *
 * `null` means UNKNOWN, and every caller must treat it as such. This is
 * the same polarity the price resolver (`resolveEmbeddingPrice` in
 * `pricing.ts`) uses for an unlisted model: treating an unknown window as
 * "fits", like treating an unknown price as free, would report a passing
 * check for a condition nobody measured, which is the misleading silence
 * this census exists to remove.
 *
 * Structural lookup by exact model string only. There is no family
 * heuristic here on purpose: `e5` prefixes are a property of the
 * INSTRUCTION FORMAT and are safe to infer, while a window is a number
 * that differs between checkpoints of one family (512 for
 * multilingual-e5-small, 128 for a MiniLM sentence-transformers port),
 * so inferring one from a name would invent the value.
 */
export function declaredInputWindowTokens(model: string | null): number | null {
  if (model === null) return null;
  return findEmbeddingPreset(model)?.inputWindowTokens ?? null;
}

/**
 * The config key an operator declares a model's input window with. Named
 * once so the resolver, its validation and every refusal spell it alike.
 */
export const INPUT_WINDOW_TOKENS_KEY = "embedding_input_window_tokens";

/**
 * The input window that governs the configured backend, or `null` when
 * nobody declared one.
 *
 * Precedence: the operator's `embedding_input_window_tokens`, then the
 * window the curated table declares for the model, then unknown. The
 * operator key exists for the same reason the price pair does: a model
 * outside the table has no other way to be declared, and an unknown
 * window cuts nothing and censuses nothing.
 *
 * `model` defaults to the configured one; a caller that falls back to the
 * model the index recorded (the census) passes that instead.
 *
 * The offline local embedder answers `null` whatever the key says: it
 * hashes n-gram features over the whole text, with no encoder and no
 * positional limit, so there is no window to cut a query to or to
 * census chunks against.
 */
export function effectiveInputWindowTokens(
  semantic: Pick<ResolvedEmbeddingConfig, "provider" | "model" | "inputWindowTokens">,
  model: string | null = semantic.model,
): number | null {
  if (semantic.provider === "local") return null;
  return semantic.inputWindowTokens ?? declaredInputWindowTokens(model);
}

/**
 * Structural e5-family detection (memory-write-path-integrity B2). Matches the
 * `e5` token wherever it appears delimited by `/` or `-` in the model id
 * (`intfloat/e5-large-v2`, `intfloat/multilingual-e5-small`), so a custom e5
 * model string not in the curated catalog still gets the instruction-prefix
 * defaults. Keys off the model id structure, never the prose note.
 */
export function isE5FamilyModel(model: string | null): boolean {
  if (!model) return false;
  return /(^|[/-])e5([/-]|$)/i.test(model);
}

/**
 * The passage prefix the CONFIGURED BACKEND will actually prepend to an
 * indexed chunk before the provider counts a token.
 *
 * Not the same question as {@link resolveEmbeddingPrefixes}, which
 * answers what the configuration asks for. Only `openai-compat`
 * implements the instruction-prefix contract (`prefixFor` in
 * `openai-compat.ts`); ZeroEntropy's `embed` takes no kind and sends the
 * raw text, the local embedder hashes n-grams over it, and the null
 * provider sends nothing at all. A census that subtracted a configured
 * prefix from a backend that never sends one would report an overflow
 * nobody can hit.
 *
 * The switch is exhaustive over {@link EmbeddingProviderName} with no
 * default arm, so adding a backend fails to compile here rather than
 * silently inheriting "sends no prefix".
 */
export function passagePrefixSentByProvider(
  provider: EmbeddingProviderName,
  configuredPassagePrefix: string | undefined,
): string {
  switch (provider) {
    case "openai-compat":
      // Exactly `OpenAICompatProvider.prefixFor("passage")`: an absent
      // configured prefix is no prefix, an empty one is disabled.
      return configuredPassagePrefix ?? "";
    case "zeroentropy":
    case "local":
    case "disabled":
      return "";
  }
}

/**
 * The query prefix the CONFIGURED BACKEND will actually prepend to a
 * search query - the twin of {@link passagePrefixSentByProvider}, for the
 * same reason: a query fit that charged a prefix to a backend that never
 * sends one would cut a query that fits.
 *
 * Exhaustive over {@link EmbeddingProviderName} with no default arm, so a
 * new backend fails to compile here.
 */
export function queryPrefixSentByProvider(
  provider: EmbeddingProviderName,
  configuredQueryPrefix: string | undefined,
): string {
  switch (provider) {
    case "openai-compat":
      // Exactly `OpenAICompatProvider.prefixFor("query")`.
      return configuredQueryPrefix ?? "";
    case "zeroentropy":
    case "local":
    case "disabled":
      return "";
  }
}

/** The prefix pair active for an embed run, after preset + config resolution. */
export interface ResolvedEmbeddingPrefixes {
  readonly queryPrefix: string;
  readonly passagePrefix: string;
}

/**
 * Resolve the active query/passage instruction prefixes
 * (memory-write-path-integrity B2). Precedence per kind: an explicit config
 * override (including an empty string, which disables the prefix) wins;
 * otherwise the curated preset field; otherwise the structural e5 default;
 * otherwise no prefix. A `null` override means "not configured" and falls
 * through; an empty-string override means "explicitly disabled".
 */
export function resolveEmbeddingPrefixes(
  model: string | null,
  queryOverride: string | null,
  passageOverride: string | null,
): ResolvedEmbeddingPrefixes {
  const preset = model ? findEmbeddingPreset(model) : null;
  const e5 = isE5FamilyModel(model);
  const queryDefault = preset?.queryPrefix ?? (e5 ? E5_QUERY_PREFIX : "");
  const passageDefault = preset?.passagePrefix ?? (e5 ? E5_PASSAGE_PREFIX : "");
  return {
    queryPrefix: queryOverride ?? queryDefault,
    passagePrefix: passageOverride ?? passageDefault,
  };
}