import type { WritableDatabase } from "#db/database.ts"; import { requireString } from "#db/rowDecode.ts"; import { keyFileTarget } from "#providers/config.ts"; import type { EmbeddingProvider } from "#providers/embedding.ts"; import { resolveFamilyProviders } from "#providers/familyProviders.ts"; import { SEARCH_TRANSPORT } from "#providers/transport.ts"; import type { FreshSearchResult } from "#search/memorySearch.ts"; import { searchMemoriesWithStatus } from "#search/memorySearch.ts"; import { optionValue } from "./args.ts"; import { ICONS } from "./render/icons.ts"; import { tagsText } from "./render/memories.ts"; // Mirrors Python's cli/memories.py degraded_note wording exactly (AI-04), // including under a degraded search with zero results. const DEGRADED_NOTE = "⚠ Degraded: lexical-only search (embedding unavailable — offline or no API key)."; /** * The degraded note for the cause the search reported (CR187). The general * note guesses "offline or no API key"; for the two causes the person can fix * themselves, the note says which one, and where. * * `config` means a missing key here: the search's embedding provider is the * live one, and nothing else in its path raises `ProviderConfigError`. `auth` * is a key OpenRouter refused, kept through the embedding wrapper. */ export function degradedNoteFor( kind: string | undefined, env: Record = process.env, home?: string, ): string { if (kind === "config") { return ( "⚠ Degraded: lexical-only search (OPENROUTER_API_KEY is not configured: " + `add it to ${keyFileTarget(env, home)}).` ); } if (kind === "auth") { return "⚠ Degraded: lexical-only search (OpenRouter refused OPENROUTER_API_KEY: check the key where it is set)."; } return DEGRADED_NOTE; } export interface SearchMemoryRow { id: string; memory_type: string; layer: string; title: string; content: string; created_at: string; journey: string | null; tags: string | null; } /** * Resolve the embedding provider by the same precedence the router used * (CV22.DS8.US1), so the route can never disagree with the routing decision * about which transport is in play. */ export async function resolveSearchEmbeddingProvider( env: NodeJS.ProcessEnv = process.env, ): Promise { // The live provider resolves its config lazily, so a missing key surfaces // inside searchMemoriesWithStatus and degrades to lexical-only rather than // failing the command -- Python's behavior for an unconfigured install. const family = await resolveFamilyProviders(env, SEARCH_TRANSPORT); if (!family.embedding) { // The search family declares an embedding fixture, so replay and live both // build one; this is defense in depth, not a reachable state. throw new Error("memories --search requires an embedding provider"); } return family.embedding; } export interface MemorySearchRouteOptions { /** Receives a content-free degraded category for the front-door log. */ onDegraded?: (detail: string) => void; } export async function runMemorySearchRoute( db: WritableDatabase, args: readonly string[], options: MemorySearchRouteOptions = {}, ): Promise { const query = optionValue(args, "--search"); if (!query) throw new Error("memories --search requires a query"); const provider = await resolveSearchEmbeddingProvider(); const limit = Number(optionValue(args, "--limit") ?? 20); const { results, degraded, degradedKind } = await searchMemoriesWithStatus(db, { query, limit, memoryType: optionValue(args, "--type"), layer: optionValue(args, "--layer"), journey: optionValue(args, "--journey"), provider, // An exploratory CLI search is not a genuine context load, so it must not // reinforce: `access_count` feeds `reinforcement_score` and the hybrid // ranker, and a ranker fed by its own exhaust drifts toward whatever was // searched for rather than whatever was used (AI-12). Python's // `cli/memories.py` has passed `log_access=False` since 2026-07-16; this // port did not, and reinforced on every `memories --search` from the flip // until CV22.DS9.US2 measured it. Builder context load deliberately keeps // the default and still reinforces -- that one IS a genuine load. logAccess: false, }); // A degraded live search is the one failure an operator has to diagnose // without a re-run, so the taxonomy class reaches the front-door log rather // than dying inside the degrade path. Category only -- never a message, // never the query (RS005/CR026). if (degraded && degradedKind) { options.onDegraded?.(`embedding_degraded kind=${degradedKind}`); } const rows = memoriesById( db, results.map((result) => result.id), ); return formatSearchResults(query, results, rows, degraded, degradedNoteFor(degradedKind)); } /** * Pure rendering of a fresh-search outcome (AI-04). Split out from * `runMemorySearchRoute` so the degraded/normal render branches are directly * unit-testable without a database or a live-failing embedding provider (none * exists yet -- see CR037 plan). */ export function formatSearchResults( query: string, results: readonly FreshSearchResult[], rows: ReadonlyMap, degraded: boolean, note: string = DEGRADED_NOTE, ): string { if (results.length === 0) { return degraded ? `${note}\n` : "No memories found.\n"; } const lines: string[] = []; if (degraded) { lines.push(`${note} Ranked by keyword match.`, ""); } lines.push(`🔍 Search: "${query}" (${results.length} results)`, ""); for (const result of results) { const memory = rows.get(result.id); if (!memory) continue; const icon = ICONS[memory.memory_type] ?? "•"; const date = memory.created_at ? memory.created_at.slice(0, 10) : "?"; const journey = memory.journey ? ` 🧭 ${memory.journey}` : ""; const tags = tagsText(memory.tags); lines.push(`${icon} **${memory.title}** (score: ${result.score.toFixed(3)})`); lines.push( ` ${date} | \`${memory.id.slice(0, 8)}\` | ${memory.memory_type} [${memory.layer}]${journey}`, ); lines.push(` ${memory.content.slice(0, 200)}`); if (tags) lines.push(` 🏷 ${tags}`); lines.push(""); } return `${lines.join("\n")}\n`; } /** * The row reader both search faces share. * * Exported for `build load` (CV22.DS7.US8 plateau 7), which renders the same * memories from the same ranked ids: the ranker returns `{id, score}` only, so a * second copy of this query is a second chance for the two blocks to disagree * about what a memory says. */ export function memoriesById( db: WritableDatabase, ids: readonly string[], ): Map { if (ids.length === 0) return new Map(); const placeholders = ids.map(() => "?").join(", "); const rows = db .prepare( `SELECT id, memory_type, layer, title, content, created_at, journey, tags FROM memories ` + `WHERE id IN (${placeholders})`, ) .all(...ids); return new Map( rows.map((row) => [ requireString(row, "id"), { id: requireString(row, "id"), memory_type: requireString(row, "memory_type"), layer: requireString(row, "layer"), title: requireString(row, "title"), content: requireString(row, "content"), created_at: requireString(row, "created_at"), journey: typeof row.journey === "string" ? row.journey : null, tags: typeof row.tags === "string" ? row.tags : null, }, ]), ); }