@desplega.ai/agent-swarm 1.74.4 → 1.75.0

package/src/be/memory/raters/llm-client.ts

@@ -0,0 +1,172 @@
+/**
+ * `LlmRaterClient` — pluggable LLM driver used by `LlmRater` to score the
+ * usefulness of a single retrieved memory against a (query, response) pair.
+ *
+ * Plan: thoughts/taras/plans/2026-05-05-memory-rater-v1.5/step-4.md §1
+ *
+ * This module is imported from worker-side `src/hooks/hook.ts` (the session-
+ * summary piggyback path), so it MUST NOT touch `bun:sqlite` or `src/be/db`.
+ * The DB-boundary check in `scripts/check-db-boundary.sh` enforces this.
+ *
+ * Default implementation shells out to the same `claude -p` CLI the hook
+ * already uses for session summarization — zero new SDK dependencies.
+ */
+
+export type LlmRaterInput = {
+  /** What the agent asked the memory system for. */
+  query: string;
+  /** The memory we're scoring. */
+  memory: {
+    id: string;
+    name: string;
+    content: string;
+  };
+  /** The agent's eventual response (or session summary) — the "did this help?" signal. */
+  response: string;
+};
+
+export type LlmRaterResult = {
+  /** Usefulness score in [0, 1]. 0 = misleading, 1 = highly useful. */
+  score: number;
+  /** Short human-readable explanation. */
+  reasoning: string;
+};
+
+export interface LlmRaterClient {
+  /**
+   * Score one memory. Returns null on parse failure / non-JSON output / timeout
+   * — the caller (`LlmRater`) treats `null` as "skip this rating", no posterior
+   * change. Implementations MUST NOT throw on transport errors; swallow + log
+   * + return null so the worker hook can never crash on rater failure.
+   */
+  rate(input: LlmRaterInput): Promise<LlmRaterResult | null>;
+}
+
+/**
+ * Configuration for the Claude-CLI implementation.
+ */
+export type ClaudeCliLlmRaterClientOptions = {
+  /** Override the model. Defaults to `MEMORY_LLM_RATER_MODEL` env var or "haiku". */
+  model?: string;
+  /** Soft timeout (ms) for the `claude -p` shell-out. Default 30s. */
+  timeoutMs?: number;
+};
+
+const DEFAULT_TIMEOUT_MS = 30000;
+
+const PROMPT_TEMPLATE = `You are scoring the usefulness of one retrieved memory.
+
+Return ONLY a JSON object with these fields (no prose, no markdown):
+{
+  "score": number,        // 0 = misleading/unhelpful, 1 = highly useful
+  "reasoning": string     // 1..500 chars, why
+}
+
+QUERY:
+\${query}
+
+MEMORY:
+id: \${memoryId}
+name: \${memoryName}
+content: \${memoryContent}
+
+AGENT RESPONSE / SUMMARY:
+\${response}
+
+Score 0..1.`;
+
+/**
+ * `claude -p --output-format json` returns a JSON envelope of the shape
+ * `{ result: string, ... }`. We parse the envelope, then JSON-parse the
+ * inner `result` to recover the score+reasoning object.
+ */
+type ClaudeCliEnvelope = { result?: unknown };
+
+function buildPrompt(input: LlmRaterInput): string {
+  return PROMPT_TEMPLATE.replace("${query}", input.query)
+    .replace("${memoryId}", input.memory.id)
+    .replace("${memoryName}", input.memory.name)
+    .replace("${memoryContent}", input.memory.content)
+    .replace("${response}", input.response);
+}
+
+function parseScoreAndReasoning(raw: unknown): LlmRaterResult | null {
+  if (typeof raw !== "string") return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw.trim());
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const obj = parsed as { score?: unknown; reasoning?: unknown };
+  const score = typeof obj.score === "number" ? obj.score : null;
+  const reasoning = typeof obj.reasoning === "string" ? obj.reasoning : null;
+  if (score == null || reasoning == null) return null;
+  if (!Number.isFinite(score) || score < 0 || score > 1) return null;
+  if (reasoning.length === 0 || reasoning.length > 500) return null;
+  return { score, reasoning };
+}
+
+export class ClaudeCliLlmRaterClient implements LlmRaterClient {
+  private readonly model: string;
+  private readonly timeoutMs: number;
+
+  constructor(opts: ClaudeCliLlmRaterClientOptions = {}) {
+    this.model = opts.model ?? process.env.MEMORY_LLM_RATER_MODEL ?? "haiku";
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  }
+
+  async rate(input: LlmRaterInput): Promise<LlmRaterResult | null> {
+    const prompt = buildPrompt(input);
+    const tmpFile = `/tmp/llm-rater-${Date.now()}-${Math.random().toString(36).slice(2)}.txt`;
+
+    let stdout = "";
+    try {
+      await Bun.write(tmpFile, prompt);
+      const proc = Bun.spawn(
+        ["bash", "-c", `cat "${tmpFile}" | claude -p --model ${this.model} --output-format json`],
+        {
+          stdout: "pipe",
+          stderr: "pipe",
+          env: { ...process.env, SKIP_SESSION_SUMMARY: "1" },
+        },
+      );
+      const timeoutId = setTimeout(() => proc.kill(), this.timeoutMs);
+      stdout = await new Response(proc.stdout).text();
+      clearTimeout(timeoutId);
+    } catch (err) {
+      console.error("[memory-rater:llm] claude -p shell-out failed:", (err as Error).message);
+      return null;
+    } finally {
+      try {
+        await Bun.$`rm -f ${tmpFile}`.quiet();
+      } catch {
+        // best-effort
+      }
+    }
+
+    let envelope: ClaudeCliEnvelope;
+    try {
+      envelope = JSON.parse(stdout) as ClaudeCliEnvelope;
+    } catch {
+      return null;
+    }
+    return parseScoreAndReasoning(envelope.result);
+  }
+}
+
+/**
+ * Factory honouring `MEMORY_LLM_RATER_PROVIDER` — defaults to `claude-cli`.
+ * Unknown providers fall back to the Claude CLI default and log a warning so
+ * misconfiguration never crashes the worker.
+ */
+export function getDefaultLlmRaterClient(): LlmRaterClient {
+  const provider = (process.env.MEMORY_LLM_RATER_PROVIDER ?? "claude-cli").trim();
+  if (provider !== "claude-cli") {
+    console.warn(
+      `[memory-rater:llm] Unknown MEMORY_LLM_RATER_PROVIDER "${provider}" — falling back to claude-cli`,
+    );
+  }
+  return new ClaudeCliLlmRaterClient();
+}

package/src/be/memory/raters/llm.ts

@@ -0,0 +1,394 @@
+/**
+ * `LlmRater` — second live rater, source = "llm".
+ *
+ * Plan: thoughts/taras/plans/2026-05-05-memory-rater-v1.5/step-4.md §2-3
+ *
+ * The worker-side flow does NOT call `LlmRater.rate(ctx)` from the in-process
+ * server-rater orchestrator. Instead, the rating LLM call is piggybacked on
+ * the existing session-summary call in `src/hooks/hook.ts` (cost optimization
+ * — same Haiku invocation produces both summary text + per-memory ratings).
+ * The hook then POSTs the constructed `RatingEvent[]` to `/api/memory/rate`.
+ *
+ * `LlmRater.rate(ctx)` is wired up so the class still satisfies `MemoryRater`
+ * for registry consistency / future direct integrations / unit tests, but is
+ * never invoked by `runServerRaters` (LlmRater is NOT in `SERVER_RATERS`).
+ *
+ * This module is imported from worker-side `src/hooks/hook.ts` so it MUST NOT
+ * touch `bun:sqlite` or `src/be/db`. The boundary check enforces it.
+ */
+import { z } from "zod";
+import { ClaudeCliLlmRaterClient, type LlmRaterClient, type LlmRaterResult } from "./llm-client";
+import {
+  type MemoryRater,
+  type RatingContext,
+  type RatingEvent,
+  REFERENCES_SOURCE_MAX_LENGTH,
+  sanitizeReferencesSource,
+} from "./types";
+
+/**
+ * Per-rating weight, fixed at 0.8 per the research-doc convention
+ * ("LLM intent_weight"). Encoded here once so neither callers nor tests can
+ * silently drift the constant.
+ */
+export const LLM_RATER_WEIGHT = 0.8;
+
+const RatingSchema = z.object({
+  id: z.string().min(1),
+  score: z.number().min(0).max(1),
+  reasoning: z.string().min(1).max(500),
+  // Step-6 §6 — optional free-form external source ID. Q2 contract: ≤512
+  // chars, no closed enum, no prefix parser. Sanitization (control-char
+  // strip + NUL rejection) happens in `buildRatingsFromLlm` so a single
+  // bad rating drops the field rather than failing the whole batch.
+  referencesSource: z.string().min(1).max(REFERENCES_SOURCE_MAX_LENGTH).optional(),
+});
+
+/**
+ * Zod schema for the structured-output piggyback prompt. The hook asks the
+ * summarizer LLM to return summary + per-memory ratings in one JSON object so
+ * we don't pay for N additional LLM calls.
+ */
+export const SummaryWithRatingsSchema = z.object({
+  summary: z.string(),
+  ratings: z.array(RatingSchema).default([]),
+});
+
+export type LlmRating = z.infer<typeof RatingSchema>;
+export type SummaryWithRatings = z.infer<typeof SummaryWithRatingsSchema>;
+
+/** Context augmentations LlmRater consumes when called directly (per-memory path). */
+export type LlmRatingContext = RatingContext & {
+  /** What the agent asked the memory system. */
+  query?: string;
+  /** Final agent response / summary used as the "did this help?" signal. */
+  response?: string;
+  /** Snapshots for memories listed in `retrievedMemoryIds` (id-aligned by id). */
+  retrievedMemories?: { id: string; name: string; content: string }[];
+};
+
+export class LlmRater implements MemoryRater {
+  readonly name = "llm";
+
+  constructor(public readonly client: LlmRaterClient = new ClaudeCliLlmRaterClient()) {}
+
+  /**
+   * Per-memory scoring path. The production hook bypasses this method and
+   * calls {@link buildRatingsFromLlm} on the piggybacked summarizer JSON
+   * (one LLM invocation, not N). Direct callers (tests, future integrations)
+   * MUST pass {@link LlmRatingContext} — the base `RatingContext` carries
+   * only memory IDs, which is insufficient to drive `LlmRaterClient.rate`.
+   *
+   * Returns `[]` when the augmented fields are missing so the rater stays a
+   * no-op rather than crashing on a `RatingContext`-only invocation.
+   */
+  async rate(ctx: RatingContext): Promise<RatingEvent[]> {
+    const enriched = ctx as LlmRatingContext;
+    if (enriched.retrievedMemoryIds.length === 0) return [];
+    const memories = enriched.retrievedMemories;
+    if (!memories || memories.length === 0) return [];
+
+    const events: RatingEvent[] = [];
+    for (const memoryId of enriched.retrievedMemoryIds) {
+      const memory = memories.find((m) => m.id === memoryId);
+      if (!memory) continue;
+      let result: LlmRaterResult | null;
+      try {
+        result = await this.client.rate({
+          query: enriched.query ?? "",
+          memory,
+          response: enriched.response ?? enriched.evidence ?? "",
+        });
+      } catch (err) {
+        console.error(
+          `[memory-rater:llm] client.rate threw for memoryId=${memoryId}:`,
+          (err as Error).message,
+        );
+        continue;
+      }
+      if (!result) continue;
+      events.push({
+        memoryId,
+        signal: 2 * result.score - 1,
+        weight: LLM_RATER_WEIGHT,
+        // Framework stamps `source = rater.name` in `runServerRaters`. Raters
+        // that populate `source` themselves are rejected by `applyRating`.
+        source: "",
+        reasoning: result.reasoning,
+      });
+    }
+    return events;
+  }
+}
+
+/**
+ * Convert the piggybacked summary's `ratings` array into `RatingEvent[]` for
+ * `POST /api/memory/rate`. Drops ratings whose `id` was not in the original
+ * retrieval set (defence-in-depth — the LLM occasionally hallucinates memory
+ * IDs; the server-side R6 check catches it too, but rejecting upstream keeps
+ * the audit log cleaner).
+ *
+ * Mapping: `signal = 2 * score - 1` (0 → -1, 0.5 → 0, 1 → +1).
+ * Weight = {@link LLM_RATER_WEIGHT} (0.8).
+ * Source = `"llm"` (the HTTP rate endpoint enums `["llm", "explicit-self"]`).
+ */
+export function buildRatingsFromLlm(
+  ratings: LlmRating[],
+  retrievals: { id: string }[],
+): RatingEvent[] {
+  const allowed = new Set(retrievals.map((r) => r.id));
+  const events: RatingEvent[] = [];
+  for (const r of ratings) {
+    if (!allowed.has(r.id)) continue;
+    // Step-6 §6 — sanitize before propagation. If the LLM emits a NUL byte
+    // or an all-control-chars string, drop the edge but keep the rating
+    // (best-effort: the memory's own posterior still gets the signal).
+    let cleanedReferencesSource: string | undefined;
+    if (r.referencesSource !== undefined) {
+      const cleaned = sanitizeReferencesSource(r.referencesSource);
+      if (cleaned !== null) {
+        cleanedReferencesSource = cleaned;
+      }
+    }
+    events.push({
+      memoryId: r.id,
+      signal: 2 * r.score - 1,
+      weight: LLM_RATER_WEIGHT,
+      source: "llm",
+      reasoning: r.reasoning,
+      ...(cleanedReferencesSource !== undefined
+        ? { referencesSource: cleanedReferencesSource }
+        : {}),
+    });
+  }
+  return events;
+}
+
+/**
+ * Append a structured-output instruction to the existing summary prompt so
+ * the same `claude -p` invocation produces both summary text AND per-memory
+ * ratings against `SummaryWithRatingsSchema`.
+ *
+ * Memory `content` is truncated to {@link RETRIEVAL_PROMPT_CONTENT_CAP} chars
+ * to keep the prompt within Haiku's context budget on long sessions; the
+ * server already truncates `agent_memory.content` to 500 chars in the
+ * retrievals endpoint, so this is the typical case.
+ */
+const RETRIEVAL_PROMPT_CONTENT_CAP = 600;
+
+export function buildSummaryWithRatingsPrompt(
+  basePrompt: string,
+  retrievals: { id: string; name: string; content: string }[],
+): string {
+  if (retrievals.length === 0) return basePrompt;
+  const memoryBlock = retrievals
+    .map((m, i) => {
+      const content =
+        m.content.length > RETRIEVAL_PROMPT_CONTENT_CAP
+          ? `${m.content.slice(0, RETRIEVAL_PROMPT_CONTENT_CAP)}…`
+          : m.content;
+      return `Memory #${i + 1}\n  id: ${m.id}\n  name: ${m.name}\n  content: ${content}`;
+    })
+    .join("\n\n");
+
+  return `${basePrompt}
+
+CRITICAL: Return JSON conforming to this schema (no prose outside the JSON, no markdown fences):
+{
+  "summary": string,                        // your existing summary text
+  "ratings": [                              // one entry per memory you can score
+    {
+      "id": string,                         // memory id, copied from the list below
+      "score": number,                      // 0 = misleading/unhelpful, 1 = highly useful
+      "reasoning": string,                  // 1..500 chars, why
+      "referencesSource": string            // OPTIONAL — see note below
+    }
+  ]
+}
+
+Score ONLY memories present in the list below. Use the exact ids. Omit any you cannot evaluate.
+
+Optionally for each rating, if the memory clearly references a specific external source (a GitHub PR/issue, a Linear issue, a customer, a Slack thread, an AgentMail thread, etc.), include a \`referencesSource\` string using the convention "<source>:<identifier>" (e.g. "github:owner/repo#N", "linear:KEY-N", "customer:<slug>"). Any prefix is fine — pick what matches the source. Omit the field if no clear external source.
+
+Memories retrieved during this session:
+
+${memoryBlock}`;
+}
+
+/**
+ * Best-effort parse of the structured `SummaryWithRatingsSchema` JSON out of
+ * the `claude -p --output-format json` envelope (`{ result: "<inner json>" }`).
+ *
+ * Returns `null` on any parse failure — the caller falls back to the existing
+ * summary-only path. NEVER throws.
+ */
+export function parseSummaryWithRatings(claudeStdout: string): SummaryWithRatings | null {
+  let envelope: { result?: unknown };
+  try {
+    envelope = JSON.parse(claudeStdout) as { result?: unknown };
+  } catch {
+    return null;
+  }
+  const inner = envelope.result;
+  let candidate: unknown;
+  if (typeof inner === "string") {
+    try {
+      candidate = JSON.parse(inner.trim());
+    } catch {
+      return null;
+    }
+  } else if (inner && typeof inner === "object") {
+    candidate = inner;
+  } else {
+    return null;
+  }
+  const parsed = SummaryWithRatingsSchema.safeParse(candidate);
+  return parsed.success ? parsed.data : null;
+}
+
+/**
+ * Fallback summary-text extractor for the hook's `claude -p` envelope. Used
+ * when {@link parseSummaryWithRatings} returns null — i.e., when the LLM
+ * returned a valid envelope but the inner payload either wasn't structured
+ * JSON (unstructured prompt path) OR was structured JSON whose ratings failed
+ * `SummaryWithRatingsSchema` validation (e.g., out-of-range scores).
+ *
+ * In the latter case `envelope.result` is the full inner JSON STRING such as
+ * `{"summary":"...","ratings":[...]}`; indexing that verbatim into agent
+ * memory would violate the step-4 contract that ratings are best-effort and
+ * the existing summary-indexing behavior remains unchanged. We extract the
+ * inner `summary` field if present, else return the inner string (treating
+ * it as plain summary text). NEVER throws.
+ */
+export function extractSummaryFromClaudeStdout(claudeStdout: string): string {
+  let envelope: { result?: unknown };
+  try {
+    envelope = JSON.parse(claudeStdout) as { result?: unknown };
+  } catch {
+    return claudeStdout;
+  }
+  const inner = envelope.result;
+  if (typeof inner === "string") {
+    try {
+      const innerParsed = JSON.parse(inner.trim()) as { summary?: unknown };
+      if (innerParsed && typeof innerParsed.summary === "string") {
+        return innerParsed.summary;
+      }
+    } catch {
+      // inner wasn't JSON — treat it as plain summary text
+    }
+    return inner;
+  }
+  if (
+    inner &&
+    typeof inner === "object" &&
+    typeof (inner as { summary?: unknown }).summary === "string"
+  ) {
+    return (inner as { summary: string }).summary;
+  }
+  return claudeStdout;
+}
+
+/**
+ * `MEMORY_RATERS=...` includes `llm`? Used by the hook to gate the piggyback
+ * path — strict opt-in so existing deployments are byte-identical when unset.
+ */
+export function isLlmRaterEnabled(): boolean {
+  const raw = process.env.MEMORY_RATERS;
+  if (!raw || raw.trim() === "") return false;
+  return raw
+    .split(",")
+    .map((s) => s.trim())
+    .includes("llm");
+}
+
+/** Memory snapshot returned by `GET /api/memory/retrievals`. */
+export type RetrievalRow = {
+  id: string;
+  name: string;
+  content: string;
+  scope?: string;
+  similarity?: number | null;
+  retrievedAt?: string;
+};
+
+/**
+ * GET `/api/memory/retrievals?taskId=` — best-effort. Returns `[]` on any
+ * failure so a transient API outage never blocks the summary-indexing path.
+ */
+export async function fetchRetrievalsForTask(opts: {
+  apiUrl: string;
+  apiKey: string;
+  agentId: string;
+  taskId: string;
+  fetchImpl?: typeof fetch;
+}): Promise<RetrievalRow[]> {
+  const fetchFn = opts.fetchImpl ?? fetch;
+  try {
+    const url = `${opts.apiUrl}/api/memory/retrievals?taskId=${encodeURIComponent(opts.taskId)}`;
+    const res = await fetchFn(url, {
+      headers: {
+        "X-Agent-ID": opts.agentId,
+        ...(opts.apiKey ? { Authorization: `Bearer ${opts.apiKey}` } : {}),
+      },
+    });
+    if (!res.ok) {
+      console.error(
+        `[memory-rater:llm] GET /api/memory/retrievals failed: ${res.status} ${res.statusText}`,
+      );
+      return [];
+    }
+    const body = (await res.json()) as { results?: RetrievalRow[] };
+    return body.results ?? [];
+  } catch (err) {
+    console.error("[memory-rater:llm] fetchRetrievalsForTask threw:", (err as Error).message);
+    return [];
+  }
+}
+
+/**
+ * POST `/api/memory/rate` — best-effort. Logs on 4xx/5xx, never throws. The
+ * worker hook wraps the whole rating block in its own try/catch as a final
+ * line of defence — rater failure must never block summary indexing.
+ */
+export async function postRatings(opts: {
+  apiUrl: string;
+  apiKey: string;
+  agentId: string;
+  taskId?: string;
+  events: RatingEvent[];
+  fetchImpl?: typeof fetch;
+}): Promise<{ ok: boolean; status: number }> {
+  if (opts.events.length === 0) return { ok: true, status: 0 };
+  const fetchFn = opts.fetchImpl ?? fetch;
+  const events = opts.events.map((e) => ({
+    memoryId: e.memoryId,
+    signal: e.signal,
+    weight: e.weight,
+    source: e.source,
+    ...(e.reasoning !== undefined ? { reasoning: e.reasoning } : {}),
+    ...(e.referencesSource !== undefined ? { referencesSource: e.referencesSource } : {}),
+    ...(opts.taskId ? { taskId: opts.taskId } : {}),
+  }));
+  try {
+    const res = await fetchFn(`${opts.apiUrl}/api/memory/rate`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Agent-ID": opts.agentId,
+        ...(opts.apiKey ? { Authorization: `Bearer ${opts.apiKey}` } : {}),
+      },
+      body: JSON.stringify({ events }),
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      console.error(
+        `[memory-rater:llm] POST /api/memory/rate failed: ${res.status} ${res.statusText} ${text.slice(0, 200)}`,
+      );
+    }
+    return { ok: res.ok, status: res.status };
+  } catch (err) {
+    console.error("[memory-rater:llm] postRatings threw:", (err as Error).message);
+    return { ok: false, status: 0 };
+  }
+}

package/src/be/memory/raters/noop.ts

@@ -0,0 +1,14 @@
+import type { MemoryRater, RatingEvent } from "./types";
+
+/**
+ * Default rater. Emits no events, makes no DB calls. Selected when
+ * MEMORY_RATERS is unset or empty so the framework defaults to behaving
+ * byte-identically to pre-rater builds.
+ */
+export class NoopRater implements MemoryRater {
+  readonly name = "noop";
+
+  async rate(): Promise<RatingEvent[]> {
+    return [];
+  }
+}

package/src/be/memory/raters/registry.ts

@@ -0,0 +1,86 @@
+import { ExplicitSelfRatingRater } from "./explicit-self";
+import { ImplicitCitationRater } from "./implicit-citation";
+import { LlmRater } from "./llm";
+import { NoopRater } from "./noop";
+import type { MemoryRater } from "./types";
+
+/**
+ * Plan: thoughts/taras/plans/2026-05-05-memory-rater-v1.5/step-1.md §4
+ *
+ * `MEMORY_RATERS` env — comma-separated list of rater names. Defaults to
+ * `[NoopRater]` when unset/empty so existing deployments stay byte-identical.
+ *
+ * `MEMORY_RATER_WEIGHTS` env — optional `name:multiplier,...` overrides.
+ * Multiplier is applied to every emitted RatingEvent.weight before
+ * `applyRating`. Default = 1.0.
+ *
+ * Each later step touches *only* its own line in the factory map:
+ *   - step-1: noop only (this PR).
+ *   - step-2: implicit-citation.
+ *   - step-4: llm.
+ *   - step-5: explicit-self.
+ *
+ * Unknown names are logged and skipped — startup never fails on this.
+ */
+
+type RaterFactory = () => MemoryRater;
+
+const FACTORIES: Record<string, RaterFactory> = {
+  noop: () => new NoopRater(),
+  "implicit-citation": () => new ImplicitCitationRater(),
+  "explicit-self": () => new ExplicitSelfRatingRater(),
+  llm: () => new LlmRater(),
+};
+
+/**
+ * Raters whose `rate(ctx)` runs server-side (in `store-progress.ts` after task
+ * completion). Worker-driven raters (e.g. step-4's `LlmRater`, step-5's
+ * `ExplicitSelfRater`) emit events from outside this set and POST them to
+ * `/api/memory/rate`. The store-progress hook only fires raters listed here.
+ *
+ * Plan: thoughts/taras/plans/2026-05-05-memory-rater-v1.5/step-2.md §6
+ */
+export const SERVER_RATERS = new Set<string>(["implicit-citation"]);
+
+export function getRegisteredRaters(): MemoryRater[] {
+  const raw = process.env.MEMORY_RATERS;
+  if (!raw || raw.trim() === "") {
+    return [new NoopRater()];
+  }
+
+  const names = raw
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+
+  const raters: MemoryRater[] = [];
+  for (const name of names) {
+    const factory = FACTORIES[name];
+    if (!factory) {
+      console.warn(`[memory-rater] Unknown rater "${name}" in MEMORY_RATERS — skipping`);
+      continue;
+    }
+    raters.push(factory());
+  }
+
+  if (raters.length === 0) {
+    return [new NoopRater()];
+  }
+  return raters;
+}
+
+export function getRaterWeightMultiplier(name: string): number {
+  const raw = process.env.MEMORY_RATER_WEIGHTS;
+  if (!raw || raw.trim() === "") return 1.0;
+
+  for (const pair of raw.split(",")) {
+    const trimmed = pair.trim();
+    if (trimmed === "") continue;
+    const [rawName, rawMult] = trimmed.split(":");
+    if (!rawName || !rawMult) continue;
+    if (rawName.trim() !== name) continue;
+    const mult = Number(rawMult);
+    if (Number.isFinite(mult) && mult >= 0) return mult;
+  }
+  return 1.0;
+}