pi-qmem/extensions/tools/store.ts

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

export function registerQmemStore(pi: ExtensionAPI) {
	pi.registerTool({
		name: "qmem_store",
		label: "Qmem memory store",
		description:
			"Store one compact, high-signal memory record. project_id is required; do not store raw transcripts.",
		parameters: Type.Object({
			text: Type.String({ description: "Compact memory content." }),
			kind: Type.Optional(
				Type.Union(
					[Type.Literal("decision"), Type.Literal("fact"), Type.Literal("episode"), Type.Literal("preference")],
					{ description: "Record kind; default fact." },
				),
			),
			agent_id: Type.Optional(Type.String({ description: "Writer provenance." })),
			project_id: Type.String({
				description: "Required project ID, kebab-case.",
			}),
			scope: Type.Optional(
				Type.Union([Type.Literal("agent"), Type.Literal("project"), Type.Literal("org")], {
					description: "Scope; default agent.",
				}),
			),
			confidence: Type.Optional(
				Type.Union([Type.Literal("high"), Type.Literal("medium"), Type.Literal("low")], {
					description: "Confidence; default medium.",
				}),
			),
			source: Type.Optional(Type.String({ description: "Source label." })),
			expires_at: Type.Optional(
				Type.String({
					description: "ISO 8601 expiry; omit for permanent records.",
				}),
			),
			supersedes_id: Type.Optional(Type.String({ description: "UUID replaced by this record." })),
			supersede_reason: Type.Optional(Type.String({ description: "Reason for replacement." })),
			parent_id: Type.Optional(Type.String({ description: "Parent UUID." })),
			level: Type.Optional(
				Type.Union([Type.Literal("L1_ROOT"), Type.Literal("L2_SUBTOPIC"), Type.Literal("L3_DETAIL")], {
					description: "Hierarchy level.",
				}),
			),
			topic: Type.Optional(Type.String({ description: "Hierarchy topic ID." })),
			private: Type.Optional(
				Type.Boolean({
					description: "Hide from standard search; use only for sensitive data.",
				}),
			),
			links: Type.Optional(
				Type.Array(
					Type.Object({
						target_id: Type.String({ description: "Target UUID." }),
						predicate: Type.Optional(Type.String({ description: "Relation type." })),
						weight: Type.Optional(Type.Number({ description: "Relation weight; default 1.0." })),
					}),
					{ description: "Related records." },
				),
			),
		}),
		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: salvataggio record..." }] });
			// Rilevamento duplicati: cerca prima di salvare (soglia alta, non blocca)
			let dupes: any[] = [];
			const dupCheck = await gatewayRequest(
				cfg,
				"POST",
				"/v1/memories:search",
				{ query: p.text, project_id: p.project_id, top_k: 3, min_score: 0.92, include_superseded: false },
				signal,
			);
			if (dupCheck.ok) dupes = dupCheck.data.results ?? [];
			// Idempotency: stessa key per tutta l'operazione (e per eventuali retry)
			const idemKey = crypto.randomUUID();
			const { ok, status, data } = await gatewayRequest(
				cfg,
				"POST",
				"/v1/memories",
				{
					text: p.text,
					kind: p.kind ?? "fact",
					agent_id: p.agent_id,
					project_id: p.project_id,
					scope: p.scope ?? "agent",
					source: p.source,
					confidence: p.confidence ?? "medium",
					expires_at: p.expires_at,
					supersedes_id: p.supersedes_id,
					supersede_reason: p.supersede_reason,
					parent_id: p.parent_id,
					private: p.private ?? false,
					level: p.level,
					topic: p.topic,
					links: p.links,
				},
				signal,
				idemKey,
			);
			if (!ok) {
				const down = status === 0 || status >= 500 || status === 429;
				return {
					content: [
						{
							type: "text",
							text:
								`Errore ${status}: ${JSON.stringify(data)}` +
								(down
									? "\n⚠️ Il record NON è stato salvato: nessuna coda locale (il gateway è la fonte di verità). Riprova quando è raggiungibile, oppure annota il contenuto e usa /qmem:local import per l'indice testuale."
									: ""),
						},
					],
					details: { error: "gateway_error", status },
				};
			}
			const dupWarning =
				dupes.length > 0
					? "\n⚠️ Possibili duplicati (score >= 0.92, stesso project_id):\n" +
					  dupes.map((d: any) => `  - ${d.memory_id} (score ${d.score}): ${String(d.text).slice(0, 100)}`).join("\n") +
					  "\nValuta se il nuovo record è davvero necessario o se conviene qmem_correct sul duplicato."
					: "";
			const extra = `${p.level ? `, level ${p.level}` : ""}${p.topic ? `, topic ${p.topic}` : ""}${p.parent_id ? ` — parent ${p.parent_id}` : ""}`;
			return {
				content: [{ type: "text", text: `Memoria salvata: ${data.memory_id} (${p.kind ?? "fact"}, scope ${p.scope ?? "agent"}${extra})${p.supersedes_id ? ` — supersede ${p.supersedes_id}` : ""}${dupWarning}` }],
				details: { memory_id: data.memory_id, created_at: data.created_at, duplicates: dupes.length, parent_id: p.parent_id, level: p.level, topic: p.topic },
			};
		},
	});

}