@cachly-dev/mcp-server 0.10.65 → 0.10.66

package/src/bench/fixtures.ts

@@ -1,256 +0,0 @@
-/**
- * Cachly-Bench fixture corpus.
- *
- * A small but realistic corpus of engineering "lessons" plus a set of labeled
- * natural-language queries. Each query declares which lesson topics are *truly*
- * relevant — the answer an agent actually wants.
- *
- * The corpus is deliberately adversarial in a fair way: for several queries there
- * is a text-similar but LOW-QUALITY distractor (a failed attempt, an unverified
- * note) competing with the proven success lesson. This is exactly the situation
- * where raw text ranking (and a flat-file memory) goes wrong, and where Cachly's
- * quality-aware reranking should win. The labels reward the lesson that solves the
- * problem, not the one that merely shares vocabulary.
- */
-
-export interface BenchLesson {
-  /** Stored under cachly:lesson:best:{topic} */
-  topic: string;
-  outcome: 'success' | 'partial' | 'failure';
-  what_worked: string;
-  what_failed?: string;
-  context?: string;
-  severity?: 'critical' | 'major' | 'minor';
-  confidence?: number;
-  recall_count?: number;
-  reviewed_by?: string;
-  review_level?: 'senior' | 'peer';
-  endorsements?: number;
-  tags?: string[];
-  ts?: string;
-}
-
-export interface BenchQuery {
-  query: string;
-  /** Topics that genuinely answer the query (the gold set). */
-  relevant: string[];
-}
-
-const NOW = Date.now();
-const daysAgo = (d: number) => new Date(NOW - d * 86400_000).toISOString();
-
-export const BENCH_LESSONS: BenchLesson[] = [
-  // ── Deploy domain ──────────────────────────────────────────────────────────
-  {
-    topic: 'deploy:k8s:rollout-stuck',
-    outcome: 'success',
-    what_worked: 'Set a readinessProbe with a longer initialDelaySeconds and a higher failureThreshold so the liveness probe stopped terminating the container before startup completed. The pod then reached ready and traffic flowed.',
-    context: 'Production release never became healthy.',
-    severity: 'critical', confidence: 0.95, recall_count: 12,
-    tags: ['kubernetes', 'deploy', 'probe'], ts: daysAgo(8),
-  },
-  {
-    topic: 'deploy:k8s:rollout-attempt-restart',
-    outcome: 'failure',
-    what_worked: '',
-    what_failed: 'The kubernetes deploy was stuck, the rollout was not finishing, so I restarted the deploy. The kubernetes deploy stayed stuck and the rollout still was not finishing. Restarted the stuck rollout again, deploy still stuck.',
-    context: 'Kubernetes deploy stuck, rollout not finishing.',
-    severity: 'major', confidence: 0.3, recall_count: 0,
-    tags: ['kubernetes', 'deploy'], ts: daysAgo(9),
-  },
-  {
-    topic: 'deploy:docker:image-too-large',
-    outcome: 'success',
-    what_worked: 'Reduced Docker image size dramatically with a multi-stage build and a slim base image, moving build-only deps out of the final layer.',
-    context: 'CI pushes were slow due to a 1.8GB image.',
-    severity: 'minor', confidence: 0.9, recall_count: 6,
-    tags: ['docker', 'deploy', 'optimization'], ts: daysAgo(20),
-  },
-
-  // ── Database domain ────────────────────────────────────────────────────────
-  {
-    topic: 'db:postgres:connection-pool-exhausted',
-    outcome: 'success',
-    what_worked: 'Added PgBouncer in transaction pooling mode and lowered the per-service max pool size so backends were shared. Peak traffic stopped exhausting backends.',
-    context: 'API returned 500s at peak traffic.',
-    severity: 'critical', confidence: 0.92, recall_count: 9,
-    tags: ['postgres', 'database', 'pool'], ts: daysAgo(15),
-  },
-  {
-    topic: 'db:postgres:slow-query-missing-index',
-    outcome: 'success',
-    what_worked: 'A slow Postgres query was fixed by adding a composite index on (tenant_id, created_at); query dropped from 4s to 12ms.',
-    context: 'Dashboard timed out loading recent events.',
-    severity: 'major', confidence: 0.88, recall_count: 4,
-    tags: ['postgres', 'database', 'index', 'performance'], ts: daysAgo(30),
-  },
-  {
-    topic: 'db:postgres:pool-raise-limit-attempt',
-    outcome: 'failure',
-    what_worked: '',
-    what_failed: 'Postgres had too many connections under load, so I raised max_connections. Postgres still had too many connections under load and the load made it worse — too many connections again under load.',
-    context: 'Postgres too many connections under load.',
-    severity: 'major', confidence: 0.25, recall_count: 0,
-    tags: ['postgres', 'database', 'pool'], ts: daysAgo(16),
-  },
-
-  // ── Auth domain ────────────────────────────────────────────────────────────
-  {
-    topic: 'auth:jwt:expired-on-restart',
-    outcome: 'success',
-    what_worked: 'JWT was lost on server restart because it was only kept in memory; persisting the token to disk after the device flow fixed recall counts staying at zero.',
-    context: 'Telemetry showed zero authenticated calls after restarts.',
-    severity: 'critical', confidence: 0.93, recall_count: 7,
-    tags: ['jwt', 'auth', 'persistence'], ts: daysAgo(3),
-  },
-  {
-    topic: 'auth:pkce:keycloak-rejects-exchange',
-    outcome: 'success',
-    what_worked: 'Keycloak rejected the PKCE code exchange because the verifier used non-URL-safe Base64; switching to RFC 7636 Base64URL random bytes fixed the login.',
-    context: 'Mobile login failed at the token exchange step.',
-    severity: 'major', confidence: 0.9, recall_count: 3,
-    tags: ['pkce', 'auth', 'keycloak', 'oauth'], ts: daysAgo(2),
-  },
-
-  // ── Redis / cache domain ───────────────────────────────────────────────────
-  {
-    topic: 'redis:noauth-on-every-call',
-    outcome: 'success',
-    what_worked: 'The connection endpoint omitted the password field, so the client connected unauthenticated; returning the credential explicitly in the response let the client authenticate and the calls succeeded.',
-    context: 'Hosted Valkey requires a credential.',
-    severity: 'critical', confidence: 0.94, recall_count: 11,
-    tags: ['redis', 'valkey', 'auth'], ts: daysAgo(4),
-  },
-  {
-    topic: 'redis:noauth-disable-auth-attempt',
-    outcome: 'failure',
-    what_worked: '',
-    what_failed: 'Redis threw NOAUTH on every call, so I tried disabling auth on Redis. Redis still threw NOAUTH on every call. Tried again to stop the NOAUTH error on every Redis call — no luck.',
-    context: 'Redis NOAUTH error on every call.',
-    severity: 'major', confidence: 0.2, recall_count: 0,
-    tags: ['redis', 'auth'], ts: daysAgo(5),
-  },
-  {
-    topic: 'redis:keys-no-ttl-memory-leak',
-    outcome: 'success',
-    what_worked: 'Redis memory grew unbounded because dependency-index and history keys had no TTL; adding a 90-day expire and an ltrim bounded the memory.',
-    context: 'Instance memory crept up over weeks of use.',
-    severity: 'major', confidence: 0.85, recall_count: 2,
-    tags: ['redis', 'ttl', 'memory'], ts: daysAgo(1),
-  },
-
-  // ── CI / build domain ──────────────────────────────────────────────────────
-  {
-    topic: 'ci:npm-ci-lockfile-mismatch',
-    outcome: 'success',
-    what_worked: 'CI "npm ci" failed because a dependency was added to package.json but the lockfile was never regenerated; running npm install to update package-lock.json fixed the build.',
-    context: 'GitHub Actions install step failed after adding a dep.',
-    severity: 'major', confidence: 0.91, recall_count: 5,
-    tags: ['ci', 'npm', 'lockfile'], ts: daysAgo(0),
-  },
-  {
-    topic: 'ci:golangci-lint-errcheck',
-    outcome: 'success',
-    what_worked: 'golangci-lint failed on an unchecked recover() return value; assigning it to _ satisfied errcheck.',
-    context: 'Go lint job blocked the deploy pipeline.',
-    severity: 'minor', confidence: 0.8, recall_count: 1,
-    tags: ['ci', 'go', 'lint'], ts: daysAgo(1),
-  },
-
-  // ── Frontend domain ────────────────────────────────────────────────────────
-  {
-    topic: 'frontend:cors-preflight-blocked',
-    outcome: 'success',
-    what_worked: 'Dashboard mutations failed because the CORS middleware did not allow PUT/PATCH; adding them to AllowMethods fixed the preflight.',
-    context: 'BYOK and webhook settings could not be saved from the browser.',
-    severity: 'major', confidence: 0.87, recall_count: 4,
-    tags: ['cors', 'frontend', 'api'], ts: daysAgo(6),
-  },
-  {
-    topic: 'frontend:hydration-mismatch',
-    outcome: 'partial',
-    what_worked: 'A Next.js hydration mismatch was reduced by guarding a date render with a client-only effect, though the root cause (locale formatting) still needs work.',
-    context: 'Console hydration warnings on the landing page.',
-    severity: 'minor', confidence: 0.6, recall_count: 1,
-    tags: ['nextjs', 'frontend', 'hydration'], ts: daysAgo(25),
-  },
-
-  // ── Governance adversarial pair: two similar-text success lessons ──────────
-  // Only the reviewed one should win; baseline cannot distinguish them by text.
-  {
-    topic: 'auth:csrf:double-submit-cookie',
-    outcome: 'success',
-    what_worked: 'CSRF protection was added via the double-submit cookie pattern: the server sets a random CSRF token cookie; the client echoes it as a request header. Requests with a mismatched or absent header are rejected.',
-    context: 'API mutations lacked CSRF protection; security audit required a fix.',
-    severity: 'critical', confidence: 0.91, recall_count: 2,
-    reviewed_by: 'senior-alice', review_level: 'senior', endorsements: 2,
-    tags: ['csrf', 'auth', 'security', 'cookie'], ts: daysAgo(12),
-  },
-  {
-    topic: 'auth:csrf:origin-header-check',
-    outcome: 'success',
-    what_worked: 'CSRF mitigation attempted by checking the Origin header on API requests, but this was bypassed in a penetration test because same-site requests from subdomains also sent the header.',
-    context: 'API mutations lacked CSRF protection; origin header check was insufficient.',
-    severity: 'major', confidence: 0.55, recall_count: 1,
-    tags: ['csrf', 'auth', 'security'], ts: daysAgo(14),
-  },
-];
-
-export const BENCH_QUERIES: BenchQuery[] = [
-  {
-    query: 'kubernetes deploy stuck rollout not finishing',
-    relevant: ['deploy:k8s:rollout-stuck'],
-  },
-  {
-    query: 'postgres too many connections under load',
-    relevant: ['db:postgres:connection-pool-exhausted'],
-  },
-  {
-    query: 'dashboard query is slow and times out',
-    relevant: ['db:postgres:slow-query-missing-index'],
-  },
-  {
-    query: 'jwt lost after restart recall count zero',
-    relevant: ['auth:jwt:expired-on-restart'],
-  },
-  {
-    query: 'keycloak rejects pkce token exchange on login',
-    relevant: ['auth:pkce:keycloak-rejects-exchange'],
-  },
-  {
-    query: 'redis noauth error on every call',
-    relevant: ['redis:noauth-on-every-call'],
-  },
-  {
-    query: 'redis memory keeps growing unbounded',
-    relevant: ['redis:keys-no-ttl-memory-leak'],
-  },
-  {
-    query: 'npm ci fails in github actions after adding dependency',
-    relevant: ['ci:npm-ci-lockfile-mismatch'],
-  },
-  {
-    query: 'cannot save settings cors preflight blocked',
-    relevant: ['frontend:cors-preflight-blocked'],
-  },
-  {
-    query: 'docker image too big slow ci push',
-    relevant: ['deploy:docker:image-too-large'],
-  },
-  {
-    query: 'go lint failing on unchecked return value',
-    relevant: ['ci:golangci-lint-errcheck'],
-  },
-  // Multi-relevant: both postgres performance lessons are reasonable answers.
-  {
-    query: 'postgres performance problem in production',
-    relevant: ['db:postgres:connection-pool-exhausted', 'db:postgres:slow-query-missing-index'],
-  },
-  // Governance adversarial: two CSRF lessons have almost identical text, but only
-  // the senior-reviewed canonical one is a proven complete solution. Quality
-  // reranking must prefer the reviewed+endorsed lesson over the unreviewed partial.
-  {
-    query: 'CSRF protection missing on API mutations security',
-    relevant: ['auth:csrf:double-submit-cookie'],
-  },
-];

package/src/ckg.ts

@@ -1,103 +0,0 @@
-import { Redis } from 'ioredis';
-
-// ── Layer 1: Causal Knowledge Graph (CKG) helpers ────────────────────────────
-// Nodes: cachly:ckg:node:{id}  → CKGNode | PersonNode | FileNode
-// Edges: cachly:ckg:edge:{from}:{edgeType}:{to} → CKGEdge
-
-export type CKGEdge = {
-  from: string; to: string; edgeType: string;
-  successes: number; trials: number; confidence: number; last_updated: string;
-};
-
-export type CKGNode = { id: string; domain: string; type: string; count: number; ts: string };
-
-// Phase 3A: People nodes — auto-built from learn_from_attempts(author=...)
-export type PersonNode = {
-  id: string;          // "person:{slug}"
-  handle: string;      // original author string as provided
-  domain: string;      // first/primary problem domain seen
-  type: 'person';
-  count: number;       // number of lessons authored
-  last_active: string; // ISO timestamp of most recent contribution
-};
-
-// Phase 3A: File nodes — auto-built from learn_from_attempts(file_paths=[...])
-export type FileNode = {
-  id: string;    // "file:{slug}"
-  path: string;  // original file path
-  domain: string;
-  type: 'file';
-  count: number; // number of times referenced in lessons
-  ts: string;
-};
-
-const STOPWORDS_CKG = new Set(['that','this','with','from','when','then','also','have','been','will','were','they','them','than','more','some','into','over','only','just','where','while','which','there','their','would','could','should','after','before','about']);
-
-export function ckgSlug(text: string): string {
-  return text.toLowerCase().replace(/[^a-z0-9\-:]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '').slice(0, 80);
-}
-
-/** Extract 1-3 significant keywords from free text for a problem concept */
-export function extractProblemConcept(text: string): string | null {
-  const words = text.toLowerCase()
-    .replace(/[^a-z0-9\s\-_]/g, ' ').split(/\s+/)
-    .filter(w => w.length > 3 && !STOPWORDS_CKG.has(w))
-    .slice(0, 5);
-  if (words.length === 0) return null;
-  return words.slice(0, 2).join('-');
-}
-
-export async function ckgUpsertNode(redis: Redis, id: string, domain: string, type: string): Promise<void> {
-  const key = `cachly:ckg:node:${id}`;
-  const raw = await redis.get(key);
-  const node: CKGNode = raw ? JSON.parse(raw) : { id, domain, type, count: 0, ts: new Date().toISOString() };
-  node.count = (node.count || 0) + 1;
-  node.ts = new Date().toISOString();
-  await redis.set(key, JSON.stringify(node));
-}
-
-/** Upsert a Person node; returns the node id ("person:{slug}"). */
-export async function ckgUpsertPersonNode(redis: Redis, handle: string, domain: string): Promise<string> {
-  const id = `person:${ckgSlug(handle)}`;
-  const key = `cachly:ckg:node:${id}`;
-  const raw = await redis.get(key);
-  const node: PersonNode = raw
-    ? JSON.parse(raw)
-    : { id, handle, domain, type: 'person', count: 0, last_active: new Date().toISOString() };
-  node.count = (node.count || 0) + 1;
-  node.last_active = new Date().toISOString();
-  if (!node.domain) node.domain = domain;
-  await redis.set(key, JSON.stringify(node));
-  return id;
-}
-
-/** Upsert a File node; returns the node id ("file:{slug}"). */
-export async function ckgUpsertFileNode(redis: Redis, filePath: string): Promise<string> {
-  const dir = filePath.split('/')[0] ?? 'root';
-  const id = `file:${ckgSlug(filePath)}`;
-  const key = `cachly:ckg:node:${id}`;
-  const raw = await redis.get(key);
-  const node: FileNode = raw
-    ? JSON.parse(raw)
-    : { id, path: filePath, domain: dir, type: 'file', count: 0, ts: new Date().toISOString() };
-  node.count = (node.count || 0) + 1;
-  node.ts = new Date().toISOString();
-  await redis.set(key, JSON.stringify(node));
-  return id;
-}
-
-export async function ckgUpdateEdge(redis: Redis, from: string, edgeType: string, to: string, success: boolean, partial = false): Promise<void> {
-  const key = `cachly:ckg:edge:${from}:${edgeType}:${to}`;
-  const raw = await redis.get(key);
-  const edge: CKGEdge = raw ? JSON.parse(raw) : { from, to, edgeType, successes: 0, trials: 0, confidence: 0, last_updated: '' };
-  edge.trials = (edge.trials || 0) + 1;
-  if (success) edge.successes = (edge.successes || 0) + 1;
-  else if (partial) edge.successes = (edge.successes || 0) + 0.5;
-  // Beta distribution smoothed confidence: (successes+1) / (trials+2)
-  edge.confidence = (edge.successes + 1) / (edge.trials + 2);
-  edge.last_updated = new Date().toISOString();
-  await redis.set(key, JSON.stringify(edge));
-  // Index: set of edge keys per source node (for fast traversal)
-  await redis.sadd(`cachly:ckg:idx:from:${from}`, key);
-  await redis.sadd(`cachly:ckg:idx:to:${to}`, key);
-}

package/src/confidence.ts

@@ -1,38 +0,0 @@
-import { createHash } from 'node:crypto';
-
-// ── Confidence Decay Config ───────────────────────────────────────────────────
-export const CONFIDENCE_WARN_DAYS  = Number(process.env.CACHLY_CONFIDENCE_WARN_DAYS  ?? 5);
-export const CONFIDENCE_STALE_DAYS = Number(process.env.CACHLY_CONFIDENCE_STALE_DAYS ?? 10);
-export const CONFIDENCE_WARN_VALUE  = 0.7;
-export const CONFIDENCE_STALE_VALUE = 0.5;
-
-/** Calculate current confidence for a lesson based on how long since last verified. */
-export function calculateConfidence(lesson: { verified_at?: string; ts: string; recall_count?: number }): number {
-  const ref = lesson.verified_at ?? lesson.ts;
-  const ageMs = Date.now() - new Date(ref).getTime();
-  const ageDays = ageMs / 86400000;
-  if (ageDays >= CONFIDENCE_STALE_DAYS) return CONFIDENCE_STALE_VALUE;
-  if (ageDays >= CONFIDENCE_WARN_DAYS)  return CONFIDENCE_WARN_VALUE;
-  return 1.0 - (ageDays / CONFIDENCE_WARN_DAYS) * (1.0 - CONFIDENCE_WARN_VALUE);
-}
-
-/** Render a confidence badge string. */
-export function confidenceBadge(confidence: number, ageDays: number): string {
-  if (confidence >= 0.9) return '✅';
-  if (confidence >= 0.7) return `⚠️ (${Math.round(ageDays)}d old, confidence ${(confidence * 100).toFixed(0)}% — verify before applying)`;
-  return `🔴 STALE (${Math.round(ageDays)}d old, confidence ${(confidence * 100).toFixed(0)}% — likely outdated!)`;
-}
-
-/** Category-specific required fields for structured lessons. */
-export const STRUCTURED_TEMPLATES: Record<string, { required: string[]; hint: string }> = {
-  'deploy':  { required: ['commands'],                hint: 'deploy:* needs commands[]' },
-  'bash':    { required: ['commands'],                hint: 'bash:* needs commands[]' },
-  'infra':   { required: ['commands'],                hint: 'infra:* needs commands[] + verified on real system' },
-  'pricing': { required: [],                          hint: 'pricing:* — add context with source (e.g. "Stripe Dashboard Apr 2026")' },
-  'stripe':  { required: [],                          hint: 'stripe:* — add context with Stripe API version' },
-};
-
-/** Fast content hash for index invalidation (not cryptographic, just change detection) */
-export function simpleHash(text: string): string {
-  return createHash('md5').update(text).digest('hex').slice(0, 12);
-}

package/src/embeddings.ts

@@ -1,217 +0,0 @@
-/**
- * ┌──────────────────────────────────────────────────────────────────────┐
- * │  EMBEDDING PROVIDER — pluggable, client-side first                  │
- * │                                                                      │
- * │  Auto-detects from env vars. To force a provider, set:              │
- * │    CACHLY_EMBED_PROVIDER=openai   (+ OPENAI_API_KEY)                │
- * │    CACHLY_EMBED_PROVIDER=gemini   (+ GEMINI_API_KEY)                │
- * │    CACHLY_EMBED_PROVIDER=mistral  (+ MISTRAL_API_KEY)               │
- * │    CACHLY_EMBED_PROVIDER=cohere   (+ COHERE_API_KEY)                │
- * │    CACHLY_EMBED_PROVIDER=ollama   (+ OLLAMA_BASE_URL, local)        │
- * │    CACHLY_EMBED_PROVIDER=cachly   (server-side fallback, no key)    │
- * │                                                                      │
- * │  Priority: openai > gemini > mistral > cohere > ollama > cachly     │
- * │  Brain works WITHOUT embedding (keyword search + exact key lookup). │
- * │  Embedding is an optional boost for semantic_search/index_project.  │
- * └──────────────────────────────────────────────────────────────────────┘
- *
- * Mutable config — call setEmbedJwt() when the JWT changes (device flow).
- */
-
-// ── Mutable config (synced with index.ts JWT on device-flow auth) ────────────
-export const embedConfig = {
-  apiUrl: process.env.CACHLY_API_URL ?? 'https://api.cachly.dev',
-  jwt:    process.env.CACHLY_JWT ?? '',
-  model:  process.env.CACHLY_EMBED_MODEL ?? '',
-};
-
-/** Call this when JWT is refreshed (e.g. after device flow). */
-export function setEmbedJwt(jwt: string): void {
-  embedConfig.jwt = jwt;
-}
-
-// ── Provider auto-detection ───────────────────────────────────────────────────
-
-function detectEmbedProvider(): string {
-  // Client-side keys first (direct, fast, no server roundtrip)
-  if (process.env.OPENAI_API_KEY) return 'openai';
-  if (process.env.GEMINI_API_KEY) return 'gemini';
-  if (process.env.MISTRAL_API_KEY) return 'mistral';
-  if (process.env.COHERE_API_KEY) return 'cohere';
-  if (process.env.OLLAMA_BASE_URL) return 'ollama';
-  // Server-side fallback — no API key needed, but adds latency
-  if (process.env.CACHLY_JWT) return 'cachly';
-  return 'none'; // no provider → embedding disabled, brain still works via exact keys
-}
-
-export const EMBED_PROVIDER = (process.env.CACHLY_EMBED_PROVIDER ?? detectEmbedProvider()).toLowerCase();
-
-// ── Multi-provider embedding ─────────────────────────────────────────────────
-
-/**
- * Compute an embedding vector for `text` using the configured provider.
- *
- * Client-side (recommended — set one API key in your .env):
- *   openai   – OPENAI_API_KEY  · text-embedding-3-small
- *   gemini   – GEMINI_API_KEY  · text-embedding-004
- *   mistral  – MISTRAL_API_KEY · mistral-embed
- *   cohere   – COHERE_API_KEY  · embed-english-v3.0
- *   ollama   – OLLAMA_BASE_URL · nomic-embed-text (local, free)
- *
- * Server-side fallback (no key needed on client):
- *   cachly   – POST /api/v1/embed (requires CACHLY_JWT)
- *
- * Note: Brain works fully WITHOUT embedding (keyword search + exact keys).
- *       Embedding is an OPTIONAL boost for semantic_search and index_project.
- */
-export async function computeEmbedding(text: string): Promise<number[]> {
-  switch (EMBED_PROVIDER) {
-    case 'cachly': {
-      // Server-side embedding — the Cachly API computes the embedding
-      // using whatever provider is configured on the server. No client-side API key needed.
-      if (!embedConfig.jwt) throw new Error(
-        'CACHLY_JWT not set.\n\n' +
-        'The "cachly" provider uses server-side embeddings via the Cachly API.\n' +
-        'Set CACHLY_JWT, or use another provider via CACHLY_EMBED_PROVIDER:\n' +
-        '  openai  → OPENAI_API_KEY\n' +
-        '  gemini  → GEMINI_API_KEY\n' +
-        '  ollama  → OLLAMA_BASE_URL (local, no key needed)'
-      );
-      const url = `${embedConfig.apiUrl}/api/v1/embed`;
-      const body: Record<string, string> = { text };
-      if (embedConfig.model) body.model = embedConfig.model;
-      const res = await fetch(url, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'Authorization': `Bearer ${embedConfig.jwt}`,
-        },
-        body: JSON.stringify(body),
-      });
-      if (!res.ok) {
-        const errBody = await res.text();
-        throw new Error(`Cachly embed API error ${res.status}: ${errBody}`);
-      }
-      const json = (await res.json()) as { embedding: number[]; dimensions: number };
-      return json.embedding;
-    }
-
-    case 'mistral': {
-      const key = process.env.MISTRAL_API_KEY;
-      if (!key) throw new Error('MISTRAL_API_KEY not set');
-      const model = embedConfig.model !== 'text-embedding-3-small' ? embedConfig.model : 'mistral-embed';
-      const res = await fetch('https://api.mistral.ai/v1/embeddings', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${key}` },
-        body: JSON.stringify({ model, input: [text] }),
-      });
-      if (!res.ok) throw new Error(`Mistral embedding error: ${res.statusText}`);
-      const json = (await res.json()) as { data: { embedding: number[] }[] };
-      if (!json.data?.[0]?.embedding) throw new Error('Mistral returned empty embedding response');
-      return json.data[0].embedding;
-    }
-
-    case 'cohere': {
-      const key = process.env.COHERE_API_KEY;
-      if (!key) throw new Error('COHERE_API_KEY not set');
-      const model = embedConfig.model !== 'text-embedding-3-small' ? embedConfig.model : 'embed-english-v3.0';
-      const res = await fetch('https://api.cohere.com/v2/embed', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${key}` },
-        body: JSON.stringify({ model, texts: [text], input_type: 'search_query', embedding_types: ['float'] }),
-      });
-      if (!res.ok) throw new Error(`Cohere embedding error: ${res.statusText}`);
-      const json = (await res.json()) as { embeddings: { float: number[][] } };
-      return json.embeddings.float[0];
-    }
-
-    case 'ollama': {
-      const base = process.env.OLLAMA_BASE_URL ?? 'http://localhost:11434';
-      const model = embedConfig.model !== 'text-embedding-3-small' ? embedConfig.model : 'nomic-embed-text';
-      const res = await fetch(`${base}/api/embeddings`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ model, prompt: text }),
-      });
-      if (!res.ok) throw new Error(`Ollama embedding error: ${res.statusText}`);
-      const json = (await res.json()) as { embedding: number[] };
-      return json.embedding;
-    }
-
-    case 'gemini': {
-      const key = process.env.GEMINI_API_KEY;
-      if (!key) throw new Error('GEMINI_API_KEY not set');
-      const model = embedConfig.model !== 'text-embedding-3-small' ? embedConfig.model : 'text-embedding-004';
-      const res = await fetch(
-        `https://generativelanguage.googleapis.com/v1beta/models/${model}:embedContent?key=${key}`,
-        {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ model: `models/${model}`, content: { parts: [{ text }] } }),
-        },
-      );
-      if (!res.ok) throw new Error(`Gemini embedding error: ${res.statusText}`);
-      const json = (await res.json()) as { embedding: { values: number[] } };
-      return json.embedding.values;
-    }
-
-    case 'openai': {
-      const key = process.env.OPENAI_API_KEY;
-      if (!key) throw new Error(
-        'OPENAI_API_KEY not set.\n\n' +
-        'Set OPENAI_API_KEY in your .env, or switch provider:\n' +
-        '  CACHLY_EMBED_PROVIDER=gemini  (+ GEMINI_API_KEY)\n' +
-        '  CACHLY_EMBED_PROVIDER=ollama  (local, free)\n' +
-        '  CACHLY_EMBED_PROVIDER=cachly  (server-side, no key needed)'
-      );
-      const model = embedConfig.model || 'text-embedding-3-small';
-      const res = await fetch('https://api.openai.com/v1/embeddings', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${key}` },
-        body: JSON.stringify({ model, input: text }),
-      });
-      if (!res.ok) throw new Error(`OpenAI embedding error: ${res.statusText}`);
-      const json = (await res.json()) as { data: { embedding: number[] }[] };
-      if (!json.data?.[0]?.embedding) throw new Error('OpenAI returned empty embedding response');
-      return json.data[0].embedding;
-    }
-
-    default: {
-      throw new Error(
-        `Unknown CACHLY_EMBED_PROVIDER="${EMBED_PROVIDER}".\n` +
-        'Supported: cachly (default), openai, mistral, cohere, ollama, gemini'
-      );
-    }
-  }
-}
-
-/** Returns true if the configured embedding provider has its required key/URL set. */
-export function hasEmbedProvider(): boolean {
-  switch (EMBED_PROVIDER) {
-    case 'cachly':  return !!embedConfig.jwt;
-    case 'mistral': return !!process.env.MISTRAL_API_KEY;
-    case 'cohere':  return !!process.env.COHERE_API_KEY;
-    case 'ollama':  return true; // OLLAMA_BASE_URL is optional (defaults to localhost)
-    case 'gemini':  return !!process.env.GEMINI_API_KEY;
-    case 'openai':  return !!process.env.OPENAI_API_KEY;
-    case 'none':    return false;
-    default:        return false;
-  }
-}
-
-/** Returns a human-readable description of the current embed provider/model for error messages. */
-export function embedProviderHint(): string {
-  const providerKeys: Record<string, string> = {
-    cachly: 'CACHLY_JWT (server-side, no extra key needed)',
-    openai: 'OPENAI_API_KEY',
-    mistral: 'MISTRAL_API_KEY',
-    cohere: 'COHERE_API_KEY',
-    ollama: 'OLLAMA_BASE_URL (optional, default: http://localhost:11434)',
-    gemini: 'GEMINI_API_KEY',
-  };
-  if (EMBED_PROVIDER === 'none') {
-    return 'No embedding provider configured. Set OPENAI_API_KEY, GEMINI_API_KEY, or another provider key in .env. Brain works without embedding.';
-  }
-  const key = providerKeys[EMBED_PROVIDER] ?? 'CACHLY_JWT';
-  return `CACHLY_EMBED_PROVIDER=${EMBED_PROVIDER} → requires ${key}`;
-}