flint-agent 1.14.0

package/src/memory/facts.js

@@ -0,0 +1,181 @@
+// Facts memory — Layer 4 of memory architecture.
+//
+// User/project facts explicitly stated or extracted from conversation.
+// "We use yarn not npm", "project runs on port 8080", "DB is PostgreSQL".
+// Injected into system prompt so agent applies them without being reminded.
+//
+// Internal task reference removed.
+
+import { insertFact, getAllFacts, deleteFact, indexEntry, searchFts, setFactPinned } from "./sqlite-store.js";
+
+const MAX_FACTS = 100;
+
+/**
+ * Add a fact.
+ * @param {string} content — the fact text
+ * @param {string} category — general|project|preference|environment
+ * @param {string} source — "user" or "agent"
+ * @param {number} confidence — 0.0 to 1.0
+ * @returns {string} fact id
+ */
+export function addFact(content, category = "general", source = "agent", confidence = 1.0, project = null) {
+  if (!content || !content.trim()) return null;
+
+  // Dedupe — don't add if very similar fact exists (any project)
+  const existing = searchFts(content.slice(0, 50), { layer: "facts", limit: 3 });
+  for (const e of existing) {
+    if (e.text && textSimilarity(e.text, content) > 0.8) {
+      return null; // too similar, skip
+    }
+  }
+
+  // Eviction: never evict pinned facts. If cap reached and no unpinned
+  // fact exists to evict, silently reject the new fact (prevents the cap
+  // from being exceeded when all slots are curated).
+  const all = getAllFacts();
+  if (all.length >= MAX_FACTS) {
+    // getAllFacts returns ORDER BY created_at DESC, so last element is oldest
+    const oldestUnpinned = [...all].reverse().find(f => !f.pinned);
+    if (!oldestUnpinned) return null; // all slots pinned — refuse new fact
+    deleteFact(oldestUnpinned.id);
+  }
+
+  const now = new Date();
+  // A random tail: two facts added in the same millisecond got the same id,
+  // and the second overwrote the first without a word.
+  const id = `fact-${now.getTime().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+  insertFact({ id, category, content: content.trim(), source, confidence, project, pinned: 0 });
+  indexEntry("facts", id, content.trim());
+  return id;
+}
+
+/**
+ * Remove a fact by id.
+ */
+export function removeFact(id) {
+  deleteFact(id);
+}
+
+/**
+ * Pin a fact — it will never be LRU-evicted. Use for durable knowledge
+ * (user preferences, project metadata) that must survive heavy write
+ * sessions (benchmarks, bulk agent work).
+ */
+export function pinFact(id) {
+  setFactPinned(id, true);
+}
+
+/**
+ * Unpin a fact — it becomes eligible for LRU eviction again.
+ */
+export function unpinFact(id) {
+  setFactPinned(id, false);
+}
+
+/**
+ * Get facts, optionally filtered by category and/or project scope.
+ * @param {string|null} category — filter by category, null = all
+ * @param {string|null|undefined} project — project scope:
+ *   undefined/null = all facts (no scope filter)
+ *   "" (empty string) = global only (project IS NULL)
+ *   "name" = project "name" + global facts (union)
+ */
+export function getFacts(category = null, project = null) {
+  const all = project === null ? getAllFacts() : getAllFacts({ project });
+  if (category) return all.filter(f => f.category === category);
+  return all;
+}
+
+/**
+ * Format facts as system-prompt-ready block. Groups by category.
+ * Uses the given project scope: global facts always included; project-scoped
+ * only when currentProject matches. If currentProject is null, only globals.
+ *
+ * @param {number} maxTokens — approximate token budget
+ * @param {string|null} currentProject — project name or null
+ */
+export function formatForPrompt(maxTokens = 500, currentProject = null) {
+  const all = currentProject
+    ? getAllFacts({ project: currentProject })  // scoped + global union
+    : getAllFacts({ project: "" });              // global only
+  if (!all.length) return "";
+
+  const groups = {};
+  for (const f of all) {
+    const cat = f.category || "general";
+    if (!groups[cat]) groups[cat] = [];
+    groups[cat].push(f);
+  }
+
+  const scopeLabel = currentProject ? `(scope: ${currentProject} + global)` : "(scope: global)";
+  const lines = [`Known facts about user and project ${scopeLabel}:`];
+  let tokens = 0;
+  for (const [cat, facts] of Object.entries(groups)) {
+    lines.push(`  [${cat}]`);
+    for (const f of facts) {
+      const marker = f.project ? `§[${f.project}]` : "§";
+      const line = `    ${marker} ${f.content}`;
+      tokens += line.split(/\s+/).length;
+      if (tokens > maxTokens) break;
+      lines.push(line);
+    }
+    if (tokens > maxTokens) break;
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Extract facts from a conversation turn.
+ * Heuristic: look for patterns like "we use X", "our project is Y",
+ * "I prefer Z", "the server runs on W".
+ * @param {string} userMessage
+ * @returns {Array<{content, category, confidence}>}
+ */
+/**
+ * Extract facts from a user message. Uses the LLM-based extractor from
+ * extract-facts.js (async, semantic). No regex, no hardcoded patterns —
+ * the LLM decides what's a durable fact.
+ *
+ * Gated: only calls LLM for messages >= 20 chars that look like disclosures
+ * (contain a pronoun-like signal). Short chit-chat ("ok", "yes", "done")
+ * never triggers a call.
+ *
+ * @param {string} userMessage
+ * @returns {Promise<Array<{content, category, confidence}>>}
+ */
+export async function extractFacts(userMessage) {
+  if (!userMessage || userMessage.length < 20) return [];
+  // Cheap language-neutral pre-filter — skip if message is clearly a question
+  // or a bare command. Real disclosures are declarative statements.
+  // Previously this used RU+EN keyword regex which was biased against
+  // Ukrainian / German / Chinese users. Replaced 2026-04-19.
+  const trimmed = userMessage.trim();
+  // Skip pure questions (ends with ?)
+  if (/\?\s*$/.test(trimmed)) return [];
+  // Skip very short declarations (covered by length check above, but also
+  // short imperative commands like "read X" or "open Y")
+  const wordCount = trimmed.split(/\s+/).length;
+  if (wordCount < 5) return [];
+
+  try {
+    const { extractFacts: extractViaLlm } = await import("./extract-facts.js");
+    // extract-facts.js expects messages; wrap the single user message
+    const out = await extractViaLlm([{ role: "user", content: userMessage }]);
+    if (!Array.isArray(out)) return [];
+    return out.map(f => ({ content: f.content, category: f.category || "general", confidence: 0.8 }));
+  } catch {
+    return [];
+  }
+}
+
+// Simple word-overlap similarity
+function textSimilarity(a, b) {
+  const wa = new Set(a.toLowerCase().split(/\s+/));
+  const wb = new Set(b.toLowerCase().split(/\s+/));
+  let inter = 0;
+  for (const w of wa) if (wb.has(w)) inter++;
+  const union = wa.size + wb.size - inter;
+  return union === 0 ? 0 : inter / union;
+}
+
+export const __internal = { MAX_FACTS };

package/src/memory/inbox.js

@@ -0,0 +1,63 @@
+// Notification inbox — queues reminders, messages, events
+// Agent sees count in system prompt, reads with check_inbox tool
+// Does NOT interrupt current task focus
+
+let _items = [];  // [{ id, type, content, from, ts }]
+let _nextId = 1;
+
+/**
+ * Add a notification to the inbox.
+ * @param {"reminder"|"message"|"event"} type
+ * @param {string} content
+ * @param {string} [from] - source (e.g. "schedule", "api", "cron")
+ */
+export function pushInbox(type, content, from = "") {
+  _items.push({
+    id: _nextId++,
+    type,
+    content,
+    from,
+    ts: new Date().toISOString(),
+    read: false,
+  });
+}
+
+/**
+ * Get count of unread notifications.
+ */
+export function unreadCount() {
+  return _items.filter((i) => !i.read).length;
+}
+
+/**
+ * Get all unread notifications and mark them as read.
+ */
+export function readInbox() {
+  const unread = _items.filter((i) => !i.read);
+  for (const item of unread) {
+    item.read = true;
+  }
+  return unread;
+}
+
+/**
+ * Get all items (read + unread), last N.
+ */
+export function allInbox(limit = 50) {
+  return _items.slice(-limit);
+}
+
+/**
+ * Format inbox summary for system prompt injection.
+ * Returns null if no unread notifications.
+ */
+export function inboxPromptHint() {
+  const count = unreadCount();
+  if (count === 0) return null;
+  const types = {};
+  for (const item of _items.filter((i) => !i.read)) {
+    types[item.type] = (types[item.type] || 0) + 1;
+  }
+  const parts = Object.entries(types).map(([t, n]) => `${n} ${t}${n > 1 ? "s" : ""}`);
+  return `You have ${count} unread notification${count > 1 ? "s" : ""} (${parts.join(", ")}). Use check_inbox tool to read them when you have a moment. Do NOT interrupt your current task.`;
+}

package/src/memory/markdown.js

@@ -0,0 +1,38 @@
+import { writeFileSync, existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { config } from "../config.js";
+import { loadAll, getMemoryStats } from "./store.js";
+
+const MEMORY_MD = path.join(config.projectRoot, "MEMORY.md");
+
+export function updateMemoryMd() {
+  const memories = loadAll();
+  const stats = getMemoryStats();
+  const grouped = {};
+  for (const m of memories) {
+    if (!grouped[m.category]) grouped[m.category] = [];
+    grouped[m.category].push(m);
+  }
+
+  let md = `# Agent Memory (${stats.total} entries)\n\n`;
+
+  for (const [cat, items] of Object.entries(grouped)) {
+    md += `## ${cat} (${items.length})\n`;
+    for (const m of items) {
+      const date = m.created_at?.slice(0, 10) || "unknown";
+      const stars = "*".repeat(Math.min(m.importance, 3));
+      md += `- [#${m.id}] ${date}: ${m.content} ${stars}\n`;
+    }
+    md += "\n";
+  }
+
+  md += `Last updated: ${new Date().toISOString()}\n`;
+  writeFileSync(MEMORY_MD, md, "utf-8");
+  return md;
+}
+
+export function readMemoryMdHead(lines = 50) {
+  if (!existsSync(MEMORY_MD)) return "";
+  const content = readFileSync(MEMORY_MD, "utf-8");
+  return content.split("\n").slice(0, lines).join("\n");
+}

package/src/memory/patterns.js

@@ -0,0 +1,185 @@
+// Patterns memory — Layer 2 of memory architecture.
+//
+// Records per-turn: what user request (tokenized) → which tool the agent
+// chose first. Compiles into a tool-preference table injected at session
+// start. Purpose: triplet-consistency — three paraphrases of the same
+// request should converge on the same tool.
+
+import {
+  insertPattern, getAllPatterns, migrateFromJsonl,
+  findSimilarPattern, incrementPatternSuccess, replacePatternTool, getTopPatterns,
+} from "./sqlite-store.js";
+
+// Run migration on first import (idempotent)
+try { migrateFromJsonl(); } catch {}
+
+const STOP_WORDS = new Set([
+  // English
+  "a", "an", "the", "is", "are", "was", "were", "be", "been", "being",
+  "have", "has", "had", "do", "does", "did", "will", "would", "should", "could",
+  "can", "may", "might", "i", "you", "he", "she", "it", "we", "they",
+  "my", "your", "his", "her", "its", "our", "their", "this", "that", "these", "those",
+  "to", "of", "in", "on", "at", "for", "with", "by", "from", "as", "and", "or", "but",
+  "not", "no", "if", "so", "then", "than", "when", "where", "what", "why", "how",
+  "please", "me", "some",
+]);
+
+/**
+ * Tokenize a request into lowercased, stop-word-filtered tokens.
+ * Keeps letters and digits of any script, 3+ chars only.
+ */
+export function tokenize(text) {
+  if (!text || typeof text !== "string") return [];
+  // Split on anything that is not a letter or digit, in any script
+  const raw = text.toLowerCase().split(/[^\p{L}\p{N}_]+/u);
+  const out = [];
+  const seen = new Set();
+  for (const t of raw) {
+    if (!t || t.length < 3) continue;
+    if (STOP_WORDS.has(t)) continue;
+    if (seen.has(t)) continue;
+    seen.add(t);
+    out.push(t);
+  }
+  return out;
+}
+
+/**
+ * Record a pattern with versioning support.
+ * - If similar tokens + same tool exists: increment success_count (reinforcement)
+ * - If similar tokens + different tool: replace tool (correction/versioning)
+ * - Otherwise: insert new pattern
+ * @param {{ request:string, first_tool:string, all_tools?:string[], ok?:boolean, session_id?:string }} p
+ * @returns {string|null} id or null if skipped
+ */
+export function recordPattern(p) {
+  if (!p || !p.request || !p.first_tool) return null;
+  const tokens = tokenize(p.request);
+  if (tokens.length === 0) return null;
+
+  // Check for existing similar pattern (Jaccard >= 0.5 on tokens)
+  const existing = findSimilarPattern(tokens, p.first_tool);
+  if (existing) {
+    // Same tool: reinforce
+    incrementPatternSuccess(existing.id);
+    return existing.id;
+  }
+
+  // Check if there's a pattern with same tokens but DIFFERENT tool (correction)
+  const allPatterns = getAllPatterns();
+  for (const ep of allPatterns) {
+    if (ep.first_tool === p.first_tool) continue;
+    const intersection = tokens.filter(t => (ep.tokens || []).includes(t)).length;
+    const union = new Set([...tokens, ...(ep.tokens || [])]).size;
+    if (union > 0 && intersection / union >= 0.5) {
+      // Correction: replace tool, increment version + fail_count
+      replacePatternTool(ep.id, p.first_tool, Array.isArray(p.all_tools) ? p.all_tools.slice(0, 20) : [p.first_tool]);
+      return ep.id;
+    }
+  }
+
+  // New pattern
+  const now = new Date();
+  const record = {
+    // Random tail for the same reason as facts.js: one millisecond, one id.
+    id: `p-${now.getTime().toString(36)}${Math.random().toString(36).slice(2, 6)}`,
+    ts: now.toISOString(),
+    session_id: p.session_id || "",
+    request: String(p.request).slice(0, 500),
+    tokens,
+    first_tool: p.first_tool,
+    all_tools: Array.isArray(p.all_tools) ? p.all_tools.slice(0, 20) : [p.first_tool],
+    ok: p.ok !== false,
+    success_count: 1,
+    fail_count: 0,
+    version: 1,
+  };
+  insertPattern(record);
+  return record.id;
+}
+
+export function loadAll() {
+  return getAllPatterns();
+}
+
+/**
+ * For each tool, find the tokens most predictive of that tool choice.
+ * Returns a map: tool_name → [tokens sorted by descriminating power].
+ *
+ * Method: for each (tool, token) pair, compute conditional probability
+ *   P(tool | token) = count(tool ∧ token) / count(token)
+ * Only tokens seen ≥ MIN_TOKEN_USES times are kept. Only pairs with
+ * P ≥ MIN_CONFIDENCE are kept.
+ */
+export function compilePreferences(opts = {}) {
+  const MIN_TOKEN_USES = opts.minTokenUses || 3;
+  const MIN_CONFIDENCE = opts.minConfidence || 0.6;
+  const MAX_TOKENS_PER_TOOL = opts.maxTokensPerTool || 6;
+  const records = loadAll();
+  // Check total weight (success_count sum), not just record count
+  const totalWeight = records.reduce((s, r) => s + (r.success_count ?? 1), 0);
+  if (totalWeight < MIN_TOKEN_USES) return {};
+
+  // Count per token: total + per-tool (weighted by success_count)
+  const tokenTotal = new Map();
+  const tokenByTool = new Map(); // token → Map(tool → count)
+  for (const r of records) {
+    if (!r.ok) continue;
+    // Filter out patterns with poor success rate
+    const sr = (r.success_count ?? 1) / Math.max((r.success_count ?? 1) + (r.fail_count ?? 0), 1);
+    if (sr < 0.4) continue; // skip patterns that fail more than 60% of the time
+    const weight = r.success_count ?? 1; // use success_count as weight
+    for (const tok of r.tokens || []) {
+      tokenTotal.set(tok, (tokenTotal.get(tok) || 0) + weight);
+      if (!tokenByTool.has(tok)) tokenByTool.set(tok, new Map());
+      const tm = tokenByTool.get(tok);
+      tm.set(r.first_tool, (tm.get(r.first_tool) || 0) + weight);
+    }
+  }
+
+  // For each tool, collect tokens where P(tool | token) >= threshold
+  const prefs = {}; // tool → [{token, confidence, support}]
+  for (const [token, total] of tokenTotal) {
+    if (total < MIN_TOKEN_USES) continue;
+    const tm = tokenByTool.get(token);
+    for (const [tool, count] of tm) {
+      const confidence = count / total;
+      if (confidence < MIN_CONFIDENCE) continue;
+      if (!prefs[tool]) prefs[tool] = [];
+      prefs[tool].push({ token, confidence, support: count });
+    }
+  }
+
+  // Sort and cap per tool
+  for (const tool of Object.keys(prefs)) {
+    prefs[tool].sort((a, b) => {
+      // Primary: confidence desc; secondary: support desc
+      if (b.confidence !== a.confidence) return b.confidence - a.confidence;
+      return b.support - a.support;
+    });
+    prefs[tool] = prefs[tool].slice(0, MAX_TOKENS_PER_TOOL);
+  }
+
+  return prefs;
+}
+
+/**
+ * Format compiled preferences as a compact prompt-ready block.
+ * @param {Record<string, Array<{token,confidence,support}>>} prefs
+ * @returns {string}
+ */
+export function formatForPrompt(prefs) {
+  const tools = Object.keys(prefs);
+  if (!tools.length) return "";
+  const lines = ["Tool preferences learned from past successful sessions:"];
+  for (const tool of tools) {
+    const items = prefs[tool];
+    if (!items?.length) continue;
+    const tokens = items.map(i => `${i.token} (${Math.round(i.confidence * 100)}%, n=${i.support})`).join(", ");
+    lines.push(`  ${tool}: ${tokens}`);
+  }
+  lines.push("Prefer these tools when the user's request contains the listed keywords.");
+  return lines.join("\n");
+}
+
+export const __internal = { STOP_WORDS };

package/src/memory/project.js

@@ -0,0 +1,66 @@
+// Project scope detection.
+//
+// Facts are split into global (about the user) and project-scoped (about a
+// specific project). This file resolves "what project are we currently in?"
+// so the rest of the memory layer can filter appropriately.
+//
+// Priority:
+//   1. Explicit override via setCurrentProject(name) — from /project set
+//   2. MEMORY.md in current workspace contains `project: <name>` frontmatter
+//   3. CWD leaf name (last path segment) matches a known project from registry
+//   4. Fallback: null (no project scope; everything treated as global)
+
+import { readFileSync, existsSync } from "node:fs";
+import { join, basename } from "node:path";
+
+let _explicitProject = null;
+
+/**
+ * Explicit override — set by /project set NAME. Takes priority over detection.
+ */
+export function setCurrentProject(name) {
+  _explicitProject = name ? String(name).trim().toLowerCase() : null;
+}
+
+/**
+ * Clear the explicit override and fall back to detection.
+ */
+export function clearCurrentProject() {
+  _explicitProject = null;
+}
+
+/**
+ * Detect the current project name.
+ *
+ * @param {string} [cwd=process.cwd()] — working directory
+ * @returns {string|null} lowercase project name, or null if no project
+ */
+export function getCurrentProject(cwd = process.cwd()) {
+  if (_explicitProject) return _explicitProject;
+
+  // 2. MEMORY.md with `project:` frontmatter
+  try {
+    const memoryPath = join(cwd, "MEMORY.md");
+    if (existsSync(memoryPath)) {
+      const content = readFileSync(memoryPath, "utf-8").slice(0, 1000);
+      const match = content.match(/^project:\s*([a-z0-9-_]+)/im);
+      if (match) return match[1].toLowerCase();
+    }
+  } catch {}
+
+  // 3. CWD leaf — only if it matches a plausible project pattern.
+  // Using leaf makes this automatic for users working in repo dirs like
+  // `flint-agent`, `my-app`, `screenbox`. Normalised: lowercased, strip trailing
+  // suffixes like "-agent" that are tooling-specific.
+  try {
+    const leaf = basename(cwd).toLowerCase();
+    // Ignore generic names that could collide: "src", "tmp", "home", "desktop"
+    const ignored = new Set(["src", "tmp", "temp", "home", "desktop", "documents", "downloads", "node_modules", ""]);
+    if (leaf && !ignored.has(leaf) && /^[a-z0-9][a-z0-9-_]{1,40}$/.test(leaf)) {
+      // Strip common suffixes
+      return leaf.replace(/-agent$|-app$|-site$/, "");
+    }
+  } catch {}
+
+  return null;
+}

package/src/memory/reflections.js

@@ -0,0 +1,74 @@
+// Reflections memory — auto-extracted learnings at session end.
+//
+// Layer 1 of memory architecture.
+// Backend: SQLite via sqlite-store.js (migrated from JSONL 2026-04-16).
+// At session end, model is prompted with 3 questions (did / wrong / better),
+// response is parsed and stored. At next session start, last N are prepended
+// to system prompt as trusted-context so model doesn't repeat past mistakes.
+
+import { insertReflection, getRecentReflections, getAllReflections, migrateFromJsonl } from "./sqlite-store.js";
+
+// Run migration on first import (idempotent — skips if already migrated)
+try { migrateFromJsonl(); } catch {}
+
+/**
+ * Append a reflection.
+ * @param {{ id?:string, ts?:string, session_id?:string, did:string, wrong:string[], better:string[], tags?:string[] }} reflection
+ * @returns {string|null} id
+ */
+export function appendReflection(reflection) {
+  const now = new Date();
+  const record = {
+    id: reflection.id || `r-${now.toISOString().slice(0, 10)}-${now.getTime().toString(36).slice(-5)}${Math.random().toString(36).slice(2, 5)}`,
+    ts: reflection.ts || now.toISOString(),
+    session_id: reflection.session_id || "",
+    did: String(reflection.did || "").trim(),
+    wrong: Array.isArray(reflection.wrong) ? reflection.wrong.filter(Boolean) : [],
+    better: Array.isArray(reflection.better) ? reflection.better.filter(Boolean) : [],
+    tags: Array.isArray(reflection.tags) ? reflection.tags.filter(Boolean) : [],
+  };
+  if (!record.did && record.wrong.length === 0 && record.better.length === 0) {
+    return null;
+  }
+  return insertReflection(record);
+}
+
+/**
+ * Load last N reflections (most recent first).
+ */
+export function loadRecent(n = 5) {
+  return getRecentReflections(n);
+}
+
+/**
+ * Load all reflections. Used by the pattern analyzer (Layer 2).
+ */
+export function loadAll() {
+  return getAllReflections();
+}
+
+/**
+ * Format reflections as a system-prompt-ready text block.
+ * Short, scannable, focused on 'better' guidance.
+ * @param {object[]} reflections
+ * @returns {string}
+ */
+export function formatForPrompt(reflections) {
+  if (!reflections.length) return "";
+  const lines = ["Past lessons from recent sessions (avoid repeating these mistakes):"];
+  for (const r of reflections) {
+    const date = r.ts ? r.ts.slice(0, 10) : "";
+    if (r.wrong.length) {
+      lines.push(`\n[${date}] I did wrong:`);
+      for (const w of r.wrong.slice(0, 3)) lines.push(`  - ${w}`);
+    }
+    if (r.better.length) {
+      lines.push(`[${date}] Next time:`);
+      for (const b of r.better.slice(0, 3)) lines.push(`  - ${b}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+// Exposed for tests (legacy references removed — now in sqlite-store)
+export const __internal = {};

package/src/memory/retrieval.js

@@ -0,0 +1,84 @@
+// Retrieval memory — Layer 4 of memory architecture.
+//
+// Unlike Layers 1-3 (frozen at session start in system prompt), Layer 4
+// injects PER-TURN context: on each user message, look up the most
+// similar past requests and surface "similar past requests used tool X"
+// as a just-in-time hint.
+//
+// Backing store: patterns.jsonl (already populated by Layer 2).
+// Similarity: Jaccard token overlap (no embeddings, no extra deps).
+
+import { loadAll as loadAllPatterns } from "./patterns.js";
+import { tokenize } from "./patterns.js";
+
+function jaccard(aSet, bSet) {
+  let inter = 0;
+  for (const x of aSet) if (bSet.has(x)) inter++;
+  const union = aSet.size + bSet.size - inter;
+  return union === 0 ? 0 : inter / union;
+}
+
+/**
+ * Find the top-K most-similar past requests to the given request.
+ * @param {string} request
+ * @param {object} opts
+ * @param {number} opts.topK — how many matches to return (default 5)
+ * @param {number} opts.minSimilarity — Jaccard threshold (default 0.25)
+ * @returns {Array<{record:object, similarity:number}>}
+ */
+export function findSimilarRequests(request, opts = {}) {
+  const topK = opts.topK || 5;
+  const minSim = opts.minSimilarity ?? 0.25;
+  if (!request || typeof request !== "string") return [];
+  const queryTokens = new Set(tokenize(request));
+  if (queryTokens.size === 0) return [];
+
+  const records = loadAllPatterns();
+  const scored = [];
+  for (const r of records) {
+    if (!r.tokens || !Array.isArray(r.tokens)) continue;
+    const s = jaccard(queryTokens, new Set(r.tokens));
+    if (s < minSim) continue;
+    scored.push({ record: r, similarity: s });
+  }
+  scored.sort((a, b) => b.similarity - a.similarity);
+  return scored.slice(0, topK);
+}
+
+/**
+ * Aggregate matches into "N past requests similar to this one used tool X
+ * in M of N cases". Returns an injectable hint string or empty.
+ *
+ * @param {Array<{record,similarity}>} matches
+ * @returns {string}
+ */
+export function formatRetrievalHint(matches) {
+  if (!matches?.length) return "";
+
+  // Count first_tool occurrences
+  const toolCounts = new Map();
+  for (const m of matches) {
+    const t = m.record.first_tool;
+    if (!t) continue;
+    toolCounts.set(t, (toolCounts.get(t) || 0) + 1);
+  }
+  if (toolCounts.size === 0) return "";
+
+  const sorted = [...toolCounts.entries()].sort((a, b) => b[1] - a[1]);
+  const top = sorted[0];
+  const total = matches.length;
+  const [topTool, topCount] = top;
+
+  // Only emit a hint if the dominant tool is majority (>= 50%) and we
+  // have at least 2 supporting cases. Otherwise, ambiguous history.
+  if (topCount < 2 || topCount / total < 0.5) return "";
+
+  const topSimilarity = Math.round(matches[0].similarity * 100);
+  const parts = [`Similar past requests (top match ${topSimilarity}% token overlap): ${topCount}/${total} used ${topTool}.`];
+  if (sorted.length > 1) {
+    const others = sorted.slice(1).map(([t, c]) => `${t}(${c})`).join(", ");
+    parts.push(`Others: ${others}.`);
+  }
+  parts.push(`Prefer ${topTool} unless the current request differs materially.`);
+  return parts.join(" ");
+}