Skip to content

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

9.2 KB
Raw Blame
import type { FindResultItem } from "./client.js";

export function clampScore(value: number | undefined): number {
  if (typeof value !== "number" || Number.isNaN(value)) {
    return 0;
  }
  return Math.max(0, Math.min(1, value));
}

function normalizeDedupeText(text: string): string {
  return text.toLowerCase().replace(/\s+/g, " ").trim();
}

function isEventOrCaseMemory(item: FindResultItem): boolean {
  const category = (item.category ?? "").toLowerCase();
  const uri = item.uri.toLowerCase();
  return (
    category === "events" ||
    category === "cases" ||
    uri.includes("/events/") ||
    uri.includes("/cases/")
  );
}

function getMemoryDedupeKey(item: FindResultItem): string {
  const abstract = normalizeDedupeText(item.abstract ?? item.overview ?? "");
  const category = (item.category ?? "").toLowerCase() || "unknown";
  if (abstract && !isEventOrCaseMemory(item)) {
    return `abstract:${category}:${abstract}`;
  }
  return `uri:${item.uri}`;
}

export function postProcessMemories(
  items: FindResultItem[],
  options: {
    limit: number;
    scoreThreshold: number;
    leafOnly?: boolean;
  },
): FindResultItem[] {
  const deduped: FindResultItem[] = [];
  const seen = new Set<string>();
  const sorted = [...items].sort((a, b) => clampScore(b.score) - clampScore(a.score));
  for (const item of sorted) {
    if (options.leafOnly && item.level !== 2) {
      continue;
    }
    if (clampScore(item.score) < options.scoreThreshold) {
      continue;
    }
    const key = getMemoryDedupeKey(item);
    if (seen.has(key)) {
      continue;
    }
    seen.add(key);
    deduped.push(item);
    if (deduped.length >= options.limit) {
      break;
    }
  }
  return deduped;
}

export function formatMemoryLines(items: FindResultItem[]): string {
  return items
    .map((item, index) => {
      const score = clampScore(item.score);
      const abstract = item.abstract?.trim() || item.overview?.trim() || item.uri;
      const category = item.category ?? "memory";
      return `${index + 1}. [${category}] ${abstract} (${(score * 100).toFixed(0)}%)`;
    })
    .join("\n");
}

export function trimForLog(value: string, limit = 260): string {
  const normalized = value.trim();
  if (normalized.length <= limit) {
    return normalized;
  }
  return `${normalized.slice(0, limit)}...`;
}

export function toJsonLog(value: unknown, maxLen = 6000): string {
  try {
    const json = JSON.stringify(value);
    if (json.length <= maxLen) {
      return json;
    }
    return JSON.stringify({
      truncated: true,
      length: json.length,
      preview: `${json.slice(0, maxLen)}...`,
    });
  } catch {
    return JSON.stringify({ error: "stringify_failed" });
  }
}

export function summarizeInjectionMemories(items: FindResultItem[]): Array<Record<string, unknown>> {
  return items.map((item) => ({
    uri: item.uri,
    category: item.category ?? null,
    abstract: trimForLog(item.abstract?.trim() || item.overview?.trim() || item.uri, 180),
    score: clampScore(item.score),
    is_leaf: item.level === 2,
  }));
}

export function summarizeExtractedMemories(
  items: Array<Record<string, unknown>>,
): Array<Record<string, unknown>> {
  return items.slice(0, 10).map((item) => {
    const abstractRaw =
      typeof item.abstract === "string"
        ? item.abstract
        : typeof item.overview === "string"
          ? item.overview
          : typeof item.title === "string"
            ? item.title
            : "";
    return {
      uri: typeof item.uri === "string" ? item.uri : null,
      category: typeof item.category === "string" ? item.category : null,
      abstract: trimForLog(abstractRaw, 180),
      is_leaf: item.level === 2,
    };
  });
}

function isPreferencesMemory(item: FindResultItem): boolean {
  return (
    item.category === "preferences" ||
    item.uri.includes("/preferences/") ||
    item.uri.endsWith("/preferences")
  );
}

function isEventMemory(item: FindResultItem): boolean {
  const category = (item.category ?? "").toLowerCase();
  return category === "events" || item.uri.includes("/events/");
}

function isLeafLikeMemory(item: FindResultItem): boolean {
  return item.level === 2;
}

const PREFERENCE_QUERY_RE = /prefer|preference|favorite|favourite|like|偏好|喜欢|爱好|更倾向/i;
const TEMPORAL_QUERY_RE =
  /when|what time|date|day|month|year|yesterday|today|tomorrow|last|next|什么时候|何时|哪天|几月|几年|昨天|今天|明天|上周|下周|上个月|下个月|去年|明年/i;
const QUERY_TOKEN_RE = /[a-z0-9]{2,}/gi;
const QUERY_TOKEN_STOPWORDS = new Set([
  "what",
  "when",
  "where",
  "which",
  "who",
  "whom",
  "whose",
  "why",
  "how",
  "did",
  "does",
  "is",
  "are",
  "was",
  "were",
  "the",
  "and",
  "for",
  "with",
  "from",
  "that",
  "this",
  "your",
  "you",
]);

type RecallQueryProfile = {
  tokens: string[];
  wantsPreference: boolean;
  wantsTemporal: boolean;
};

export type RankingWeights = {
  baseScore?: number;
  leaf?: number;
  event?: number;
  preference?: number;
  lexicalOverlapMax?: number;
};

export type RankingOptions = {
  weights?: RankingWeights;
  categoryWeights?: Record<string, number>;
  resourceTypeWeights?: Record<string, number>;
};

const DEFAULT_RANKING_WEIGHTS = {
  baseScore: 1,
  leaf: 0.12,
  event: 0.1,
  preference: 0.08,
  lexicalOverlapMax: 0.2,
};

function buildRecallQueryProfile(query: string): RecallQueryProfile {
  const text = query.trim();
  const allTokens = text.toLowerCase().match(QUERY_TOKEN_RE) ?? [];
  const tokens = allTokens.filter((token) => !QUERY_TOKEN_STOPWORDS.has(token));
  return {
    tokens,
    wantsPreference: PREFERENCE_QUERY_RE.test(text),
    wantsTemporal: TEMPORAL_QUERY_RE.test(text),
  };
}

function lexicalOverlapBoost(tokens: string[], text: string, maxBoost = DEFAULT_RANKING_WEIGHTS.lexicalOverlapMax): number {
  if (tokens.length === 0 || !text) {
    return 0;
  }
  const haystack = ` ${text.toLowerCase()} `;
  let matched = 0;
  for (const token of tokens.slice(0, 8)) {
    if (haystack.includes(` ${token} `) || haystack.includes(token)) {
      matched += 1;
    }
  }
  return Math.min(maxBoost, (matched / Math.min(tokens.length, 4)) * maxBoost);
}

function inferResourceType(item: FindResultItem): string | undefined {
  if (item.uri.startsWith("viking://resources")) return "resource";
  if (/^viking:\/\/(?:user\/[^/]+|~)\/sessions(?:\/|$)/.test(item.uri)) return "session";
  if (item.uri.startsWith("viking://user/skills") || item.uri.startsWith("viking://~/skills") || item.uri.startsWith("viking://skills")) return "agent";
  if (item.uri.startsWith("viking://user/") || item.uri.startsWith("viking://~/")) return "user";
  return undefined;
}

function rankForInjection(item: FindResultItem, query: RecallQueryProfile, options?: RankingOptions): number {
  // Keep ranking simple and stable: semantic score + light query-aware boosts.
  const weights = { ...DEFAULT_RANKING_WEIGHTS, ...(options?.weights ?? {}) };
  const baseScore = clampScore(item.score) * weights.baseScore;
  const abstract = (item.abstract ?? item.overview ?? "").trim();
  const leafBoost = isLeafLikeMemory(item) ? weights.leaf : 0;
  const eventBoost = query.wantsTemporal && isEventMemory(item) ? weights.event : 0;
  const preferenceBoost = query.wantsPreference && isPreferencesMemory(item) ? weights.preference : 0;
  const overlapBoost = lexicalOverlapBoost(query.tokens, `${item.uri} ${abstract}`, weights.lexicalOverlapMax);
  const category = (item.category ?? "").toLowerCase();
  const categoryBoost = category ? (options?.categoryWeights?.[category] ?? options?.categoryWeights?.[item.category ?? ""] ?? 0) : 0;
  const resourceType = inferResourceType(item);
  const resourceTypeBoost = resourceType ? (options?.resourceTypeWeights?.[resourceType] ?? 0) : 0;
  return baseScore + leafBoost + eventBoost + preferenceBoost + overlapBoost + categoryBoost + resourceTypeBoost;
}

export function pickMemoriesForInjection(
  items: FindResultItem[],
  limit: number,
  queryText: string,
  scoreThreshold: number = 0,
  rankingOptions?: RankingOptions,
): FindResultItem[] {
  if (items.length === 0 || limit <= 0) {
    return [];
  }

  const query = buildRecallQueryProfile(queryText);
  const sorted = [...items].sort((a, b) => rankForInjection(b, query, rankingOptions) - rankForInjection(a, query, rankingOptions));
  const deduped: FindResultItem[] = [];
  const seen = new Set<string>();
  for (const item of sorted) {
    const abstractKey = (item.abstract ?? item.overview ?? "").trim().toLowerCase();
    const key = abstractKey || item.uri;
    if (seen.has(key)) {
      continue;
    }
    seen.add(key);
    deduped.push(item);
  }
  const leaves = deduped.filter((item) => isLeafLikeMemory(item));
  if (leaves.length >= limit) {
    return leaves.slice(0, limit);
  }

  const picked = [...leaves];
  const used = new Set(leaves.map((item) => item.uri));
  for (const item of deduped) {
    if (picked.length >= limit) {
      break;
    }
    if (used.has(item.uri)) {
      continue;
    }
    // Respect score threshold when supplementing leaf memories with
    // non-leaf items. Without this check, low-scoring memories bypass
    // the threshold configured in recallScoreThreshold (see #1106).
    if (clampScore(item.score) < scoreThreshold) {
      continue;
    }
    picked.push(item);
  }
  return picked;
}