recallnest 1.4.1

package/src/preference-matcher.ts

@@ -0,0 +1,174 @@
+/**
+ * Preference Matcher — Tier 3.6
+ *
+ * When a new preference is about to be stored, checks for semantically similar
+ * existing preferences in the same scope. If found, uses LLM to decide:
+ * - MERGE: combine into existing entry (update text)
+ * - SKIP: incoming is a duplicate, drop it
+ * - CREATE: genuinely new preference, store normally
+ *
+ * This prevents duplicate preference accumulation without being too aggressive
+ * (unlike hard dedup which might miss nuanced differences).
+ */
+
+import type { MemoryStore, MemoryEntry } from "./store.js";
+import type { Embedder } from "./embedder.js";
+import type { LLMClient } from "./llm-client.js";
+import { logInfo } from "./stderr-log.js";
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+export interface PreferenceMatcherConfig {
+  /** Minimum vector similarity to consider a match (default: 0.78) */
+  similarityThreshold: number;
+  /** Maximum candidates to check (default: 3) */
+  maxCandidates: number;
+}
+
+export const DEFAULT_PREFERENCE_MATCHER_CONFIG: PreferenceMatcherConfig = {
+  similarityThreshold: 0.78,
+  maxCandidates: 3,
+};
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface PreferenceMatchResult {
+  /** What to do with the incoming preference */
+  action: "merge" | "skip" | "create";
+  /** ID of the existing entry to merge into (when action=merge) */
+  mergeTargetId?: string;
+  /** Merged text (when action=merge, LLM-generated) */
+  mergedText?: string;
+  /** Reason for the decision */
+  reason: string;
+}
+
+// ============================================================================
+// Core
+// ============================================================================
+
+/**
+ * Check if an incoming preference matches existing ones and decide what to do.
+ *
+ * @param text     The new preference text
+ * @param vector   Pre-computed embedding vector for the text
+ * @param scope    The scope to search within
+ * @param store    Memory store
+ * @param llm      LLM client (null = always create)
+ * @param config   Optional config overrides
+ */
+export async function matchPreference(
+  text: string,
+  vector: number[],
+  scope: string,
+  store: MemoryStore,
+  llm: LLMClient | null,
+  config: PreferenceMatcherConfig = DEFAULT_PREFERENCE_MATCHER_CONFIG,
+): Promise<PreferenceMatchResult> {
+  // Find similar preferences in the same scope
+  const candidates = await store.vectorSearch(
+    vector,
+    config.maxCandidates,
+    config.similarityThreshold,
+    [scope],
+  );
+
+  // Filter to only preferences category
+  const prefMatches = candidates.filter(c => c.entry.category === "preferences");
+
+  if (prefMatches.length === 0) {
+    return { action: "create", reason: "no-similar-preferences" };
+  }
+
+  // Without LLM, fall back to simple similarity-based decision
+  if (!llm) {
+    const topScore = prefMatches[0].score;
+    if (topScore >= 0.92) {
+      return { action: "skip", reason: "high-similarity-no-llm" };
+    }
+    return { action: "create", reason: "moderate-similarity-no-llm" };
+  }
+
+  // Ask LLM to decide
+  const topMatch = prefMatches[0];
+  try {
+    const decision = await llm.dedupDecision(text, topMatch.entry.text);
+
+    if (decision.action === "SKIP") {
+      return {
+        action: "skip",
+        reason: `llm-skip: ${decision.reason}`,
+      };
+    }
+
+    if (decision.action === "MERGE") {
+      // Generate merged text
+      const mergedText = await generateMergedPreference(llm, text, topMatch.entry.text);
+      return {
+        action: "merge",
+        mergeTargetId: topMatch.entry.id,
+        mergedText: mergedText ?? `${topMatch.entry.text}; ${text}`,
+        reason: `llm-merge: ${decision.reason}`,
+      };
+    }
+
+    return { action: "create", reason: `llm-create: ${decision.reason}` };
+  } catch {
+    // LLM failure → safe default: create
+    return { action: "create", reason: "llm-error" };
+  }
+}
+
+/**
+ * Apply the match result: either merge into existing or signal to skip/create.
+ *
+ * @returns true if handled (merged or skipped), false if caller should proceed to create
+ */
+export async function applyPreferenceMatch(
+  result: PreferenceMatchResult,
+  store: MemoryStore,
+  scope: string,
+): Promise<{ handled: boolean; entry?: MemoryEntry }> {
+  if (result.action === "skip") {
+    logInfo(`[INFO] Preference skipped (duplicate): ${result.reason}`);
+    return { handled: true };
+  }
+
+  if (result.action === "merge" && result.mergeTargetId && result.mergedText) {
+    const updated = await store.update(
+      result.mergeTargetId,
+      { text: result.mergedText },
+      [scope],
+    );
+    if (updated) {
+      logInfo(`[INFO] Preference merged into ${result.mergeTargetId.slice(0, 8)}: ${result.reason}`);
+      return { handled: true, entry: updated };
+    }
+  }
+
+  return { handled: false };
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+async function generateMergedPreference(
+  llm: LLMClient,
+  newText: string,
+  existingText: string,
+): Promise<string | null> {
+  try {
+    return await llm.synthesizeFragments(
+      [existingText, newText],
+      "merge preferences",
+      300,
+    );
+  } catch {
+    return null;
+  }
+}

package/src/preference-slots.ts

@@ -0,0 +1,259 @@
+const ROLE_PREFIX_RE = /^\[(用户|助手)\]\s*/gm;
+const PREFERENCE_SPLIT_RE = /(?:、|,|，|\/|以及|及|与|和| and | & )/iu;
+const PREFERENCE_CLAUSE_STOP_RE = /(?:因为|所以|但是|不过|if |when |because |but )/iu;
+const LEADING_ENGLISH_ARTICLE_RE = /^(?:the|a|an)\s+/iu;
+const REPLY_STYLE_CONTEXT_RE = /(?:\brepl(?:y|ies)\b|\bresponse(?:s)?\b|\brespond(?:ing)?\b|\bwriting\b|\btone\b|\bvoice\b|\bstyle\b|回复|回答|语气|写作|表达|风格|措辞|说话)/iu;
+const REPLY_STYLE_PREFERENCE_CUE_RE = /(?:\bprefer(?:s|red)?\b|\bwants?\b|\bplease\b|\bavoid\b|\bkeep\b|\bneed(?:s|ed)?\b|偏好|喜欢|希望|请|要|不要|不接受|避免|尽量|最好)/iu;
+const BRAND_ITEM_PREFERENCE_PATTERNS = [
+  /(?:^|[\s，,。；;！!？?])(?:我|用户)?(?:很|更|还)?(?:喜欢|爱吃|偏爱|常吃|想吃)(?:吃|喝|用|买)?(?<brand>[\p{Script=Han}A-Za-z0-9&·'\-]{1,24})的(?<items>[\p{Script=Han}A-Za-z0-9&·'\-\s、,，和及与/]{1,80})/u,
+  /\b(?:i|user)?\s*(?:really\s+|still\s+|also\s+)?(?:like|love|prefer|enjoy)\s+(?<items>[a-z0-9'&\-\s]{1,80})\s+from\s+(?<brand>[a-z0-9'&\-\s]{1,40})/iu,
+] as const;
+const TOOL_CHOICE_PREFERENCE_PATTERNS = [
+  /^(?:\s*)(?:i|user)?\s*(?:really\s+|still\s+|also\s+)?(?:use|uses|using|prefer|prefers|preferred|pick|picks|picked)\s+(?<preferred>[a-z0-9.+#/_\-\s]{1,24})\s+(?:over|instead of|rather than)\s+(?<avoided>[a-z0-9.+#/_\-\s]{1,24})(?:\s*[.!?。！？])?\s*$/iu,
+  /(?:更喜欢|喜欢|偏好|倾向|优先)(?:使用|用)?(?<preferred>[A-Za-z0-9.+#/_\-\s]{1,24})(?:\s*)(?:而不是|而非|不用|不选|代替|替代|优先于|胜过)(?:\s*)(?<avoided>[A-Za-z0-9.+#/_\-\s]{1,24})/u,
+  /(?:使用|用)(?<preferred>[A-Za-z0-9.+#/_\-\s]{1,24})(?:\s*)(?:不用|代替|替代)(?<avoided>[A-Za-z0-9.+#/_\-\s]{1,24})/u,
+] as const;
+const REPLY_STYLE_TRAIT_PATTERNS = [
+  {
+    key: "concise",
+    pattern: /(?:\bconcise\b|\bbrief\b|\bshort\b|简洁|简短|短句|少废话|少空话|精炼)/iu,
+  },
+  {
+    key: "direct",
+    pattern: /(?:\bdirect\b|\bstraight(?:forward)?\b|to the point|直说|直接|不绕弯|别绕弯|开门见山)/iu,
+  },
+  {
+    key: "colloquial",
+    pattern: /(?:\bcolloquial\b|\bconversational\b|\bcasual\b|口语化|像聊天|像朋友聊天)/iu,
+  },
+  {
+    key: "grounded",
+    pattern: /(?:\bgrounded\b|non[-\s]?salesy|non[-\s]?hype|avoid sales language|avoid hype|不浮夸|不鸡血|不说教|不营销(?:腔)?|别太飘|不端着|别太端着)/iu,
+  },
+  {
+    key: "technical",
+    pattern: /(?:\btechnical\b|逻辑清晰|讲清楚|讲明白|技术向)/iu,
+  },
+] as const;
+const TOOL_ALIAS_MAP: Record<string, string> = {
+  bun: "bun",
+  bunjs: "bun",
+  bunx: "bunx",
+  node: "node",
+  "node.js": "node",
+  nodejs: "node",
+  npm: "npm",
+  pnpm: "pnpm",
+  yarn: "yarn",
+  npx: "npx",
+  uv: "uv",
+  pip: "pip",
+  python: "python",
+  docker: "docker",
+  podman: "podman",
+  rg: "rg",
+  ripgrep: "rg",
+  grep: "grep",
+  git: "git",
+  claude: "claude-code",
+  claudecode: "claude-code",
+  "claude-code": "claude-code",
+  codex: "codex",
+  gemini: "gemini",
+  cursor: "cursor",
+  vscode: "vscode",
+  "vs-code": "vscode",
+  vscodeinsiders: "vscode",
+  vim: "vim",
+  neovim: "neovim",
+  nvim: "neovim",
+} as const;
+
+export interface ParsedBrandItemPreference {
+  brand: string;
+  items: string[];
+  aggregate: boolean;
+}
+
+export interface AtomicBrandItemPreferenceSlot {
+  type: "brand-item";
+  brand: string;
+  item: string;
+}
+
+export interface ReplyStylePreferenceSlot {
+  type: "reply-style";
+  traits: string[];
+}
+
+export interface ToolChoicePreferenceSlot {
+  type: "tool-choice";
+  preferredTool: string;
+  avoidedTool: string;
+}
+
+export type PreferenceSlot =
+  | AtomicBrandItemPreferenceSlot
+  | ReplyStylePreferenceSlot
+  | ToolChoicePreferenceSlot;
+
+function normalizePreferenceText(value: string): string {
+  return value
+    .replace(ROLE_PREFIX_RE, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function normalizePreferenceToken(value: string): string {
+  return normalizePreferenceTokenWithOptions(value);
+}
+
+function normalizePreferenceTokenWithOptions(
+  value: string,
+  options?: { stripLeadingEnglishArticle?: boolean },
+): string {
+  let normalized = normalizePreferenceText(value)
+    .replace(/^[“"'`‘’.]+|[”"'`‘’.。！!？?，,；;:：]+$/gu, "")
+    .trim();
+
+  if (options?.stripLeadingEnglishArticle) {
+    normalized = normalized.replace(LEADING_ENGLISH_ARTICLE_RE, "");
+  }
+
+  return normalized
+    .replace(/\s+/g, "")
+    .toLowerCase();
+}
+
+function splitPreferenceItems(
+  rawItems: string,
+  options?: { stripLeadingEnglishArticle?: boolean },
+): string[] {
+  const trimmed = rawItems.split(PREFERENCE_CLAUSE_STOP_RE)[0] || rawItems;
+  return trimmed
+    .split(PREFERENCE_SPLIT_RE)
+    .map((item) => normalizePreferenceTokenWithOptions(item, options))
+    .filter((item) => item.length > 0);
+}
+
+export function parseBrandItemPreference(text: string): ParsedBrandItemPreference | null {
+  const normalizedText = normalizePreferenceText(text);
+
+  for (const pattern of BRAND_ITEM_PREFERENCE_PATTERNS) {
+    const match = normalizedText.match(pattern);
+    if (!match?.groups) continue;
+
+    const brand = normalizePreferenceToken(match.groups.brand || "");
+    const items = splitPreferenceItems(match.groups.items || "", {
+      // Strip leading "the/a/an" from English item names so
+      // "the Big Mac" and "Big Mac" land on the same atomic slot.
+      stripLeadingEnglishArticle: pattern === BRAND_ITEM_PREFERENCE_PATTERNS[1],
+    });
+    if (!brand || items.length === 0) continue;
+
+    return {
+      brand,
+      items,
+      aggregate: items.length > 1,
+    };
+  }
+
+  return null;
+}
+
+export function inferAtomicBrandItemPreferenceSlot(text: string): AtomicBrandItemPreferenceSlot | null {
+  const parsed = parseBrandItemPreference(text);
+  if (!parsed || parsed.aggregate || parsed.items.length !== 1) {
+    return null;
+  }
+
+  return {
+    type: "brand-item",
+    brand: parsed.brand,
+    item: parsed.items[0],
+  };
+}
+
+export function inferReplyStylePreferenceSlot(text: string): ReplyStylePreferenceSlot | null {
+  const normalizedText = normalizePreferenceText(text);
+  const traits = REPLY_STYLE_TRAIT_PATTERNS
+    .filter(({ pattern }) => pattern.test(normalizedText))
+    .map(({ key }) => key);
+
+  if (traits.length === 0) {
+    return null;
+  }
+
+  const hasContext = REPLY_STYLE_CONTEXT_RE.test(normalizedText);
+  const hasPreferenceCue = REPLY_STYLE_PREFERENCE_CUE_RE.test(normalizedText);
+  if (!hasContext && (!hasPreferenceCue || traits.length < 2)) {
+    return null;
+  }
+
+  return {
+    type: "reply-style",
+    traits: Array.from(new Set(traits)).sort(),
+  };
+}
+
+function normalizeToolToken(value: string): string {
+  const normalized = normalizePreferenceToken(value);
+  return TOOL_ALIAS_MAP[normalized] || normalized;
+}
+
+function isKnownToolToken(value: string): boolean {
+  return Boolean(value && (TOOL_ALIAS_MAP[value] || Object.values(TOOL_ALIAS_MAP).includes(value as any)));
+}
+
+export function inferToolChoicePreferenceSlot(text: string): ToolChoicePreferenceSlot | null {
+  const normalizedText = normalizePreferenceText(text);
+
+  for (const pattern of TOOL_CHOICE_PREFERENCE_PATTERNS) {
+    const match = normalizedText.match(pattern);
+    if (!match?.groups) continue;
+
+    const preferredTool = normalizeToolToken(match.groups.preferred || "");
+    const avoidedTool = normalizeToolToken(match.groups.avoided || "");
+    if (!preferredTool || !avoidedTool || preferredTool === avoidedTool) continue;
+    if (!isKnownToolToken(preferredTool) || !isKnownToolToken(avoidedTool)) continue;
+
+    return {
+      type: "tool-choice",
+      preferredTool,
+      avoidedTool,
+    };
+  }
+
+  return null;
+}
+
+export function inferPreferenceSlot(text: string): PreferenceSlot | null {
+  return inferAtomicBrandItemPreferenceSlot(text)
+    || inferReplyStylePreferenceSlot(text)
+    || inferToolChoicePreferenceSlot(text);
+}
+
+export function samePreferenceSlot(
+  left: PreferenceSlot | null,
+  right: PreferenceSlot | null,
+): boolean {
+  if (!left || !right || left.type !== right.type) {
+    return false;
+  }
+
+  if (left.type === "brand-item" && right.type === "brand-item") {
+    return left.brand === right.brand && left.item === right.item;
+  }
+
+  if (left.type === "reply-style" && right.type === "reply-style") {
+    return left.traits.length === right.traits.length &&
+      left.traits.every((trait, index) => trait === right.traits[index]);
+  }
+
+  if (left.type === "tool-choice" && right.type === "tool-choice") {
+    return left.preferredTool === right.preferredTool &&
+      left.avoidedTool === right.avoidedTool;
+  }
+
+  return false;
+}

package/src/prospective-memory.ts

@@ -0,0 +1,198 @@
+/**
+ * Prospective Memory — Tier 3.4
+ *
+ * "Remind me about Y next time X comes up"
+ *
+ * Stores reminders as pattern memories with special `prospective` metadata.
+ * During retrieval, pending triggers are checked against the query.
+ * When a trigger fires, the reminder is injected into context.
+ *
+ * Data model: stored as category="patterns" with metadata.prospective = {
+ *   trigger, action, status, createdAt, firedAt?, expiresAt?
+ * }
+ */
+
+import type { MemoryStore, MemoryEntry } from "./store.js";
+import type { Embedder } from "./embedder.js";
+import { logInfo } from "./stderr-log.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface ProspectiveMetadata {
+  trigger: string;
+  action: string;
+  status: "pending" | "fired" | "expired";
+  createdAt: string;
+  firedAt?: string;
+  expiresAt?: string;
+}
+
+export interface Reminder {
+  entryId: string;
+  trigger: string;
+  action: string;
+}
+
+export interface SetReminderParams {
+  trigger: string;
+  action: string;
+  scope: string;
+  expiresInDays?: number;
+}
+
+// ============================================================================
+// Core Functions
+// ============================================================================
+
+/**
+ * Create a new reminder (prospective memory).
+ * Stored as a pattern entry with prospective metadata.
+ */
+export async function setReminder(
+  store: MemoryStore,
+  embedder: Embedder,
+  params: SetReminderParams,
+): Promise<MemoryEntry> {
+  const text = `[Reminder] When "${params.trigger}" comes up: ${params.action}`;
+  const vector = await embedder.embedPassage(text);
+
+  const prospective: ProspectiveMetadata = {
+    trigger: params.trigger,
+    action: params.action,
+    status: "pending",
+    createdAt: new Date().toISOString(),
+    ...(params.expiresInDays
+      ? { expiresAt: new Date(Date.now() + params.expiresInDays * 86_400_000).toISOString() }
+      : {}),
+  };
+
+  return store.store({
+    text,
+    vector,
+    category: "patterns",
+    scope: params.scope,
+    importance: 0.75,
+    metadata: JSON.stringify({
+      prospective,
+      tier: "working",
+      boundary: { layer: "durable", authority: "user" },
+    }),
+  });
+}
+
+/**
+ * Check pending reminders against a query text.
+ * Returns reminders whose trigger matches the query (simple keyword check).
+ *
+ * @param store       Memory store
+ * @param embedder    Embedder for vector search
+ * @param query       The user's query/message
+ * @param scopeFilter Scopes to check
+ * @returns Array of matching reminders (may be empty)
+ */
+export async function checkTriggers(
+  store: MemoryStore,
+  embedder: Embedder,
+  query: string,
+  scopeFilter?: string[],
+): Promise<Reminder[]> {
+  // Vector search for similar prospective memories
+  const queryVector = await embedder.embedPassage(query);
+  const candidates = await store.vectorSearch(queryVector, 10, 0.3, scopeFilter);
+
+  const now = new Date().toISOString();
+  const reminders: Reminder[] = [];
+
+  for (const candidate of candidates) {
+    const meta = parseMetadata(candidate.entry.metadata);
+    const prospective = meta.prospective as ProspectiveMetadata | undefined;
+
+    if (!prospective || prospective.status !== "pending") continue;
+
+    // Check expiration
+    if (prospective.expiresAt && prospective.expiresAt < now) {
+      // Mark as expired
+      prospective.status = "expired";
+      meta.prospective = prospective;
+      await store.update(candidate.entry.id, { metadata: JSON.stringify(meta) }, scopeFilter);
+      continue;
+    }
+
+    // Check if trigger matches query (case-insensitive keyword match)
+    if (triggerMatches(prospective.trigger, query)) {
+      reminders.push({
+        entryId: candidate.entry.id,
+        trigger: prospective.trigger,
+        action: prospective.action,
+      });
+    }
+  }
+
+  return reminders;
+}
+
+/**
+ * Fire a reminder — mark it as fired and return the action text.
+ */
+export async function fireReminder(
+  store: MemoryStore,
+  entryId: string,
+  scopeFilter?: string[],
+): Promise<string | null> {
+  const entry = await store.getById(entryId);
+  if (!entry) return null;
+
+  const meta = parseMetadata(entry.metadata);
+  const prospective = meta.prospective as ProspectiveMetadata | undefined;
+  if (!prospective || prospective.status !== "pending") return null;
+
+  prospective.status = "fired";
+  prospective.firedAt = new Date().toISOString();
+  meta.prospective = prospective;
+
+  await store.update(entryId, { metadata: JSON.stringify(meta) }, scopeFilter);
+
+  logInfo(`[INFO] Reminder fired: "${prospective.trigger}" → ${prospective.action}`);
+
+  return prospective.action;
+}
+
+/**
+ * Format fired reminders for injection into context.
+ */
+export function formatReminders(reminders: Reminder[]): string[] {
+  return reminders.map(r =>
+    `[Reminder] Triggered by "${r.trigger}": ${r.action}`
+  );
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Check if a trigger string matches a query.
+ * Uses case-insensitive keyword matching with word boundary awareness.
+ */
+function triggerMatches(trigger: string, query: string): boolean {
+  const triggerLower = trigger.toLowerCase();
+  const queryLower = query.toLowerCase();
+
+  // Split trigger into keywords
+  const keywords = triggerLower.split(/\s+/).filter(w => w.length >= 2);
+
+  if (keywords.length === 0) return false;
+
+  // All keywords must appear in query
+  return keywords.every(kw => queryLower.includes(kw));
+}
+
+function parseMetadata(raw?: string): Record<string, unknown> {
+  try {
+    return JSON.parse(raw || "{}") as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}