r2mcp 0.2.0

package/dist/edges/classifier.js

@@ -0,0 +1,172 @@
+import { pairHash } from './state.js';
+import { Semaphore } from '../providers/semaphore.js';
+// Conservative pre-call cost estimates per stage (USD).
+// Ground truth lives in AnthropicProvider.priceForTokens; revisit if pricing changes.
+const STAGE1_EST_COST_USD = 0.0005;
+const STAGE2_EST_COST_USD = 0.04;
+export async function runClassifier(opts, deps) {
+    const startedAt = new Date().toISOString();
+    const candidates = await deps.findCandidatePairs({ sinceDays: opts.sinceDays });
+    // Resume: skip terminal pair_hashes
+    const terminals = await deps.state.terminalPairs(opts.runId);
+    const counters = {
+        stage1Total: 0,
+        stage1Pass: 0,
+        stage1Skip: 0,
+        stage2Total: 0,
+        stage2Classified: 0,
+        edgesWritten: 0,
+        totalCost: 0,
+        hitCap: false,
+    };
+    if (opts.dryRun) {
+        let estimate = 0;
+        if (deps.estimateCost) {
+            estimate = await deps.estimateCost(candidates);
+        }
+        else {
+            estimate = candidates.length * 0.018;
+        }
+        process.stdout.write(`Estimated cost for full run: $${estimate.toFixed(2)} (${candidates.length} candidate pairs after pre-filter)\n`);
+        return {
+            run_id: opts.runId,
+            started_at: startedAt,
+            ended_at: new Date().toISOString(),
+            candidate_pairs: candidates.length,
+            stage1_total: 0,
+            stage1_pass: 0,
+            stage1_skip: 0,
+            stage2_total: 0,
+            stage2_classified: 0,
+            edges_written: 0,
+            total_cost_usd: 0,
+            hit_cost_cap: false,
+            provider: deps.providerName,
+        };
+    }
+    await deps.state.markActiveRun(opts.runId);
+    const concurrency = Math.max(1, deps.concurrencyLimit ?? 1);
+    const semaphore = new Semaphore(concurrency);
+    const inFlight = new Set();
+    const launch = (cand) => {
+        const task = semaphore.withPermit(() => processPair(cand, opts, deps, counters, terminals));
+        inFlight.add(task);
+        void task.finally(() => inFlight.delete(task));
+        return task;
+    };
+    // Dispatcher loop — keep up to `concurrency` pairs in flight at once.
+    for (const cand of candidates) {
+        if (counters.hitCap)
+            break;
+        if (inFlight.size >= concurrency) {
+            await Promise.race(inFlight);
+        }
+        if (counters.hitCap)
+            break;
+        launch(cand);
+    }
+    await Promise.all([...inFlight]);
+    if (counters.hitCap) {
+        process.stdout.write(`Cost cap reached at $${counters.totalCost.toFixed(4)}. Resume with: npm run edges:classify -- --resume=${opts.runId}\n`);
+    }
+    const summary = {
+        run_id: opts.runId,
+        started_at: startedAt,
+        ended_at: new Date().toISOString(),
+        candidate_pairs: candidates.length,
+        stage1_total: counters.stage1Total,
+        stage1_pass: counters.stage1Pass,
+        stage1_skip: counters.stage1Skip,
+        stage2_total: counters.stage2Total,
+        stage2_classified: counters.stage2Classified,
+        edges_written: counters.edgesWritten,
+        total_cost_usd: counters.totalCost,
+        hit_cost_cap: counters.hitCap,
+        provider: deps.providerName,
+    };
+    await deps.summaryWriter.write(summary);
+    return summary;
+}
+async function processPair(cand, opts, deps, counters, terminals) {
+    if (counters.hitCap)
+        return;
+    const ph = pairHash(cand.from_id, cand.to_id);
+    if (terminals.has(ph))
+        return;
+    const fromMem = await deps.fetchMemoryById(cand.from_id);
+    const toMem = await deps.fetchMemoryById(cand.to_id);
+    if (!fromMem || !toMem)
+        return;
+    // Pre-call cap check for Stage 1. Approximate under concurrency.
+    if (counters.totalCost + STAGE1_EST_COST_USD > opts.maxCostUsd) {
+        counters.hitCap = true;
+        await deps.state.append({
+            run_id: opts.runId,
+            pair_hash: ph,
+            stage: 'cap_reached',
+            timestamp: new Date().toISOString(),
+        });
+        return;
+    }
+    counters.stage1Total++;
+    const s1 = await deps.stage1Filter({ from: fromMem, to: toMem });
+    counters.totalCost += s1.cost_usd;
+    if (!s1.pass) {
+        counters.stage1Skip++;
+        await deps.state.append({
+            run_id: opts.runId,
+            pair_hash: ph,
+            stage: 'haiku_skip',
+            timestamp: new Date().toISOString(),
+            cost_usd: s1.cost_usd,
+        });
+        return;
+    }
+    counters.stage1Pass++;
+    await deps.state.append({
+        run_id: opts.runId,
+        pair_hash: ph,
+        stage: 'haiku_pass',
+        timestamp: new Date().toISOString(),
+        cost_usd: s1.cost_usd,
+    });
+    // Pre-call cap check for Stage 2.
+    if (counters.totalCost + STAGE2_EST_COST_USD > opts.maxCostUsd) {
+        counters.hitCap = true;
+        await deps.state.append({
+            run_id: opts.runId,
+            pair_hash: ph,
+            stage: 'cap_reached',
+            timestamp: new Date().toISOString(),
+        });
+        return;
+    }
+    counters.stage2Total++;
+    const s2 = await deps.stage2Classify({ from: fromMem, to: toMem });
+    counters.totalCost += s2.cost_usd;
+    counters.stage2Classified++;
+    if (s2.downgraded) {
+        process.stdout.write(`AC10 GUARD: downgraded contradicts→none for rejection pair {${fromMem.id} (${fromMem.type})}, {${toMem.id} (${toMem.type})}\n`);
+    }
+    if (s2.relation !== 'none' && s2.confidence > 0) {
+        const edgeId = await deps.insertEdge(fromMem.id, toMem.id, s2.relation, s2.confidence, s2.rationale, deps.classifierVersion);
+        counters.edgesWritten++;
+        await deps.state.append({
+            run_id: opts.runId,
+            pair_hash: ph,
+            stage: 'opus_complete',
+            timestamp: new Date().toISOString(),
+            cost_usd: s2.cost_usd,
+            edge_id: edgeId,
+        });
+    }
+    else {
+        await deps.state.append({
+            run_id: opts.runId,
+            pair_hash: ph,
+            stage: 'opus_complete',
+            timestamp: new Date().toISOString(),
+            cost_usd: s2.cost_usd,
+        });
+    }
+}

package/dist/edges/signals.d.ts

@@ -0,0 +1,13 @@
+import type pg from 'pg';
+import type { RecallSignal } from './types.js';
+/**
+ * Build the signals[] array for a recall response. For every returned memory ID:
+ * - emit a `contradicts` signal for each outgoing `contradicts` edge
+ * - emit a `superseded_by` signal for each outgoing `supersedes` edge (returned memory is the newer one; signal's `from_id` will be the DB row's `to_memory_id`)
+ *   AND for each incoming `supersedes` edge (returned memory is the older one; signal's `from_id` will be its own ID)
+ *
+ * Direction semantics: in the DB, `(from=newer, to=older, relation=supersedes)` means
+ * "newer supersedes older". The recall signal `superseded_by` always points
+ * from the older memory to the newer one, regardless of which side appeared in results[].
+ */
+export declare function getSignalsForMemoryIds(pool: pg.Pool, memoryIds: string[]): Promise<RecallSignal[]>;

package/dist/edges/signals.js

@@ -0,0 +1,45 @@
+/**
+ * Build the signals[] array for a recall response. For every returned memory ID:
+ * - emit a `contradicts` signal for each outgoing `contradicts` edge
+ * - emit a `superseded_by` signal for each outgoing `supersedes` edge (returned memory is the newer one; signal's `from_id` will be the DB row's `to_memory_id`)
+ *   AND for each incoming `supersedes` edge (returned memory is the older one; signal's `from_id` will be its own ID)
+ *
+ * Direction semantics: in the DB, `(from=newer, to=older, relation=supersedes)` means
+ * "newer supersedes older". The recall signal `superseded_by` always points
+ * from the older memory to the newer one, regardless of which side appeared in results[].
+ */
+export async function getSignalsForMemoryIds(pool, memoryIds) {
+    if (memoryIds.length === 0)
+        return [];
+    // Outgoing contradicts (memory in results -> some other memory)
+    const contradictsRes = await pool.query(`SELECT from_memory_id, to_memory_id, rationale, confidence
+     FROM memory_edges
+     WHERE from_memory_id = ANY($1) AND relation = 'contradicts' AND valid_until IS NULL`, [memoryIds]);
+    // Supersession: surface in either direction so the consumer always sees it
+    const supersedesRes = await pool.query(`SELECT from_memory_id, to_memory_id, rationale, confidence
+     FROM memory_edges
+     WHERE (from_memory_id = ANY($1) OR to_memory_id = ANY($1))
+       AND relation = 'supersedes' AND valid_until IS NULL`, [memoryIds]);
+    const signals = [];
+    for (const row of contradictsRes.rows) {
+        signals.push({
+            kind: 'contradicts',
+            from_id: row.from_memory_id,
+            to_id: row.to_memory_id,
+            rationale: row.rationale,
+            confidence: Number(row.confidence),
+        });
+    }
+    for (const row of supersedesRes.rows) {
+        // DB: from=newer, to=older (per classifier convention)
+        // Signal: from=older, to=newer (per spec AC8 — "from_id is older")
+        signals.push({
+            kind: 'superseded_by',
+            from_id: row.to_memory_id,
+            to_id: row.from_memory_id,
+            rationale: row.rationale,
+            confidence: Number(row.confidence),
+        });
+    }
+    return signals;
+}

package/dist/edges/stage1-haiku.d.ts

@@ -0,0 +1,21 @@
+import type { LLMProvider } from '../providers/types.js';
+export interface PairForFilter {
+    from: {
+        id: string;
+        content: string;
+    };
+    to: {
+        id: string;
+        content: string;
+    };
+}
+export interface Stage1Result {
+    pass: boolean;
+    comment: string;
+    cost_usd: number;
+}
+export declare function parseStage1Response(text: string): {
+    pass: boolean;
+    comment: string;
+};
+export declare function stage1HaikuFilter(provider: LLMProvider, pair: PairForFilter): Promise<Stage1Result>;

package/dist/edges/stage1-haiku.js

@@ -0,0 +1,33 @@
+import { withLLMCallSpan } from '../telemetry.js';
+const STAGE1_SYSTEM = `You are a filter that decides whether two memories MIGHT have a meaningful structural relation worth deeper analysis.
+
+Reply with one line in this exact format:
+  YES — <brief reason>
+  NO — <brief reason>
+
+Say YES if the two memories appear to make claims about overlapping things — e.g., they recommend or contradict each other on the same subject, one is a refinement of the other, or one depends on the other. Say NO if they describe distinct, non-conflicting things despite sharing topic tags. Reply with ONLY the single line — no other text.`;
+const STAGE1_MAX_OUTPUT_TOKENS = 64;
+export function parseStage1Response(text) {
+    const trimmed = text.trim();
+    const match = trimmed.match(/^(YES|NO)(?:\s*[—\-:]\s*(.*))?$/i);
+    if (!match) {
+        throw new Error(`Stage 1 response not parseable: ${JSON.stringify(text)}`);
+    }
+    return {
+        pass: match[1].toUpperCase() === 'YES',
+        comment: (match[2] ?? '').trim(),
+    };
+}
+export async function stage1HaikuFilter(provider, pair) {
+    const userPrompt = `Memory A (id=${pair.from.id}): ${pair.from.content}\n\nMemory B (id=${pair.to.id}): ${pair.to.content}`;
+    // claw-1ejd: wrap the LLM call so the parent OTEL_TRACEPARENT context
+    // has a concrete child span to inherit when this runs as a subprocess.
+    const result = await withLLMCallSpan('memory.classify_edges.call', { provider: provider.name, model: 'haiku' }, () => provider.complete({
+        model: 'haiku',
+        system: STAGE1_SYSTEM,
+        prompt: userPrompt,
+        max_tokens: STAGE1_MAX_OUTPUT_TOKENS,
+    }));
+    const parsed = parseStage1Response(result.response);
+    return { pass: parsed.pass, comment: parsed.comment, cost_usd: result.cost_usd };
+}

package/dist/edges/stage2-opus.d.ts

@@ -0,0 +1,41 @@
+import type { LLMProvider } from '../providers/types.js';
+import type { EdgeRelation } from './types.js';
+export interface MemoryForClassify {
+    id: string;
+    content: string;
+    type: string;
+}
+export interface PairForClassify {
+    from: MemoryForClassify;
+    to: MemoryForClassify;
+}
+export type Stage2Result = {
+    kind: 'classified';
+    relation: EdgeRelation | 'none';
+    confidence: number;
+    rationale: string;
+    cost_usd: number;
+    downgraded?: boolean;
+};
+export declare const STAGE2_RELATIONS: ReadonlyArray<EdgeRelation | 'none'>;
+/**
+ * AC10: rejection-typed memories are out-of-vocabulary for the `contradicts` relation
+ * (a rejection is a meta-statement, not a factual claim). They CAN participate in
+ * other relations like related_to, evolved_into, supersedes — a rejection often
+ * pairs with a preference saying the same thing in positive form.
+ *
+ * Used by stage2OpusClassify as a post-call guard: if the LLM returns "contradicts"
+ * for a rejection pair (despite being instructed otherwise in the system prompt),
+ * the result is downgraded to "none".
+ */
+export declare function isRejectionPair(a: {
+    type: string;
+}, b: {
+    type: string;
+}): boolean;
+export declare function parseStage2Response(text: string): {
+    relation: EdgeRelation | 'none';
+    confidence: number;
+    rationale: string;
+};
+export declare function stage2OpusClassify(provider: LLMProvider, pair: PairForClassify): Promise<Stage2Result>;

package/dist/edges/stage2-opus.js

@@ -0,0 +1,101 @@
+import { withLLMCallSpan } from '../telemetry.js';
+export const STAGE2_RELATIONS = [
+    'supports',
+    'contradicts',
+    'supersedes',
+    'evolved_into',
+    'depends_on',
+    'related_to',
+    'none',
+];
+const STAGE2_SYSTEM = `You classify the structural relation between two memories. Respond with JSON only.
+
+Possible relations:
+  - supports: B reinforces or is consistent with A
+  - contradicts: A and B make conflicting factual claims about the same subject
+  - supersedes: A explicitly replaces B as the current framing (newer A, older B)
+  - evolved_into: A is a refined version of B with the same core intent
+  - depends_on: A presupposes B's truth
+  - related_to: A and B are about the same general topic but no stronger relation applies
+  - none: no meaningful relation
+
+Use "supersedes" with from=A=newer, to=B=older.
+
+Use "contradicts" only for genuinely conflicting claims. Do NOT mark superseded pairs as contradictions.
+
+Rejection-typed memories rule: if memory A or B has type=rejection, you must NOT use "contradicts". A rejection ("don't do X") is a meta-statement about what to avoid, not a factual claim that can conflict with another claim. For rejection-involving pairs, prefer "related_to", "evolved_into", "supersedes", "depends_on", or "none".
+
+Avoid "related_to" unless you are sure no stronger relation fits — it is the weakest signal.
+
+Reply with a single JSON object: {"relation": <one of the seven>, "confidence": <0..1>, "rationale": "<one sentence>"}`;
+const STAGE2_MAX_OUTPUT_TOKENS = 256;
+/**
+ * AC10: rejection-typed memories are out-of-vocabulary for the `contradicts` relation
+ * (a rejection is a meta-statement, not a factual claim). They CAN participate in
+ * other relations like related_to, evolved_into, supersedes — a rejection often
+ * pairs with a preference saying the same thing in positive form.
+ *
+ * Used by stage2OpusClassify as a post-call guard: if the LLM returns "contradicts"
+ * for a rejection pair (despite being instructed otherwise in the system prompt),
+ * the result is downgraded to "none".
+ */
+export function isRejectionPair(a, b) {
+    return a.type === 'rejection' || b.type === 'rejection';
+}
+export function parseStage2Response(text) {
+    // Strip optional ```json fences
+    const cleaned = text
+        .trim()
+        .replace(/^```(?:json)?\s*/, '')
+        .replace(/\s*```\s*$/, '')
+        .trim();
+    let parsed;
+    try {
+        parsed = JSON.parse(cleaned);
+    }
+    catch {
+        throw new Error(`Stage 2 response is not JSON: ${JSON.stringify(text).slice(0, 200)}`);
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        throw new Error('Stage 2 response is not an object');
+    }
+    const obj = parsed;
+    const relation = String(obj.relation ?? '').toLowerCase();
+    if (!STAGE2_RELATIONS.includes(relation)) {
+        throw new Error(`Stage 2 returned invalid relation: ${obj.relation}`);
+    }
+    const confidence = Number(obj.confidence ?? 0);
+    const rationale = String(obj.rationale ?? '').trim();
+    return { relation, confidence, rationale };
+}
+export async function stage2OpusClassify(provider, pair) {
+    const userPrompt = `Memory A (id=${pair.from.id}, type=${pair.from.type}): ${pair.from.content}\n\nMemory B (id=${pair.to.id}, type=${pair.to.type}): ${pair.to.content}`;
+    // claw-1ejd: wrap the LLM call so the parent OTEL_TRACEPARENT context
+    // has a concrete child span to inherit when this runs as a subprocess.
+    const result = await withLLMCallSpan('memory.classify_edges.call', { provider: provider.name, model: 'opus' }, () => provider.complete({
+        model: 'opus',
+        system: STAGE2_SYSTEM,
+        prompt: userPrompt,
+        max_tokens: STAGE2_MAX_OUTPUT_TOKENS,
+    }));
+    const parsed = parseStage2Response(result.response);
+    // AC10 guard: if the LLM returns contradicts despite being told not to for rejection
+    // pairs, downgrade to 'none'. The system prompt is the primary defense; this is a fallback.
+    if (parsed.relation === 'contradicts' && isRejectionPair(pair.from, pair.to)) {
+        return {
+            kind: 'classified',
+            relation: 'none',
+            confidence: parsed.confidence,
+            rationale: `[AC10] downgraded contradicts→none for rejection pair; original rationale: ${parsed.rationale}`,
+            cost_usd: result.cost_usd,
+            downgraded: true,
+        };
+    }
+    return {
+        kind: 'classified',
+        relation: parsed.relation,
+        confidence: parsed.confidence,
+        rationale: parsed.rationale,
+        cost_usd: result.cost_usd,
+    };
+}

package/dist/edges/state.d.ts

@@ -0,0 +1,44 @@
+export interface StageRecord {
+    run_id: string;
+    pair_hash: string;
+    stage: 'haiku_pass' | 'haiku_skip' | 'opus_complete' | 'cap_reached' | 'rejection_skip';
+    timestamp: string;
+    cost_usd?: number;
+    edge_id?: string;
+}
+export declare function pairHash(idA: string, idB: string): string;
+export declare class StateStore {
+    private readonly path;
+    private readonly lastRunPath?;
+    constructor(path: string, lastRunPath?: string | undefined);
+    append(record: StageRecord): Promise<void>;
+    markActiveRun(runId: string): Promise<void>;
+    /**
+     * Read all terminal stage records for a run_id, returning the set of pair_hashes
+     * that should NOT be re-classified on resume. Tolerates a truncated final line
+     * (jsonl partial write from a hard kill).
+     */
+    terminalPairs(runId: string): Promise<Set<string>>;
+}
+export interface RunSummary {
+    run_id: string;
+    started_at: string;
+    ended_at: string;
+    candidate_pairs: number;
+    stage1_total: number;
+    stage1_pass: number;
+    stage1_skip: number;
+    stage2_total: number;
+    stage2_classified: number;
+    edges_written: number;
+    total_cost_usd: number;
+    hit_cost_cap: boolean;
+    error?: string;
+    /** Active LLM provider (D.R3, surfaces in run summary). */
+    provider?: string;
+}
+export declare class RunSummaryWriter {
+    private readonly dir;
+    constructor(dir: string);
+    write(summary: RunSummary): Promise<string>;
+}

package/dist/edges/state.js

@@ -0,0 +1,79 @@
+import { createHash } from 'node:crypto';
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const TERMINAL_STAGES = new Set([
+    'opus_complete',
+    'haiku_skip',
+    'cap_reached',
+    'rejection_skip',
+]);
+export function pairHash(idA, idB) {
+    const [first, second] = [idA, idB].sort();
+    return createHash('sha256').update(`${first}|${second}`).digest('hex').slice(0, 16);
+}
+export class StateStore {
+    path;
+    lastRunPath;
+    constructor(path, lastRunPath) {
+        this.path = path;
+        this.lastRunPath = lastRunPath;
+    }
+    async append(record) {
+        await mkdir(dirname(this.path), { recursive: true });
+        await appendFile(this.path, JSON.stringify(record) + '\n', 'utf-8');
+    }
+    async markActiveRun(runId) {
+        if (!this.lastRunPath)
+            return;
+        await mkdir(dirname(this.lastRunPath), { recursive: true });
+        await writeFile(this.lastRunPath, runId, 'utf-8');
+    }
+    /**
+     * Read all terminal stage records for a run_id, returning the set of pair_hashes
+     * that should NOT be re-classified on resume. Tolerates a truncated final line
+     * (jsonl partial write from a hard kill).
+     */
+    async terminalPairs(runId) {
+        if (!existsSync(this.path))
+            return new Set();
+        const raw = await readFile(this.path, 'utf-8');
+        const lines = raw.split('\n');
+        const terminals = new Set();
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (!line)
+                continue;
+            // The final element of split is '' when the file ends in '\n' (good).
+            // If the file does NOT end in '\n', the final element is a partial line —
+            // skip it because it was truncated mid-write.
+            if (i === lines.length - 1 && !raw.endsWith('\n'))
+                continue;
+            try {
+                const rec = JSON.parse(line);
+                if (rec.run_id !== runId)
+                    continue;
+                if (TERMINAL_STAGES.has(rec.stage)) {
+                    terminals.add(rec.pair_hash);
+                }
+            }
+            catch {
+                // Defensive: skip malformed line rather than crash on resume
+                continue;
+            }
+        }
+        return terminals;
+    }
+}
+export class RunSummaryWriter {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    async write(summary) {
+        await mkdir(this.dir, { recursive: true });
+        const path = join(this.dir, `${summary.run_id}.json`);
+        await writeFile(path, JSON.stringify(summary, null, 2), 'utf-8');
+        return path;
+    }
+}

package/dist/edges/types.d.ts

@@ -0,0 +1,20 @@
+export type EdgeRelation = 'supports' | 'contradicts' | 'supersedes' | 'evolved_into' | 'depends_on' | 'related_to';
+export interface MemoryEdge {
+    id: string;
+    from_memory_id: string;
+    to_memory_id: string;
+    relation: EdgeRelation;
+    confidence: number;
+    rationale: string;
+    classifier_version: string;
+    valid_from: Date;
+    valid_until: Date | null;
+}
+export type SignalKind = 'contradicts' | 'superseded_by';
+export interface RecallSignal {
+    kind: SignalKind;
+    from_id: string;
+    to_id: string;
+    rationale: string;
+    confidence: number;
+}

package/dist/edges/types.js

@@ -0,0 +1 @@
+export {};

package/dist/embeddings.d.ts

@@ -0,0 +1,13 @@
+/**
+ * claw-8cjf.2: a null embedding must be explainable in tool responses instead
+ * of silently degrading the headline semantic-search feature.
+ */
+export declare const EMBEDDINGS_DISABLED_WARNING: string;
+export declare const EMBEDDING_FAILED_WARNING: string;
+/**
+ * Explains a null embedding: disabled (no key) vs failed (key present).
+ * Returns null when the embedding is present — no warning needed.
+ */
+export declare function embeddingWarning(embedding: ReadonlyArray<number> | null): string | null;
+export declare function embedBatch(texts: string[], model?: string): Promise<number[][] | null>;
+export declare function embedText(text: string, model?: string): Promise<number[] | null>;

package/dist/embeddings.js

@@ -0,0 +1,54 @@
+import { withEmbeddingSpan } from './telemetry.js';
+const OPENROUTER_URL = 'https://openrouter.ai/api/v1/embeddings';
+const DEFAULT_MODEL = 'openai/text-embedding-3-small';
+/**
+ * claw-8cjf.2: a null embedding must be explainable in tool responses instead
+ * of silently degrading the headline semantic-search feature.
+ */
+export const EMBEDDINGS_DISABLED_WARNING = 'embeddings disabled: R2MCP_OPENROUTER_API_KEY is not set — memories store without ' +
+    'embeddings and recall falls back to full-text. Set it in your .mcp.json "env" block ' +
+    'or .env to enable semantic search.';
+export const EMBEDDING_FAILED_WARNING = 'embedding generation failed (see server stderr for the OpenRouter error) — this ' +
+    'operation completed without an embedding; re-saving the content later will backfill it.';
+/**
+ * Explains a null embedding: disabled (no key) vs failed (key present).
+ * Returns null when the embedding is present — no warning needed.
+ */
+export function embeddingWarning(embedding) {
+    if (embedding !== null)
+        return null;
+    return process.env.R2MCP_OPENROUTER_API_KEY
+        ? EMBEDDING_FAILED_WARNING
+        : EMBEDDINGS_DISABLED_WARNING;
+}
+export async function embedBatch(texts, model = DEFAULT_MODEL) {
+    const apiKey = process.env.R2MCP_OPENROUTER_API_KEY;
+    if (!apiKey) {
+        return null;
+    }
+    const totalChars = texts.reduce((sum, t) => sum + t.length, 0);
+    return withEmbeddingSpan(texts.length, async () => {
+        const res = await fetch(OPENROUTER_URL, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${apiKey}`,
+                'HTTP-Referer': 'https://github.com/DMokong/r2mcp',
+                'X-Title': 'r2mcp',
+            },
+            body: JSON.stringify({ model, input: texts }),
+        });
+        if (!res.ok) {
+            console.error(`OpenRouter embedding error ${res.status}: ${await res.text()}`);
+            return null;
+        }
+        const data = await res.json();
+        return data.data
+            .sort((a, b) => a.index - b.index)
+            .map((d) => d.embedding);
+    }, totalChars);
+}
+export async function embedText(text, model = DEFAULT_MODEL) {
+    const result = await embedBatch([text], model);
+    return result ? result[0] : null;
+}