@cachly-dev/mcp-server 0.10.65 → 0.10.67

package/src/namespace.ts

@@ -1,128 +0,0 @@
-/**
- * Namespace Auto-Detection
- *
- * Classify a prompt into one of 5 semantic namespaces using text heuristics.
- * Overhead: <0.1 ms. No embedding required.
- *
- * Covers: EN · DE · FR · ES · IT · PT · NL
- * Source of truth for keyword lists: sdk/shared/filler-words.ts
- */
-
-const CODE_KW = [
-  'function ', 'def ', 'class ', 'import ', 'const ', 'let ', 'var ',
-  'return ', ' => ', 'void ', 'public class', 'func ', '#include', 'package ',
-  'struct ', 'interface ', 'async def', 'lambda ', '#!/',
-];
-
-// Translation – EN · DE · FR · ES · IT · PT · NL
-const TRANSL_KW = [
-  // EN
-  'translate', 'in english', 'in german', 'in french', 'in spanish', 'in italian', 'in portuguese',
-  // DE
-  'übersetze', 'übersetz', 'auf deutsch', 'auf englisch', 'ins deutsche', 'ins englische',
-  // FR
-  'traduis', 'traduire', 'en français', 'en anglais', 'en allemand', 'en espagnol',
-  // ES
-  'traduce', 'traducir', 'al español', 'al inglés', 'al alemán',
-  // IT
-  'traduci', 'in italiano', 'in inglese', 'in tedesco',
-  // PT
-  'traduz', 'traduzir', 'em português', 'em inglês', 'em alemão',
-  // NL
-  'vertaal',
-];
-
-// Summary – EN · DE · FR · ES · IT · PT
-const SUMMARY_KW = [
-  // EN
-  'summarize', 'summarise', 'summary', 'tl;dr', 'tldr',
-  'key points', 'give me a brief', 'in a nutshell', 'in short', 'overview of',
-  // DE
-  'zusammenfass', 'stichpunkte', 'fasse zusammen', 'kurze zusammenfassung', 'überblick',
-  // FR
-  'résume', 'résumé', 'résumer', 'points clés', 'en bref', "vue d'ensemble",
-  // ES
-  'resumir', 'en resumen', 'puntos clave', 'en breve', 'resumen de',
-  // IT
-  'riassumi', 'riassunto', 'punti chiave', 'in breve', 'panoramica',
-  // PT
-  'resumir', 'em resumo', 'pontos principais', 'resumo de',
-];
-
-// Q&A prefixes – EN · DE · FR · ES · IT · PT
-const QA_PREFIXES = [
-  // EN
-  'what ', 'who ', 'where ', 'when ', 'why ', 'how ', 'which ',
-  'is ', 'are ', 'was ', 'were ', 'does ', 'do ', 'did ',
-  'can ', 'could ', 'would ', 'should ', 'will ',
-  // DE
-  'wer ', 'wie ', 'wo ', 'wann ', 'warum ', 'welche', 'wieso ', 'was ist',
-  // FR
-  "qu'est-ce que", 'comment ', 'pourquoi ', 'quel ', 'quelle ', 'quels ',
-  'est-ce que', 'qui est', 'où est', 'quand ',
-  // ES
-  'qué ', 'cómo ', 'quién ', 'dónde ', 'cuándo ', 'por qué ',
-  // IT
-  'come ', 'perché ', "cos'è", "com'è", 'dove ', 'quando ', 'chi è',
-  // PT
-  'o que ', 'como ', 'quem ', 'onde ', 'quando ', 'por que ',
-];
-
-/**
- * Classify a prompt into one of 5 semantic namespaces.
- * Returns one of: `cachly:sem:code` | `:translation` | `:summary` | `:qa` | `:creative`
- */
-export function detectNamespace(prompt: string): string {
-  const s = prompt.trim().toLowerCase();
-  if (CODE_KW.some((kw) => s.includes(kw))) return 'cachly:sem:code';
-  if (TRANSL_KW.some((kw) => s.includes(kw))) return 'cachly:sem:translation';
-  if (SUMMARY_KW.some((kw) => s.includes(kw))) return 'cachly:sem:summary';
-  if (QA_PREFIXES.some((p) => s.startsWith(p))) return 'cachly:sem:qa';
-  if (s.trimEnd().endsWith('?')) return 'cachly:sem:qa';
-  return 'cachly:sem:creative';
-}
-
-/**
- * Filler words used by prompt normalisation in MCP context.
- * Source of truth: sdk/shared/filler-words.ts
- * Covers: EN · DE · FR · ES · IT · PT
- */
-export const FILLER_WORDS: string[] = [
-  // EN
-  'please', 'hey', 'hi', 'hello',
-  'could you', 'can you', 'would you', 'will you',
-  'just', 'quickly', 'briefly', 'simply',
-  'tell me', 'show me', 'give me', 'help me', 'assist me',
-  'explain to me', 'describe to me',
-  'i need', 'i want', 'i would like', "i'd like", "i'm looking for",
-  // DE
-  'bitte', 'mal eben', 'schnell', 'kurz', 'einfach',
-  'kannst du', 'könntest du', 'könnten sie', 'würden sie', 'würdest du',
-  'hallo', 'hi', 'hey',
-  'sag mir', 'zeig mir', 'gib mir', 'hilf mir', 'erkläre mir', 'erklär mir',
-  'ich brauche', 'ich möchte', 'ich hätte gerne', 'ich suche',
-  // FR
-  "s'il vous plaît", 'svp', 'stp', 'bonjour', 'salut', 'allô',
-  'pouvez-vous', 'pourriez-vous', 'peux-tu', 'pourrais-tu',
-  'dis-moi', 'dites-moi', 'montre-moi', 'montrez-moi',
-  "j'ai besoin de", 'je voudrais', 'je cherche', 'je souhaite',
-  'expliquez-moi', 'explique-moi', 'aidez-moi', 'aide-moi',
-  // ES
-  'por favor', 'hola', 'oye',
-  'puedes', 'podrías', 'podría usted', 'me puedes', 'me podrías',
-  'dime', 'dígame', 'muéstrame', 'muéstreme', 'dame', 'deme',
-  'necesito', 'quisiera', 'me gustaría', 'quiero saber',
-  'ayúdame', 'ayúdeme', 'explícame', 'explíqueme',
-  // IT
-  'per favore', 'perfavore', 'ciao', 'salve', 'ehi',
-  'potresti', 'mi potresti', 'potrebbe', 'mi potrebbe',
-  'dimmi', 'mi dica', 'mostrami', 'dammi', 'mi dia',
-  'ho bisogno di', 'vorrei', 'mi piacerebbe',
-  'aiutami', 'mi aiuti', 'spiegami', 'mi spieghi',
-  // PT
-  'por favor', 'olá', 'oi', 'ei',
-  'pode', 'poderia', 'você poderia', 'você pode', 'podes',
-  'me diga', 'diga-me', 'me mostre', 'mostre-me', 'me dê', 'dê-me',
-  'preciso de', 'gostaria de', 'quero saber', 'estou procurando',
-  'me ajude', 'ajude-me', 'explique-me', 'me explique',
-];

package/src/notifier.ts

@@ -1,5 +0,0 @@
-/**
- * Re-exports from the shared telegram-notify package.
- * Canonical implementation: packages/telegram-notify/client.ts
- */
-export { notify, formatMessage } from '../packages/telegram-notify/client.js';

package/src/rerank.ts

@@ -1,148 +0,0 @@
-/**
- * Quality-aware reranking for Brain recall.
- *
- * The raw BM25+ keyword search (src/search.ts) ranks purely by *textual* relevance.
- * That is necessary but not sufficient: when an agent asks "how do I fix the flaky
- * deploy?", a *failed* attempt with similar words can out-rank the *proven success*
- * lesson that actually solves it. Anthropic's flat-file memory has exactly this
- * problem — it reads files in order, with no notion of which lesson is trustworthy.
- *
- * This module is Cachly's structural advantage made concrete: we re-rank text
- * matches by the *quality* of the underlying lesson — outcome, confidence,
- * proven-ness (recall_count), severity and human review (endorsements) — so the
- * lesson most likely to help surfaces first. A flat-file memory has none of these
- * signals; a senior-confirmed, ten-times-recalled success reads identically to a
- * one-off failed attempt.
- *
- * It is intentionally pure (no I/O): the lesson JSON already travels inside each
- * KeywordMatch.content for `cachly:lesson:best:*` keys, so reranking needs no extra
- * Redis round-trips. This keeps it fast and trivially benchmarkable (see
- * src/bench/cachly-bench.ts).
- */
-
-import type { KeywordMatch } from './search.js';
-import { safeJsonParse } from './utils.js';
-
-/** Subset of a stored lesson that influences ranking. */
-export interface LessonQuality {
-  outcome?: string;        // 'success' | 'partial' | 'failure'
-  confidence?: number;     // 0..1
-  recall_count?: number;   // times this lesson has been recalled (proven-ness)
-  severity?: string;       // 'critical' | 'major' | 'minor'
-  ts?: string;             // ISO timestamp (for freshness, mild)
-  verified_at?: string;
-  // ── Governance (Phase 3): human review raises trust above mere usage ──
-  reviewed_by?: string;    // handle of the reviewer who endorsed it (latest)
-  review_level?: string;   // 'senior' | 'peer' (weight differs)
-  endorsements?: number;   // distinct human endorsements
-}
-
-export interface RerankedMatch extends KeywordMatch {
-  /** Final score after applying the quality multiplier. */
-  finalScore: number;
-  /** The multiplier that was applied to the BM25 score (1.0 = neutral). */
-  qualityBoost: number;
-}
-
-// ── Tunable weights (kept conservative; validated by Cachly-Bench) ─────────────
-const OUTCOME_WEIGHT: Record<string, number> = {
-  success: 1.0,
-  partial: 0.8,
-  failure: 0.55,
-};
-const OUTCOME_DEFAULT = 0.75; // unknown / not a lesson with an outcome
-
-const SEVERITY_WEIGHT: Record<string, number> = {
-  critical: 1.15,
-  major: 1.05,
-  minor: 1.0,
-};
-const SEVERITY_DEFAULT = 1.0;
-
-// Governance: a human-confirmed lesson is more trustworthy than one proven only
-// by automated recall. A senior review weighs more than a peer review; multiple
-// endorsements add a small, saturating bump on top.
-const REVIEW_LEVEL_WEIGHT: Record<string, number> = {
-  senior: 1.25,
-  peer: 1.1,
-};
-
-// Clamp so a strong text match is never fully buried by quality, and a weak text
-// match is never catapulted to the top purely on quality.
-const MIN_MULTIPLIER = 0.5;
-const MAX_MULTIPLIER = 2.5;
-
-const LESSON_KEY_PREFIX = 'cachly:lesson:best:';
-
-/**
- * Compute the quality multiplier for a single lesson.
- * Returns 1.0 (neutral) for documents that carry no quality signal (e.g. context).
- */
-export function qualityMultiplier(lesson: LessonQuality | null): number {
-  if (!lesson || (lesson.outcome === undefined && lesson.confidence === undefined
-      && lesson.recall_count === undefined && lesson.reviewed_by === undefined
-      && lesson.endorsements === undefined)) {
-    return 1.0;
-  }
-
-  // 1. Outcome — a proven success is what the agent actually wants.
-  const outcome = OUTCOME_WEIGHT[lesson.outcome ?? ''] ?? OUTCOME_DEFAULT;
-
-  // 2. Confidence — maps 0..1 → 0.7..1.3 so it nudges, not dominates.
-  const conf = typeof lesson.confidence === 'number' ? Math.max(0, Math.min(1, lesson.confidence)) : 0.6;
-  const confidenceFactor = 0.7 + 0.6 * conf;
-
-  // 3. Proven-ness — a lesson recalled many times has stood the test of use.
-  //    Log-scaled so it saturates: rc=0→1.0, rc=5→~1.18, rc=50→~1.30.
-  const rc = Math.max(0, lesson.recall_count ?? 0);
-  const provenBoost = 1 + Math.min(0.3, Math.log1p(rc) / 13);
-
-  // 4. Severity — when two lessons tie, surface the one guarding the worse failure.
-  const severity = SEVERITY_WEIGHT[lesson.severity ?? ''] ?? SEVERITY_DEFAULT;
-
-  // 5. Governance — a human-confirmed lesson outranks an unreviewed one.
-  //    Base weight from the review level, plus a small saturating bump for
-  //    additional endorsements (rc-style log curve, capped at +0.1).
-  const reviewBase = lesson.reviewed_by
-    ? (REVIEW_LEVEL_WEIGHT[lesson.review_level ?? 'peer'] ?? REVIEW_LEVEL_WEIGHT.peer)
-    : 1.0;
-  const extraEndorse = Math.max(0, (lesson.endorsements ?? 0) - 1);
-  const reviewBoost = reviewBase * (1 + Math.min(0.1, Math.log1p(extraEndorse) / 20));
-
-  const m = outcome * confidenceFactor * provenBoost * severity * reviewBoost;
-  return Math.max(MIN_MULTIPLIER, Math.min(MAX_MULTIPLIER, m));
-}
-
-/** Extract the quality signal from a match, if its content is a stored lesson. */
-export function extractLessonQuality(match: Pick<KeywordMatch, 'key' | 'content'>): LessonQuality | null {
-  if (!match.key.startsWith(LESSON_KEY_PREFIX)) return null;
-  return safeJsonParse<LessonQuality | null>(match.content, null);
-}
-
-/**
- * Rerank BM25 keyword matches by lesson quality.
- *
- * The BM25 scores are first min-max normalized to [0,1] so the quality multiplier
- * acts on a comparable scale across queries; ties are broken by the original BM25
- * score (stable, deterministic).
- */
-export function rerankByQuality(matches: KeywordMatch[]): RerankedMatch[] {
-  if (matches.length === 0) return [];
-
-  const maxScore = Math.max(...matches.map(m => m.score));
-  const minScore = Math.min(...matches.map(m => m.score));
-  const range = maxScore - minScore || 1;
-
-  const reranked: RerankedMatch[] = matches.map(m => {
-    const norm = (m.score - minScore) / range; // 0..1
-    const lesson = extractLessonQuality(m);
-    const boost = qualityMultiplier(lesson);
-    // Blend: keep a floor of raw relevance so a top text hit stays competitive,
-    // then layer the quality multiplier on the normalized component.
-    const finalScore = m.score * (0.4 + 0.6 * boost) + norm * (boost - 1) * 0.0001;
-    return { ...m, finalScore, qualityBoost: boost };
-  });
-
-  reranked.sort((a, b) => (b.finalScore - a.finalScore) || (b.score - a.score));
-  return reranked;
-}