recallnest 1.4.1 → 2.2.1

package/src/preference-slots.ts

@@ -92,10 +92,17 @@ export interface ToolChoicePreferenceSlot {
   avoidedTool: string;
 }
 
+export interface ImplicitUsagePreferenceSlot {
+  type: "implicit-usage";
+  /** Normalized subject: the tool, product, or activity mentioned */
+  subject: string;
+}
+
 export type PreferenceSlot =
   | AtomicBrandItemPreferenceSlot
   | ReplyStylePreferenceSlot
-  | ToolChoicePreferenceSlot;
+  | ToolChoicePreferenceSlot
+  | ImplicitUsagePreferenceSlot;
 
 function normalizePreferenceText(value: string): string {
   return value
@@ -227,10 +234,62 @@ export function inferToolChoicePreferenceSlot(text: string): ToolChoicePreferenc
   return null;
 }
 
+// ---------------------------------------------------------------------------
+// Implicit usage preference detection
+// Captures "I use X", "I have a X", "I enjoy X", "I'm learning X" etc.
+// These are indirect signals — user never says "I prefer X" explicitly.
+// ---------------------------------------------------------------------------
+
+const IMPLICIT_USAGE_EN_PATTERNS: RegExp[] = [
+  // "I/User use(s)/using X for..." or at end of sentence
+  /\b(?:i|user)\s+(?:use[sd]?|using|am\s+using|have\s+been\s+using|work[s]?\s+with)\s+(?<subject>[A-Za-z][A-Za-z0-9\s.+#\-']{1,40}?)\s*(?=\s+(?:for|to|in|at|on|as|which|because|since)\b|[,.:;!?]|$)/i,
+  // "I/User have/own a X (camera|phone|...)" or at end
+  /\b(?:i|user)\s+(?:have|has|own[s]?|bought|got)\s+(?:a |an |the )?(?<subject>[A-Za-z][A-Za-z0-9\s.+#\-']{1,40}?)\s*(?=\s+(?:camera|phone|laptop|computer|tablet|watch|car|bike|guitar|piano|keyboard|headphones|monitor|setup|kit|device)\b|[,.:;!?]|$)/i,
+  // "I/User enjoy(s)/love(s) (to use) X" (no "from" — avoids brand-item overlap)
+  /\b(?:i|user)\s+(?:enjoy[s]?|love[s]?|really\s+like[s]?)\s+(?:to\s+(?:use\s+)?)?(?<subject>[A-Za-z][A-Za-z0-9\s.+#\-']{1,40}?)\s*(?=[,.:;!?]|$)/i,
+  // "I'm learning/studying X"
+  /\b(?:i'm|i\s+am|user\s+is)\s+(?:learning|studying|interested\s+in|passionate\s+about)\s+(?<subject>[A-Za-z][A-Za-z0-9\s.+#\-']{1,40}?)\s*(?=[,.:;!?]|$)/i,
+];
+
+const IMPLICIT_USAGE_CN_PATTERNS: RegExp[] = [
+  // "我用/在用 X" (lookahead stops at verb complements or punctuation; no \b for CJK)
+  /(?:我|用户)(?:在)?(?:用|使用)\s*(?<subject>[\p{Script=Han}A-Za-z0-9][\p{Script=Han}A-Za-z0-9\s.+#\-]{0,30}?)(?=\s*(?:来|做|进行|处理|开发|编辑)|[，。！？,.:;!?]|$)/u,
+  // "我有/买了 X"
+  /(?:我|用户)(?:有|买了|入了)\s*(?:一[个台部套])?(?<subject>[\p{Script=Han}A-Za-z0-9][\p{Script=Han}A-Za-z0-9\s.+#\-]{0,30}?)(?=[，。！？,.:;!?]|$)/u,
+  // "我喜欢做 X" / "我爱 X" (activity, not brand-item — no "的" connector)
+  /(?:我|用户)(?:很)?(?:喜欢|爱|享受)\s*(?:做|玩|学|用)\s*(?<subject>[\p{Script=Han}A-Za-z0-9][\p{Script=Han}A-Za-z0-9\s.+#\-]{0,30}?)(?=[，。！？,.:;!?]|$)/u,
+  // "我在学/研究 X"
+  /(?:我|用户)(?:在学|正在学|在研究)\s*(?<subject>[\p{Script=Han}A-Za-z0-9][\p{Script=Han}A-Za-z0-9\s.+#\-]{0,30}?)(?=[，。！？,.:;!?]|$)/u,
+];
+
+/** Minimum normalized subject length to avoid false positives like "I use it" */
+const IMPLICIT_USAGE_MIN_SUBJECT_LEN = 2;
+
+export function inferImplicitUsageSlot(text: string): ImplicitUsagePreferenceSlot | null {
+  const normalizedText = normalizePreferenceText(text);
+
+  for (const pattern of [...IMPLICIT_USAGE_EN_PATTERNS, ...IMPLICIT_USAGE_CN_PATTERNS]) {
+    const match = normalizedText.match(pattern);
+    if (!match?.groups?.subject) continue;
+
+    const subject = normalizePreferenceToken(match.groups.subject);
+    if (subject.length < IMPLICIT_USAGE_MIN_SUBJECT_LEN) continue;
+
+    return {
+      type: "implicit-usage",
+      subject,
+    };
+  }
+
+  return null;
+}
+
 export function inferPreferenceSlot(text: string): PreferenceSlot | null {
+  // Explicit patterns take priority over implicit detection
   return inferAtomicBrandItemPreferenceSlot(text)
     || inferReplyStylePreferenceSlot(text)
-    || inferToolChoicePreferenceSlot(text);
+    || inferToolChoicePreferenceSlot(text)
+    || inferImplicitUsageSlot(text);
 }
 
 export function samePreferenceSlot(
@@ -255,5 +314,9 @@ export function samePreferenceSlot(
       left.avoidedTool === right.avoidedTool;
   }
 
+  if (left.type === "implicit-usage" && right.type === "implicit-usage") {
+    return left.subject === right.subject;
+  }
+
   return false;
 }

package/src/prospective-memory.ts

@@ -15,6 +15,9 @@
 import type { MemoryStore, MemoryEntry } from "./store.js";
 import type { Embedder } from "./embedder.js";
 import { logInfo } from "./stderr-log.js";
+import type { ScoredPrediction, PredictionContext } from "./prediction-engine.js";
+import { collectSignals, scorePredictions } from "./prediction-engine.js";
+import { isPredictiveMemoryEnabled } from "./memory-schema.js";
 
 // ============================================================================
 // Types
@@ -27,6 +30,16 @@ export interface ProspectiveMetadata {
   createdAt: string;
   firedAt?: string;
   expiresAt?: string;
+  /** HP-predictive: "explicit" = user-created, "predicted" = heuristic-generated */
+  source?: "explicit" | "predicted";
+  /** HP-predictive: confidence score 0-1 for predicted reminders */
+  confidence?: number;
+  /** HP-predictive: evidence strings explaining why this was predicted */
+  evidence?: string[];
+  /** HP-predictive: last time this prediction was surfaced to the user */
+  lastSuggestedAt?: string;
+  /** HP-predictive: when the user accepted/acted on this predicted reminder */
+  acceptedAt?: string;
 }
 
 export interface Reminder {
@@ -42,6 +55,20 @@ export interface SetReminderParams {
   expiresInDays?: number;
 }
 
+export interface SuggestedReminder {
+  entryId: string;
+  trigger: string;
+  action: string;
+  confidence: number;
+  evidence: string[];
+}
+
+/** Default expiry for predicted reminders: 7 days */
+const PREDICTED_REMINDER_EXPIRY_DAYS = 7;
+
+/** Confidence penalty per ignored suggestion cycle */
+const IGNORE_CONFIDENCE_PENALTY = 0.15;
+
 // ============================================================================
 // Core Functions
 // ============================================================================
@@ -62,6 +89,7 @@ export async function setReminder(
     trigger: params.trigger,
     action: params.action,
     status: "pending",
+    source: "explicit",
     createdAt: new Date().toISOString(),
     ...(params.expiresInDays
       ? { expiresAt: new Date(Date.now() + params.expiresInDays * 86_400_000).toISOString() }
@@ -168,6 +196,193 @@ export function formatReminders(reminders: Reminder[]): string[] {
   );
 }
 
+// ============================================================================
+// HP-predictive: Predicted Reminders
+// ============================================================================
+
+/**
+ * Generate predicted reminders from behavioral signals.
+ * Deduplicates against existing pending reminders via vector similarity.
+ * Stores new predictions as ephemeral entries with 7-day expiry.
+ *
+ * @returns Array of suggested reminders to surface to the user
+ */
+export async function suggestPredictedReminders(
+  store: MemoryStore,
+  embedder: Embedder,
+  predictionContext: PredictionContext,
+  scope: string,
+): Promise<SuggestedReminder[]> {
+  if (!isPredictiveMemoryEnabled()) return [];
+
+  // 1. Collect and score signals
+  const signals = collectSignals(predictionContext);
+  const predictions = scorePredictions(signals);
+
+  if (predictions.length === 0) return [];
+
+  const suggested: SuggestedReminder[] = [];
+  const now = predictionContext.now ?? new Date();
+
+  for (const prediction of predictions) {
+    // 2. Deduplicate: vector search for similar existing reminders
+    const isDuplicate = await isDuplicateReminder(store, embedder, prediction, [scope]);
+    if (isDuplicate) continue;
+
+    // 3. Store as predicted + ephemeral reminder with 7-day expiry
+    const text = `[Predicted Reminder] ${prediction.action}`;
+    const vector = await embedder.embedPassage(text);
+
+    const prospective: ProspectiveMetadata = {
+      trigger: prediction.trigger,
+      action: prediction.action,
+      status: "pending",
+      source: "predicted",
+      confidence: prediction.confidence,
+      evidence: prediction.evidence,
+      lastSuggestedAt: now.toISOString(),
+      createdAt: now.toISOString(),
+      expiresAt: new Date(now.getTime() + PREDICTED_REMINDER_EXPIRY_DAYS * 86_400_000).toISOString(),
+    };
+
+    const entry = await store.store({
+      text,
+      vector,
+      category: "patterns",
+      scope,
+      importance: 0.5, // Lower than explicit reminders (0.75)
+      metadata: JSON.stringify({
+        prospective,
+        tier: "working",
+        privacyTier: "ephemeral",
+        boundary: { layer: "ephemeral", authority: "system" },
+      }),
+    });
+
+    suggested.push({
+      entryId: entry.id,
+      trigger: prediction.trigger,
+      action: prediction.action,
+      confidence: prediction.confidence,
+      evidence: prediction.evidence,
+    });
+
+    logInfo(`[INFO] Predicted reminder stored: "${prediction.trigger}" (confidence: ${prediction.confidence})`);
+  }
+
+  return suggested;
+}
+
+/**
+ * Accept a predicted reminder — upgrade it to explicit, persist as durable.
+ */
+export async function acceptPredictedReminder(
+  store: MemoryStore,
+  entryId: string,
+  scopeFilter?: string[],
+): Promise<boolean> {
+  const entry = await store.getById(entryId);
+  if (!entry) return false;
+
+  const meta = parseMetadata(entry.metadata);
+  const prospective = meta.prospective as ProspectiveMetadata | undefined;
+  if (!prospective || prospective.source !== "predicted" || prospective.status !== "pending") return false;
+
+  // Upgrade: predicted → explicit, ephemeral → durable
+  prospective.source = "explicit";
+  prospective.acceptedAt = new Date().toISOString();
+  meta.prospective = prospective;
+  meta.privacyTier = "durable";
+  if (meta.boundary && typeof meta.boundary === "object") {
+    (meta.boundary as Record<string, string>).layer = "durable";
+    (meta.boundary as Record<string, string>).authority = "user";
+  }
+
+  await store.update(entryId, {
+    metadata: JSON.stringify(meta),
+    importance: 0.75, // Upgrade to explicit-level importance
+  }, scopeFilter);
+
+  logInfo(`[INFO] Predicted reminder accepted and promoted: ${entryId}`);
+  return true;
+}
+
+/**
+ * Demote a predicted reminder — reduce confidence.
+ * If confidence drops below threshold after penalty, mark as expired.
+ */
+export async function demotePredictedReminder(
+  store: MemoryStore,
+  entryId: string,
+  scopeFilter?: string[],
+): Promise<boolean> {
+  const entry = await store.getById(entryId);
+  if (!entry) return false;
+
+  const meta = parseMetadata(entry.metadata);
+  const prospective = meta.prospective as ProspectiveMetadata | undefined;
+  if (!prospective || prospective.source !== "predicted" || prospective.status !== "pending") return false;
+
+  const newConfidence = Math.max(0, (prospective.confidence ?? 0) - IGNORE_CONFIDENCE_PENALTY);
+
+  if (newConfidence < 0.6) {
+    // Below threshold — expire it
+    prospective.status = "expired";
+    prospective.confidence = newConfidence;
+    meta.prospective = prospective;
+    await store.update(entryId, { metadata: JSON.stringify(meta) }, scopeFilter);
+    logInfo(`[INFO] Predicted reminder demoted below threshold and expired: ${entryId}`);
+  } else {
+    // Still above threshold — just lower confidence
+    prospective.confidence = newConfidence;
+    prospective.lastSuggestedAt = new Date().toISOString();
+    meta.prospective = prospective;
+    await store.update(entryId, { metadata: JSON.stringify(meta) }, scopeFilter);
+    logInfo(`[INFO] Predicted reminder demoted: ${entryId} (new confidence: ${newConfidence})`);
+  }
+
+  return true;
+}
+
+/**
+ * Format suggested reminders for output in search_memory results.
+ */
+export function formatSuggestedReminders(suggestions: SuggestedReminder[]): string {
+  if (suggestions.length === 0) return "";
+
+  const lines = suggestions.map(s => {
+    const confidenceLabel = s.confidence >= 0.8 ? "high" : s.confidence >= 0.7 ? "medium" : "low";
+    return `- [${confidenceLabel}] ${s.action}\n  Evidence: ${s.evidence.join("; ")}`;
+  });
+
+  return "\n\n--- Suggested Reminders ---\n" + lines.join("\n");
+}
+
+/**
+ * Check if a prediction duplicates an existing pending reminder.
+ * Uses vector similarity — threshold 0.75 = likely duplicate.
+ */
+async function isDuplicateReminder(
+  store: MemoryStore,
+  embedder: Embedder,
+  prediction: ScoredPrediction,
+  scopeFilter: string[],
+): Promise<boolean> {
+  const searchText = `${prediction.trigger} ${prediction.action}`;
+  const vector = await embedder.embedPassage(searchText);
+  const candidates = await store.vectorSearch(vector, 5, 0.75, scopeFilter);
+
+  for (const candidate of candidates) {
+    const meta = parseMetadata(candidate.entry.metadata);
+    const prospective = meta.prospective as ProspectiveMetadata | undefined;
+    if (prospective && prospective.status === "pending") {
+      return true; // Found an existing pending reminder that's similar enough
+    }
+  }
+
+  return false;
+}
+
 // ============================================================================
 // Helpers
 // ============================================================================

package/src/query-expander.ts

@@ -7,8 +7,11 @@
  *       MAX_EXPANSION_TERMS cap to prevent query bloat hurting BM25 precision.
  *       Structured synonym entries separating CN (substring) from EN (word-boundary).
  * v1.2: Entity resolution pre-pass normalizes aliases before synonym expansion.
+ * v1.3: P0.3 — User-level alias-map (data/alias-map.json) for short query expansion.
  */
 
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
 import { resolveQueryEntities } from "./entity-resolver.js";
 
 interface SynonymEntry {
@@ -59,6 +62,56 @@ const SYNONYM_MAP: SynonymEntry[] = [
 /** Maximum expansion terms to prevent query bloat hurting BM25 precision */
 const MAX_EXPANSION_TERMS = 5;
 
+// ============================================================================
+// P0.3: User-level alias-map for short query expansion
+// ============================================================================
+
+/**
+ * Alias map entry: a short trigger → expansion terms.
+ * Loaded from data/alias-map.json on first use (lazy, cached).
+ */
+export interface AliasEntry {
+  trigger: string;
+  expansions: string[];
+}
+
+let aliasMapCache: AliasEntry[] | null = null;
+let aliasMapPath: string | null = null;
+
+/** Override the alias-map file path (for testing). */
+export function setAliasMapPath(path: string): void {
+  aliasMapPath = path;
+  aliasMapCache = null; // force reload
+}
+
+/** Reset alias-map cache (for testing). */
+export function resetAliasMapCache(): void {
+  aliasMapCache = null;
+}
+
+function loadAliasMap(): AliasEntry[] {
+  if (aliasMapCache !== null) return aliasMapCache;
+  const filePath = aliasMapPath ?? join(process.cwd(), "data", "alias-map.json");
+  try {
+    if (existsSync(filePath)) {
+      const raw = JSON.parse(readFileSync(filePath, "utf-8"));
+      if (Array.isArray(raw)) {
+        aliasMapCache = raw.filter(
+          (e: unknown): e is AliasEntry =>
+            typeof e === "object" && e !== null &&
+            typeof (e as AliasEntry).trigger === "string" &&
+            Array.isArray((e as AliasEntry).expansions),
+        );
+        return aliasMapCache;
+      }
+    }
+  } catch {
+    // Silent — alias map is optional
+  }
+  aliasMapCache = [];
+  return aliasMapCache;
+}
+
 /**
  * Expand a query by appending synonym terms from the dictionary.
  * Returns the original query with additional terms appended.
@@ -72,6 +125,7 @@ export function expandQuery(query: string): string {
   const lower = resolved.toLowerCase();
   const additions = new Set<string>();
 
+  // Static synonym map (built-in)
   for (const entry of SYNONYM_MAP) {
     // Chinese triggers: substring match (CJK has no word boundaries)
     const cnMatch = entry.cn.some(t => lower.includes(t.toLowerCase()));
@@ -90,6 +144,19 @@ export function expandQuery(query: string): string {
     }
   }
 
+  // P0.3: User alias-map (data/alias-map.json) — short triggers → expansions
+  const aliasMap = loadAliasMap();
+  for (const alias of aliasMap) {
+    const triggerLower = alias.trigger.toLowerCase();
+    if (lower.includes(triggerLower)) {
+      for (const exp of alias.expansions) {
+        if (!lower.includes(exp.toLowerCase())) {
+          additions.add(exp);
+        }
+      }
+    }
+  }
+
   if (additions.size === 0) return resolved;
 
   // Cap expansion terms to prevent query bloat

package/src/recall-governor.ts

@@ -0,0 +1,183 @@
+/**
+ * LME-7: Recall Governor — auto-recall 治理层
+ *
+ * 在 HybridRetriever 返回结果后、auto-recall 返回给调用方之前，
+ * 对检索结果施加 4 层治理：
+ *   1. Query 截断 — 超长 query 截到 maxQueryChars（省 embedding 成本）
+ *   2. 状态过滤 — 排除 archived/superseded 记忆（evolution 兜底）
+ *   3. 预算控制 — 总字符上限 + 条目数上限
+ *   4. 会话去重 — 同一 session 内不重复注入同一条记忆
+ */
+
+import { isActiveMemory } from "./memory-evolution.js";
+import type { RetrievalResult } from "./retriever.js";
+import { logInfo } from "./stderr-log.js";
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+export interface GovernorConfig {
+  /** Max query length before truncation (default: 1000) */
+  maxQueryChars: number;
+  /** Max total characters across all injected memories (default: 8000) */
+  charBudget: number;
+  /** Max number of memories to inject (default: 10) */
+  maxItems: number;
+}
+
+const DEFAULT_CONFIG: GovernorConfig = {
+  maxQueryChars: 1000,
+  charBudget: 8000,
+  maxItems: 10,
+};
+
+export function resolveGovernorConfig(
+  overrides?: Partial<GovernorConfig>,
+): GovernorConfig {
+  return { ...DEFAULT_CONFIG, ...overrides };
+}
+
+// ============================================================================
+// Governor Session — tracks per-session dedup state
+// ============================================================================
+
+export class GovernorSession {
+  private readonly injectedIds = new Set<string>();
+
+  /** Mark a memory ID as already injected in this session. */
+  markInjected(id: string): void {
+    this.injectedIds.add(id);
+  }
+
+  /** Check whether a memory ID was already injected. */
+  wasInjected(id: string): boolean {
+    return this.injectedIds.has(id);
+  }
+
+  /** Bulk-mark results after governing. */
+  markAll(results: RetrievalResult[]): void {
+    for (const r of results) {
+      this.injectedIds.add(r.entry.id);
+    }
+  }
+
+  /** Number of unique IDs tracked so far. */
+  get size(): number {
+    return this.injectedIds.size;
+  }
+}
+
+// ============================================================================
+// Layer 1: Query Truncation
+// ============================================================================
+
+export function truncateQuery(
+  query: string,
+  maxChars: number,
+): string {
+  if (query.length <= maxChars) return query;
+  logInfo(`[recall-governor] query truncated: ${query.length} → ${maxChars} chars`);
+  return query.slice(0, maxChars);
+}
+
+// ============================================================================
+// Layer 2: Evolution State Filter
+// ============================================================================
+
+function filterByEvolutionState(results: RetrievalResult[]): RetrievalResult[] {
+  const before = results.length;
+  const filtered = results.filter((r) => isActiveMemory(r.entry.metadata));
+  const dropped = before - filtered.length;
+  if (dropped > 0) {
+    logInfo(`[recall-governor] evolution filter dropped ${dropped}/${before} inactive memories`);
+  }
+  return filtered;
+}
+
+// ============================================================================
+// Layer 3: Budget Control
+// ============================================================================
+
+function applyBudget(
+  results: RetrievalResult[],
+  config: GovernorConfig,
+): RetrievalResult[] {
+  const kept: RetrievalResult[] = [];
+  let totalChars = 0;
+
+  for (const r of results) {
+    if (kept.length >= config.maxItems) break;
+    const textLen = r.entry.text.length;
+    if (totalChars + textLen > config.charBudget && kept.length > 0) break;
+    // Always allow at least one result even if it exceeds budget
+    kept.push(r);
+    totalChars += textLen;
+  }
+
+  if (kept.length < results.length) {
+    logInfo(
+      `[recall-governor] budget control: ${kept.length}/${results.length} kept ` +
+      `(${totalChars} chars, limit ${config.charBudget})`,
+    );
+  }
+  return kept;
+}
+
+// ============================================================================
+// Layer 4: Session Dedup
+// ============================================================================
+
+function deduplicateBySession(
+  results: RetrievalResult[],
+  session: GovernorSession | undefined,
+): RetrievalResult[] {
+  if (!session) return results;
+
+  const before = results.length;
+  const deduped = results.filter((r) => !session.wasInjected(r.entry.id));
+  const dropped = before - deduped.length;
+  if (dropped > 0) {
+    logInfo(`[recall-governor] session dedup dropped ${dropped}/${before} already-injected memories`);
+  }
+  return deduped;
+}
+
+// ============================================================================
+// Public API — compose all layers
+// ============================================================================
+
+/**
+ * Run the full governance pipeline on retrieval results.
+ * Call this after tier-aware filtering in auto-recall, before returning.
+ *
+ * @param results - Pre-sorted retrieval results (score descending)
+ * @param session - Optional GovernorSession for cross-call dedup
+ * @param config  - Optional config overrides
+ * @returns Governed results, ready for injection
+ */
+export function governResults(
+  results: RetrievalResult[],
+  session?: GovernorSession,
+  config?: Partial<GovernorConfig>,
+): RetrievalResult[] {
+  if (results.length === 0) return results;
+
+  const cfg = resolveGovernorConfig(config);
+
+  // Layer 2: evolution state filter
+  let governed = filterByEvolutionState(results);
+
+  // Layer 3: session dedup (before budget so deduped items don't waste budget slots)
+  governed = deduplicateBySession(governed, session);
+
+  // Layer 4: budget control
+  governed = applyBudget(governed, cfg);
+
+  // Mark newly injected IDs for future dedup
+  if (session) {
+    session.markAll(governed);
+  }
+
+  return governed;
+}