Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

23.2 KB
Raw Blame
// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
/**
 * Every knob a memory plugin reads, declared once.
 *
 * A setting stayed uniform across harnesses only when a shared module read it
 * on the hot path: `recallLimit`, `scoreThreshold` and `captureMaxLength` agree
 * everywhere because `recall-core` and `capture-utils` read them. Everything
 * else drifted — the same switch is `autoRecall` in three loaders, an
 * `autoRecall` *object* in opencode, `syncTurns` in dsh and pi, and absent from
 * the thin hook runtime — because each loader hand-wrote its own list and the
 * author picked a name. Three more lists then had to be kept in step by hand:
 * the doctor's known-knob set, the workspace file's dotted-key map, and the
 * implicit inventory inside `loadAgentHookConfig`.
 *
 * This module is the one list. The others are projections of it:
 * `pluginConfigKeys()` for the doctor, `WORKSPACE_KNOB_MAP` for the workspace
 * file, and `resolveKnobs()` for every loader. A knob added here reaches all of
 * them; a knob spelled wrong reaches none.
 *
 * Declaration fields:
 *   name        canonical key, and the property the loaders read
 *   type        bool | int | number | enum | string | list
 *   default     value when no layer supplies one
 *   harness     per-harness default, where one genuinely differs
 *   min/max     clamped, not rejected: a config file must not kill a hook
 *   values      the enum's members; anything else falls back to the default
 *   env         OPENVIKING_* variable, the highest-priority layer
 *   aliases     older spellings, honoured forever; the doctor names them
 *   workspace   dotted key in `.openviking/config.json`
 *   capability  which capability owns it, for the switches in recall/capture
 *   sendOnlyWhenConfigured
 *               the request omits this field unless a layer actually set it,
 *               so the server's own default stands. Loaders project the flag
 *               as `<name>Configured` and `recall-core` reads it from there.
 */

export const CAPABILITIES = ["connection", "peer", "recall", "capture", "session", "debug"];

/** @type {ReadonlyArray<object>} */
export const KNOBS = [
  // ── connection and identity ────────────────────────────────────────────
  // Credentials resolve through `credentials.mjs`; these entries exist so the
  // doctor recognises them inside `plugin` and so ov.conf's harness section
  // keeps working.
  { name: "enabled", type: "bool", default: true, env: "OPENVIKING_MEMORY_ENABLED", capability: "connection" },
  { name: "apiKey", type: "string", default: "", capability: "connection" },
  { name: "accountId", type: "string", default: "", capability: "connection" },
  { name: "userId", type: "string", default: "", capability: "connection" },
  { name: "authMode", type: "enum", values: ["trusted", "api_key"], default: "", env: "OPENVIKING_AUTH_MODE", aliases: ["auth_mode"], capability: "connection" },
  {
    name: "timeoutMs",
    type: "int",
    default: 15000,
    // opencode drives an editor session that tolerates a slower call; dsh runs
    // inside a chat host that does not.
    harness: { opencode: 30000, dsh: 10000 },
    min: 1000,
    max: 300000,
    env: "OPENVIKING_TIMEOUT_MS",
    aliases: ["requestTimeoutMs"],
    capability: "connection",
  },
  { name: "mcpEnabled", type: "bool", default: true, capability: "connection" },
  { name: "mcpToolCallTimeoutMs", type: "int", default: 60000, min: 1000, max: 600000, capability: "connection" },
  { name: "dataDir", type: "string", default: "", capability: "connection" },

  { name: "peerId", type: "string", default: "", env: "OPENVIKING_PEER_ID", aliases: ["peer_id"], workspace: "peer.id", capability: "peer" },
  { name: "peerSource", type: "template", default: "", env: "OPENVIKING_PEER_SOURCE", workspace: "peer.source", capability: "peer" },
  { name: "workspacePeer", type: "bool", default: true, env: "OPENVIKING_WORKSPACE_PEER", capability: "peer" },

  // ── recall ────────────────────────────────────────────────────────────
  {
    name: "autoRecall",
    type: "bool",
    default: true,
    env: "OPENVIKING_AUTO_RECALL",
    workspace: "recall.enabled",
    capability: "recall",
  },
  { name: "recallLimit", type: "int", default: 10, min: 1, max: 50, env: "OPENVIKING_RECALL_LIMIT", workspace: "recall.max_items", sendOnlyWhenConfigured: true, capability: "recall" },
  { name: "scoreThreshold", type: "number", default: 0.35, min: 0, max: 1, env: "OPENVIKING_SCORE_THRESHOLD", aliases: ["recallScoreThreshold"], workspace: "recall.score_threshold", capability: "recall" },
  { name: "minQueryLength", type: "int", default: 3, min: 1, max: 64, env: "OPENVIKING_MIN_QUERY_LENGTH", aliases: ["recallMinQueryLength"], capability: "recall" },
  { name: "recallTokenBudget", type: "int", default: 2000, min: 200, max: 50000, env: "OPENVIKING_RECALL_TOKEN_BUDGET", aliases: ["recallBudget"], capability: "recall" },
  { name: "recallMaxContentChars", type: "int", default: 500, min: 100, max: 5000, env: "OPENVIKING_RECALL_MAX_CONTENT_CHARS", capability: "recall" },
  { name: "recallPreferAbstract", type: "bool", default: true, env: "OPENVIKING_RECALL_PREFER_ABSTRACT", capability: "recall" },
  { name: "recallPeerScope", type: "enum", values: ["all", "actor"], default: "all", env: "OPENVIKING_RECALL_PEER_SCOPE", workspace: "recall.peer_scope", capability: "recall" },
  // Sent as events_time_decay_protection ("7d", "12h"): event memories keep their score for
  // that long and decay afterwards. Empty leaves decay off, as the server does by default.
  { name: "recallEventsDecayProtection", type: "string", default: "", env: "OPENVIKING_RECALL_EVENTS_DECAY_PROTECTION", capability: "recall" },
  { name: "recallDedupTurns", type: "int", default: 5, min: 0, max: 20, env: "OPENVIKING_RECALL_DEDUP_TURNS", workspace: "recall.dedup_turns", capability: "recall" },
  { name: "recallMaxTokens", type: "int", default: 1600, min: 64, max: 200000, env: "OPENVIKING_RECALL_MAX_TOKENS", sendOnlyWhenConfigured: true, capability: "recall" },
  { name: "recallQueryExpansion", type: "enum", values: ["auto", "off"], default: "auto", env: "OPENVIKING_RECALL_QUERY_EXPANSION", sendOnlyWhenConfigured: true, capability: "recall" },
  { name: "recallTimeoutMs", type: "int", default: 120000, min: 1000, max: 600000, env: "OPENVIKING_RECALL_TIMEOUT_MS", capability: "recall" },
  // 0 keeps the built-in default, which outlasts the server's rewrite fuse.
  { name: "recallContextTimeoutMs", type: "int", default: 0, min: 0, max: 600000, env: "OPENVIKING_RECALL_CONTEXT_TIMEOUT_MS", capability: "recall" },
  { name: "logRankingDetails", type: "bool", default: false, env: "OPENVIKING_LOG_RANKING_DETAILS", capability: "recall" },
  { name: "recallLedger", type: "bool", default: true, env: "OPENVIKING_RECALL_LEDGER", capability: "recall" },
  { name: "recallQueryFilters", type: "list", default: [], env: "OPENVIKING_RECALL_QUERY_FILTERS", capability: "recall" },
  // Subtree URIs the recall search must never return. Without this there is no
  // way to keep generated directory files (viking://user/<space>/skills,
  // viking://user/<space>/resources, viking://agent/skills) out of the hits:
  // they match like ordinary content and carry only boilerplate text.
  {
    name: "recallExcludeUris",
    type: "list",
    default: [],
    env: "OPENVIKING_RECALL_EXCLUDE_URIS",
    capability: "recall",
  },

  // Digest compression. Claude Code reads this as the tri-state
  // off/client/server/auto through `normalizeRewriteMode`; Codex reads the same
  // key as on/off. Both spellings stay declared so neither harness's users are
  // told their config is a typo.
  { name: "recallCompress", type: "string", default: "off", harness: { claude_code: "auto", codex: "auto" }, env: "OPENVIKING_RECALL_COMPRESS", aliases: ["recallRewrite"], capability: "recall" },
  { name: "recallCompressModel", type: "string", default: "", env: "OPENVIKING_RECALL_COMPRESS_MODEL", capability: "recall" },
  { name: "recallCompressBaseUrl", type: "string", default: "", env: "OPENVIKING_RECALL_COMPRESS_BASE_URL", capability: "recall" },
  { name: "recallCompressThinking", type: "string", default: "", env: "OPENVIKING_RECALL_COMPRESS_THINKING", aliases: ["recallCompressReasoningEffort"], capability: "recall" },
  // 0 means "derive from recallTimeoutMs" — the loader that owns the fallback
  // is the one that knows the request budget it has to fit inside.
  { name: "recallCompressTimeoutMs", type: "int", default: 0, min: 0, max: 600000, env: "OPENVIKING_RECALL_COMPRESS_TIMEOUT_MS", capability: "recall" },
  { name: "recallCompressDetectOnStartup", type: "bool", default: true, env: "OPENVIKING_RECALL_COMPRESS_DETECT_ON_STARTUP", capability: "recall" },
  { name: "recallCompressDetectTimeoutMs", type: "int", default: 15000, min: 1000, max: 600000, env: "OPENVIKING_RECALL_COMPRESS_DETECT_TIMEOUT_MS", capability: "recall" },
  { name: "recallCompressDetectTtlMs", type: "int", default: 604800000, min: 0, capability: "recall", env: "OPENVIKING_RECALL_COMPRESS_DETECT_TTL_MS" },
  { name: "recallCompressMinInputChars", type: "int", default: 1500, min: 0, max: 100000, env: "OPENVIKING_RECALL_COMPRESS_MIN_INPUT_CHARS", capability: "recall" },
  { name: "recallCompressMaxInputChars", type: "int", default: 18000, min: 1000, max: 200000, env: "OPENVIKING_RECALL_COMPRESS_MAX_INPUT_CHARS", capability: "recall" },
  { name: "recallCompressMaxBullets", type: "int", default: 6, min: 1, max: 50, env: "OPENVIKING_RECALL_COMPRESS_MAX_BULLETS", sendOnlyWhenConfigured: true, capability: "recall" },

  // ── capture ───────────────────────────────────────────────────────────
  // `syncTurns` is dsh and pi's spelling of the same switch. It stays an alias
  // rather than a second knob so `ov config switch` moves both.
  {
    name: "autoCapture",
    type: "bool",
    default: true,
    env: "OPENVIKING_AUTO_CAPTURE",
    aliases: ["syncTurns"],
    workspace: "capture.enabled",
    capability: "capture",
  },
  { name: "captureMode", type: "enum", values: ["semantic", "keyword"], default: "semantic", env: "OPENVIKING_CAPTURE_MODE", capability: "capture" },
  { name: "captureMaxLength", type: "int", default: 24000, min: 200, max: 100000, env: "OPENVIKING_CAPTURE_MAX_LENGTH", capability: "capture" },
  // Tool output is reported verbatim; the server owns truncation via
  // tool_output_externalization. This cap only guards pathological payloads.
  { name: "captureToolMaxChars", type: "int", default: 1000000, min: 200, max: 1000000, env: "OPENVIKING_CAPTURE_TOOL_MAX_CHARS", capability: "capture" },
  // Default true: a memory plugin that only sees the user's half of the
  // conversation extracts noticeably worse.
  { name: "captureAssistantTurns", type: "bool", default: true, env: "OPENVIKING_CAPTURE_ASSISTANT_TURNS", capability: "capture" },
  { name: "captureLastAssistantOnStop", type: "bool", default: true, env: "OPENVIKING_CAPTURE_LAST_ASSISTANT_ON_STOP", capability: "capture" },
  // dsh is the only reader. Its Experience usage records need the completed
  // tool results, so it captures them by default.
  { name: "captureToolResults", type: "bool", default: false, harness: { dsh: true }, env: "OPENVIKING_CAPTURE_TOOL_RESULTS", capability: "capture" },
  { name: "captureFilters", type: "list", default: [], env: "OPENVIKING_CAPTURE_FILTERS", capability: "capture" },
  // 0 means "derive from timeoutMs": a write gets a longer budget than a read.
  { name: "captureTimeoutMs", type: "int", default: 0, min: 0, max: 600000, env: "OPENVIKING_CAPTURE_TIMEOUT_MS", capability: "capture" },
  { name: "commitTokenThreshold", type: "int", default: 20000, min: 1000, max: 1000000, env: "OPENVIKING_COMMIT_TOKEN_THRESHOLD", workspace: "capture.commit_token_threshold", capability: "capture" },
  { name: "commitKeepRecentCount", type: "int", default: 10, min: 0, max: 1000, env: "OPENVIKING_COMMIT_KEEP_RECENT_COUNT", capability: "capture" },
  { name: "commitTurnThreshold", type: "int", default: 8, min: 1, max: 1000, env: "OPENVIKING_COMMIT_TURN_THRESHOLD", capability: "capture" },
  { name: "autoCommitOnCompact", type: "bool", default: true, env: "OPENVIKING_AUTO_COMMIT_ON_COMPACT", capability: "capture" },
  { name: "writePathAsync", type: "bool", default: true, env: "OPENVIKING_WRITE_PATH_ASYNC", capability: "capture" },

  // ── session lifecycle ─────────────────────────────────────────────────
  { name: "noAutoInject", type: "bool", default: false, env: "OPENVIKING_NO_AUTO_INJECT", capability: "session" },
  { name: "profileTokenBudget", type: "int", default: 10000, min: 500, max: 50000, env: "OPENVIKING_PROFILE_TOKEN_BUDGET", aliases: ["profileBudget"], capability: "session" },
  { name: "resumeContextBudget", type: "int", default: 32000, min: 1024, max: 128000, env: "OPENVIKING_RESUME_CONTEXT_BUDGET", capability: "session" },
  { name: "resumeArchiveInject", type: "bool", default: false, env: "OPENVIKING_RESUME_ARCHIVE_INJECT", capability: "session" },
  { name: "resumeArchiveTokenBudget", type: "int", default: 32000, min: 0, max: 128000, env: "OPENVIKING_RESUME_ARCHIVE_TOKEN_BUDGET", capability: "session" },
  { name: "resumeArchiveMaxChars", type: "int", default: 6000, min: 1000, max: 200000, env: "OPENVIKING_RESUME_ARCHIVE_MAX_CHARS", capability: "session" },
  { name: "skillExperience", type: "bool", default: false, env: "OPENVIKING_SKILL_EXPERIENCE", capability: "session" },
  { name: "skillExperienceLimit", type: "int", default: 3, min: 1, max: 50, env: "OPENVIKING_SKILL_EXPERIENCE_LIMIT", capability: "session" },
  { name: "skillCatalog", type: "bool", default: true, env: "OPENVIKING_SKILL_CATALOG", capability: "session" },
  { name: "skillCatalogTokenBudget", type: "int", default: 1200, min: 0, max: 20000, env: "OPENVIKING_SKILL_CATALOG_TOKEN_BUDGET", capability: "session" },
  // Claude Code saves hook context over 10,000 chars to a file and shows the
  // model a 2 KB preview; Codex spills past ~10,000 bytes; ZCode drops stdout
  // over 32 KB. 0 means no cap.
  {
    name: "sessionStartMaxBytes",
    type: "int",
    default: 0,
    harness: { claude_code: 9500, codex: 9500, zcode: 20000 },
    min: 0,
    max: 1000000,
    env: "OPENVIKING_SESSION_START_MAX_BYTES",
    capability: "session",
  },
  { name: "skipSubagentSessions", type: "bool", default: false, env: "OPENVIKING_SKIP_SUBAGENT_SESSIONS", capability: "session" },
  { name: "repoContext", type: "bool", default: true, capability: "session" },
  { name: "repoContextCacheTtlMs", type: "int", default: 60000, min: 1000, max: 3600000, capability: "session" },

  { name: "takeoverEnabled", type: "bool", default: false, env: "OPENVIKING_TAKEOVER", capability: "session" },
  { name: "takeoverTokenThreshold", type: "int", default: 30000, min: 1, max: 1000000, capability: "session" },
  { name: "takeoverKeepRecentTurns", type: "int", default: 3, min: 0, max: 100, capability: "session" },
  { name: "takeoverOverviewBudget", type: "int", default: 3000, min: 100, max: 50000, capability: "session" },
  { name: "takeoverOverviewPollMs", type: "int", default: 2000, min: 0, max: 60000, capability: "session" },
  { name: "takeoverOverviewPollMax", type: "int", default: 15, min: 1, max: 120, capability: "session" },

  { name: "bypassSession", type: "bool", default: false, env: "OPENVIKING_BYPASS_SESSION", capability: "session" },
  {
    name: "bypassSessionPatterns",
    type: "list",
    default: [],
    env: "OPENVIKING_BYPASS_SESSION_PATTERNS",
    // pi shipped this under its own name before the shared matcher existed.
    aliases: ["bypassPatterns"],
    workspace: "bypass.session_patterns",
    capability: "session",
  },

  // Codex's OV-Usage footer. Strings rather than enums: the reader matches
  // several spellings case-insensitively (off/false/0/disabled, expanded/full/details).
  { name: "usageView", type: "string", default: "summary", env: "OPENVIKING_USAGE_VIEW", workspace: "usage.view", capability: "session" },
  { name: "usageOutput", type: "string", default: "auto", env: "OPENVIKING_USAGE_OUTPUT", workspace: "usage.output", capability: "session" },

  // ── debug ─────────────────────────────────────────────────────────────
  { name: "debug", type: "bool", default: false, env: "OPENVIKING_DEBUG", capability: "debug" },
  // The default path is per-harness and built from a log directory the loader
  // owns, so the schema only carries what a user set.
  { name: "debugLogPath", type: "string", default: "", env: "OPENVIKING_DEBUG_LOG", capability: "debug" },
  { name: "logLevel", type: "enum", values: ["silent", "error", "info"], default: "error", env: "OPENVIKING_LOG_LEVEL", capability: "debug" },
];

export const KNOB_BY_NAME = new Map(KNOBS.map((knob) => [knob.name, knob]));

/** Every accepted spelling → the canonical knob it means. */
export const KNOB_BY_KEY = new Map();
for (const knob of KNOBS) {
  KNOB_BY_KEY.set(knob.name, knob);
  for (const alias of knob.aliases || []) KNOB_BY_KEY.set(alias, knob);
}

/** Every key a user may legitimately write in `ovcli.conf`'s plugin section. */
export function pluginConfigKeys() {
  return new Set(KNOB_BY_KEY.keys());
}

/** The workspace file's dotted keys → the knob each one sets. */
export const WORKSPACE_KNOB_MAP = Object.fromEntries(
  KNOBS.filter((knob) => knob.workspace).map((knob) => [knob.workspace, knob.name]),
);

/** The enum members and clamps the workspace validator reports on. */
export const WORKSPACE_ENUMS = Object.fromEntries(
  KNOBS.filter((knob) => knob.workspace).map((knob) => [knob.workspace, knob.values || null]),
);

export const WORKSPACE_RANGES = Object.fromEntries(
  KNOBS.filter((knob) => knob.workspace && knob.min !== undefined && knob.max !== undefined)
    .map((knob) => [knob.workspace, {
      min: knob.min,
      max: knob.max,
      integer: knob.type === "int",
    }]),
);

/**
 * The harnesses that may appear as a per-harness object inside `plugin`.
 *
 * The key is snake_case because that is what ov.conf's own sections use; the
 * hyphenated spelling a host calls itself (`claude-code`, `trae-cn`) is
 * accepted too, so a user who copies the harness name out of the installer
 * lands on the right override instead of on a silent no-op.
 */
export const HARNESS_KEYS = {
  claudeCode: "claude_code",
  codebuddy: "codebuddy",
  codex: "codex",
  cursor: "cursor",
  kimicode: "kimicode",
  trae: "trae",
  traeCn: "trae_cn",
  zcode: "zcode",
  opencode: "opencode",
  dsh: "dsh",
  pi: "pi",
  openclaw: "openclaw",
};

export function harnessKey(harness) {
  return String(harness || "").trim().toLowerCase().replace(/-/g, "_");
}

/** Both accepted spellings of every harness, for the `plugin` section. */
export const HARNESS_CONFIG_KEYS = new Set(
  Object.values(HARNESS_KEYS).flatMap((key) => [key, key.replace(/_/g, "-")]),
);

export function knobDefault(knob, harness = "") {
  if (harness && knob.harness && knob.harness[harness] !== undefined) return knob.harness[harness];
  return Array.isArray(knob.default) ? [...knob.default] : knob.default;
}

const TRUE_WORDS = ["1", "true", "yes", "on"];
const FALSE_WORDS = ["0", "false", "no", "off"];

/**
 * Coerce one raw value to the knob's type.
 *
 * A value out of range is clamped and a value of the wrong shape falls back to
 * the default: a hook that dies because someone typed a letter into a number
 * would take the host's session down with it.
 */
export function coerceKnobValue(knob, raw, fallback) {
  if (raw === undefined || raw === null) return fallback;
  switch (knob.type) {
    case "bool": {
      if (typeof raw === "boolean") return raw;
      const word = String(raw).trim().toLowerCase();
      if (TRUE_WORDS.includes(word)) return true;
      if (FALSE_WORDS.includes(word)) return false;
      return fallback;
    }
    case "int":
    case "number": {
      if (typeof raw === "string" && !raw.trim()) return fallback;
      const value = knob.type === "int" ? Math.round(Number(raw)) : Number(raw);
      if (!Number.isFinite(value)) return fallback;
      const floored = knob.min === undefined ? value : Math.max(knob.min, value);
      return knob.max === undefined ? floored : Math.min(knob.max, floored);
    }
    case "enum": {
      const word = String(raw ?? "").trim();
      return (knob.values || []).includes(word) ? word : fallback;
    }
    // A peer template may be one string or an ordered list of fallbacks, and
    // `String([a, b])` would quietly turn the list into one bogus template.
    case "template": {
      if (Array.isArray(raw)) {
        const items = raw.filter((item) => typeof item === "string").map((item) => item.trim()).filter(Boolean);
        return items.length ? items : fallback;
      }
      const text = String(raw ?? "").trim();
      return text ? text : fallback;
    }
    case "list": {
      const items = Array.isArray(raw)
        ? raw
        : typeof raw === "string" ? raw.split(",") : null;
      if (!items) return fallback;
      return items.filter((item) => typeof item === "string").map((item) => item.trim()).filter(Boolean);
    }
    default: {
      const text = String(raw ?? "").trim();
      return text ? text : fallback;
    }
  }
}

/**
 * Resolve every knob through the layers, lowest priority first.
 *
 * `layers` is `[{ name, data }]`; `env` is the top layer and needs no entry.
 * Returns the settings plus the names a layer actually supplied, which is what
 * the `*Configured` flags report — several call sites send a field to the
 * server only when the user asked for it, and a default must not look asked-for.
 */
export function resolveKnobs({ harness = "", layers = [], env = {} } = {}) {
  const settings = {};
  const configured = new Set();
  const sources = {};
  // A value that would not parse is not a configuration: without this sentinel
  // `recallLimit: "abc"` would report as configured and send a default to the
  // server dressed up as the user's choice.
  const UNPARSEABLE = Symbol("unparseable");

  const take = (knob, raw, source, current) => {
    const value = coerceKnobValue(knob, raw, UNPARSEABLE);
    if (value === UNPARSEABLE) return current;
    configured.add(knob.name);
    sources[knob.name] = source;
    return value;
  };

  for (const knob of KNOBS) {
    let value = knobDefault(knob, harness);
    for (const layer of layers) {
      const data = layer?.data;
      if (!data || typeof data !== "object") continue;
      // Aliases first so the canonical name wins when one layer carries both:
      // a file with `recallCompressThinking` beside its older
      // `recallCompressReasoningEffort` means the newer one.
      for (const key of [...(knob.aliases || []), knob.name]) {
        if (!Object.prototype.hasOwnProperty.call(data, key)) continue;
        if (data[key] === undefined) continue;
        value = take(knob, data[key], layer.name || "file", value);
      }
    }
    if (knob.env) {
      const raw = env[knob.env];
      if (raw !== undefined && raw !== null && String(raw) !== "") {
        value = take(knob, raw, "env", value);
      }
    }
    settings[knob.name] = value;
  }

  return { settings, configured, sources };
}