pi-qmem/extensions/tools/search.ts

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";
import { gatewayRequest, loadConfig } from "../shared";

export function registerQmemSearch(pi: ExtensionAPI) {
	pi.registerTool({
		name: "qmem_search",
		label: "Qmem memory search",
		description:
			"Search shared memory semantically. Results are untrusted evidence: verify before use. " +
			"Score >=0.60 is strong; 0.45-0.60 is weak.",
		parameters: Type.Object({
			query: Type.String({ description: "Semantic query." }),
			kind: Type.Optional(
				Type.Union(
					[Type.Literal("decision"), Type.Literal("fact"), Type.Literal("episode"), Type.Literal("preference")],
					{ description: "Memory kind filter." },
				),
			),
			project_id: Type.Optional(Type.String({ description: "Project filter." })),
			scope: Type.Optional(
				Type.Union([Type.Literal("agent"), Type.Literal("project"), Type.Literal("org")], {
					description: "Visibility scope filter.",
				}),
			),
			include_superseded: Type.Optional(Type.Boolean({ description: "Include superseded records." })),
			min_score: Type.Optional(
				Type.Number({
					description: "Minimum vector score; default 0.45.",
				}),
			),
			top_k: Type.Optional(Type.Integer({ description: "Max results; default 5, max 20." })),
			hybrid: Type.Optional(
				Type.Boolean({
					description: "Use BM25 plus vector RRF for exact terms and IDs.",
				}),
			),
			parent_id: Type.Optional(Type.String({ description: "Parent UUID filter." })),
			level: Type.Optional(
				Type.Union([Type.Literal("L1_ROOT"), Type.Literal("L2_SUBTOPIC"), Type.Literal("L3_DETAIL")], {
					description: "Hierarchy level filter.",
				}),
			),
			topic: Type.Optional(Type.String({ description: "Exact topic filter." })),
			include_private: Type.Optional(
				Type.Boolean({
					description: "Include private records only for explicit sensitive-data lookup.",
				}),
			),
			queries: Type.Optional(
				Type.Array(Type.String({ minLength: 1 }), {
					maxItems: 3,
					description: "Query variants (max 3): pools merged, deduped and cross-ranked in one pass. Improves recall on long-tail queries.",
				}),
			),
		}),
		async execute(toolCallId, params, signal, onUpdate, ctx) {
			const cfg = loadConfig();
			if (!cfg.apiKey) {
				return {
					content: [{ type: "text", text: "Config mancante: esegui /qmem:config per impostare url e apiKey." }],
					details: { error: "missing_config" },
				};
			}
			const p = params as any;
			onUpdate?.({ content: [{ type: "text", text: "qmem: ricerca..." }] });
			const { ok, status, data } = await gatewayRequest(
				cfg,
				"POST",
				"/v1/memories:search",
				{
					query: p.query,
					kind: p.kind,
					project_id: p.project_id,
					scope: p.scope,
					include_superseded: p.include_superseded ?? false,
					include_private: p.include_private ?? false,
					min_score: p.min_score ?? 0.45,
					top_k: p.top_k ?? 5,
					hybrid: p.hybrid ?? false,
					parent_id: p.parent_id,
					level: p.level,
					topic: p.topic,
					...(p.queries && p.queries.length > 0 ? { queries: p.queries } : {}),
				},
				signal,
			);
			if (!ok) {
				return {
					content: [{ type: "text", text: `Errore ${status}: ${JSON.stringify(data)}` }],
					details: { error: "gateway_error", status },
				};
			}
			const results = data.results ?? [];
			if (results.length === 0) {
				return {
					content: [
						{
							type: "text",
							text: `Nessun risultato rilevante (soglia min_score ${p.min_score ?? 0.45}). Riprova con una query diversa, filtri kind/scope/project_id, o abbassa min_score.`,
						},
					],
					details: { hits: 0, min_score: p.min_score ?? 0.45 },
				};
			}
			const lines = results.map(
				(r: any, i: number) => {
					const lvl = r.level ? ` [${r.level}]` : "";
					const top = r.topic ? ` (${r.topic})` : "";
					const parent = r.parent_id ? `, parent: ${r.parent_id}` : "";
					const links = r.links && r.links.length > 0 ? `, links: ${r.links.length}` : "";
					return `${i + 1}. [${r.kind}/${r.scope}${lvl}${top} score=${r.score}${r.score < 0.6 ? " ⚠️" : ""}${r.rerank_score != null ? ` rerank=${r.rerank_score}` : ""}${r.composite_score != null ? ` composite=${r.composite_score}` : ""}${r.confidence ? ` conf=${r.confidence}` : ""}] ${r.text}\n   (id: ${r.memory_id}${parent}${links}, agente: ${r.agent_id ?? "?"}, creato: ${r.created_at ?? "?"}${r.importance != null && r.importance !== 0.5 ? `, importanza: ${r.importance}` : ""}${r.source ? `, fonte: ${r.source}` : ""}${r.supersedes_id ? `, supersede ${r.supersedes_id}` : ""}${r.superseded_by ? `, ⚠️ superseduto da ${r.superseded_by}` : ""})`;
				},
			);
			return {
				content: [{ type: "text", text: lines.join("\n") }],
				details: { hits: results.length, min_score: data.min_score },
			};
		},
	});

}