frinus-mcp 3.3.0 → 3.4.1

package/README.md

@@ -11,7 +11,7 @@ It does **not** run on its own. It stores nothing locally: every tool call is fo
 
 With those in place, the server exposes **70 tools** spanning cognitive memory, working memory, sessions, agents, the L0–L3 knowledge hierarchy, orchestration tasks, and training pipelines. It speaks stdio and works with any MCP-aware client.
 
-- **Version:** 3.3.0
+- **Version:** 3.4.1
 - **Tools:** 70 (see [Tools Reference](#tools-reference))
 - **Platform:** https://frinus.rdxsec.com.br (hosted SaaS — the backend this server talks to)
 - **npm package:** [`frinus-mcp`](https://www.npmjs.com/package/frinus-mcp)

package/dist/client/memory-client.d.ts

@@ -55,6 +55,21 @@ export declare class MemoryClient implements MemoryClientInterface {
         task_description: string;
         max_tokens?: number;
     }): Promise<any>;
+    /** List memories with a classification suggestion awaiting approval. */
+    getPendingClassifications(limit?: number): Promise<any>;
+    /**
+     * Approve a proposed classification. Without overrides, the backend applies
+     * its own suggestion. Passing universe_id and/or context_id overrides the
+     * suggested target (also used to CORRECT a wrong suggestion).
+     */
+    approveClassification(memoryId: string, data?: {
+        universe_id?: string;
+        context_id?: string;
+    }): Promise<any>;
+    /** Reject a proposed classification (memory stays where it is). */
+    rejectClassification(memoryId: string): Promise<any>;
+    /** Approve multiple proposed classifications in one call. */
+    approveClassificationBatch(ids: string[]): Promise<any>;
     reinforceMemory(memoryId: string, boost?: number): Promise<any>;
     weakenMemory(memoryId: string, penalty?: number): Promise<any>;
     getWorkingMemory(contextId: string): Promise<any>;

package/dist/client/memory-client.js

@@ -142,6 +142,46 @@ export class MemoryClient {
         return response.data;
     }
     // =========================================================================
+    // Auto-classification (human-in-the-loop)
+    //
+    // The backend classifies a memory by content at write time and returns a
+    // SUGGESTION with classification_status="proposed". The user reviews the
+    // pending queue and explicitly approves (optionally overriding the target)
+    // or rejects. Nothing is moved automatically.
+    // =========================================================================
+    /** List memories with a classification suggestion awaiting approval. */
+    async getPendingClassifications(limit) {
+        const params = limit ? `?limit=${limit}` : "";
+        const response = await this.client.get(`/memories/classification/pending${params}`);
+        return response.data;
+    }
+    /**
+     * Approve a proposed classification. Without overrides, the backend applies
+     * its own suggestion. Passing universe_id and/or context_id overrides the
+     * suggested target (also used to CORRECT a wrong suggestion).
+     */
+    async approveClassification(memoryId, data) {
+        const payload = {};
+        if (data?.universe_id)
+            payload.universe_id = data.universe_id;
+        if (data?.context_id)
+            payload.context_id = data.context_id;
+        const response = await this.client.post(`/memories/${memoryId}/classification/approve`, payload);
+        return response.data;
+    }
+    /** Reject a proposed classification (memory stays where it is). */
+    async rejectClassification(memoryId) {
+        const response = await this.client.post(`/memories/${memoryId}/classification/reject`);
+        return response.data;
+    }
+    /** Approve multiple proposed classifications in one call. */
+    async approveClassificationBatch(ids) {
+        const response = await this.client.post("/memories/classification/approve-batch", {
+            ids,
+        });
+        return response.data;
+    }
+    // =========================================================================
     // Dynamic Relevance
     // =========================================================================
     async reinforceMemory(memoryId, boost) {

package/dist/tools/definitions.js

@@ -9,6 +9,17 @@ export const TOOLS = [
 Use this to record important information, learnings, decisions, or procedures
 that should be remembered for future reference.
 
+The backend classifies the memory by content at write time and returns a
+SUGGESTION (status "proposed"/"universe_only") of which universe/context node it
+belongs to — nothing is moved automatically. Review pending suggestions with
+memory_classification_pending and apply them with memory_classification_approve.
+
+Passing universe_id or context_id anchors the memory THERE directly (status
+"manual"): auto-classification is skipped entirely, so no suggestion is returned
+and nothing may later move it. The response always reports the destination the
+memory actually landed in — a suggestion, when present, is labelled as pending
+and not applied.
+
 Memory types:
 - episodic: Specific experiences and events (what happened)
 - semantic: General knowledge and facts (what I know)
@@ -38,7 +49,7 @@ Scopes:
                 scope: {
                     type: "string",
                     enum: ["user", "agent", "universe", "organization"],
-                    description: "Visibility scope. Padrão: a memória é associada ao universo do agente (contexto). 'organization' (org-wide) e 'user' (private) só são usados quando explicitamente definidos; 'agent' (agent-only) é o fallback automático quando não há universo identificável.",
+                    description: "Optional explicit visibility scope — WHO can see the memory, independent of WHERE it is filed in the hierarchy (that is universe_id/context_id). 'organization' (org-wide), 'user' (private), 'universe' (department-shared — requires a universe, via universe_id/context_id or the agent's own), 'agent' (agent-only). Default: 'user'.",
                 },
                 importance: {
                     type: "number",
@@ -58,7 +69,7 @@ Scopes:
                 },
                 universe_id: {
                     type: "string",
-                    description: "UUID do universo/contexto ao qual associar a memória. Se omitido, a memória é associada automaticamente ao universo do agente.",
+                    description: "Optional UUID of a universe to file the memory under explicitly. Anchors it there as ground-truth (status 'manual'): auto-classification is skipped and nothing may later move it. Omit to let the backend suggest one.",
                 },
                 context_id: {
                     type: "string",
@@ -156,6 +167,64 @@ Use with caution - this permanently removes the memory.`,
         },
     },
     // ==========================================================================
+    // Auto-classification — human-in-the-loop (3)
+    // ==========================================================================
+    {
+        name: "memory_classification_pending",
+        description: `List memories whose auto-classification is awaiting your approval.
+
+The backend classifies each new memory by content and proposes a target
+universe/context node (status "proposed"). This returns that review queue with,
+per item: the memory id, the suggested destination breadcrumb, and the
+confidence. Approve with memory_classification_approve, or correct the target by
+passing universe_id/context_id to it.`,
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: { type: "integer", description: "Maximum suggestions to return (default: backend default)" },
+            },
+            required: [],
+        },
+    },
+    {
+        name: "memory_classification_approve",
+        description: `Approve a proposed classification, moving the memory to its suggested
+universe/context node.
+
+Without overrides, the backend applies its own suggestion. Pass universe_id
+and/or context_id to override the suggested target (also the way to CORRECT a
+wrong suggestion).`,
+        inputSchema: {
+            type: "object",
+            properties: {
+                memory_id: { type: "string", description: "UUID of the memory whose classification is being approved" },
+                universe_id: { type: "string", description: "Optional UUID of a universe to override the suggested destination" },
+                context_id: { type: "string", description: "Optional UUID of a hierarchy node (concept/theme/topic/point) to override the suggested destination" },
+            },
+            required: ["memory_id"],
+        },
+    },
+    {
+        name: "memory_reclassify",
+        description: `Re-classify a memory. Either pin it to an explicit destination, or ask the
+backend to re-run its automatic classifier.
+
+- Pass universe_id and/or context_id to set the destination directly (correction).
+- Pass rerun_auto=true (and no explicit target) to discard the current
+  suggestion and let the backend propose a new one (review via
+  memory_classification_pending).`,
+        inputSchema: {
+            type: "object",
+            properties: {
+                memory_id: { type: "string", description: "UUID of the memory to reclassify" },
+                universe_id: { type: "string", description: "Optional UUID of a universe to set as the explicit destination" },
+                context_id: { type: "string", description: "Optional UUID of a hierarchy node to set as the explicit destination" },
+                rerun_auto: { type: "boolean", description: "When true (and no explicit target), re-run the backend's automatic classification" },
+            },
+            required: ["memory_id"],
+        },
+    },
+    // ==========================================================================
     // Dynamic Relevance (2)
     // ==========================================================================
     {

package/dist/tools/handlers.js

@@ -196,84 +196,283 @@ export function handleApiError(error) {
     }
     return null; // Not a known error, let it propagate
 }
+// ---------------------------------------------------------------------------
+// Auto-classification rendering helpers (human-in-the-loop)
+// ---------------------------------------------------------------------------
+// The Memory Engine now classifies a memory by content at write time and
+// returns a SUGGESTION with classification_status="proposed". These helpers
+// render that suggestion enxuto, and degrade gracefully to the minimal
+// ID/Type/Scope format when an OLDER backend omits the classification fields.
+/** Human-readable confidence bucket from a 0..1 score. >=0.75 alta, >=0.45 média. */
+function confidenceLabel(confidence) {
+    if (typeof confidence !== "number" || Number.isNaN(confidence))
+        return null;
+    if (confidence >= 0.75)
+        return "alta";
+    if (confidence >= 0.45)
+        return "média";
+    return "baixa";
+}
+/** Name of a classified universe, tolerating string | {name} shapes. */
+function universeName(u) {
+    if (!u)
+        return null;
+    if (typeof u === "string")
+        return u;
+    if (typeof u === "object") {
+        const name = u.name;
+        if (typeof name === "string" && name)
+            return name;
+    }
+    return null;
+}
+/** Breadcrumb path of a classified context node ("Checkout › Antifraude"). */
+function contextName(c) {
+    if (!c)
+        return null;
+    if (typeof c === "string")
+        return c;
+    if (typeof c === "object") {
+        const obj = c;
+        const path = obj.path || obj.context_path || obj.name;
+        if (typeof path === "string" && path)
+            return path;
+    }
+    return null;
+}
+/**
+ * Build the suggestion breadcrumb from a result that carries
+ * classified_universe / classified_context, e.g.
+ * "Monetizze › Checkout › Antifraude" or just "Monetizze".
+ */
+function suggestionLabel(result) {
+    const uni = universeName(result?.classified_universe);
+    const ctx = contextName(result?.classified_context);
+    if (uni && ctx)
+        return `${uni} › ${ctx}`;
+    if (uni)
+        return uni;
+    if (ctx)
+        return ctx;
+    return "";
+}
+/**
+ * Build the FINAL destination breadcrumb for an approved/manual memory. Falls
+ * back to the classified_* suggestion shape, then to a bare scope.
+ */
+function destinationLabel(result) {
+    const fromSuggestion = suggestionLabel(result);
+    if (fromSuggestion)
+        return fromSuggestion;
+    if (typeof result?.scope === "string" && result.scope)
+        return `scope ${result.scope}`;
+    return "";
+}
+/**
+ * Breadcrumb for a hierarchy chain returned by the backend as a list of nodes
+ * ({ id, level, name, context_path }), e.g. "Operacoes › Contratos › Gain-share".
+ * Falls back to the raw id for legacy FK-only nodes with no contexts row.
+ */
+function hierarchyLabel(nodes) {
+    if (!Array.isArray(nodes) || nodes.length === 0)
+        return "";
+    return nodes
+        .map((n) => (typeof n?.name === "string" && n.name ? n.name : n?.id))
+        .filter((s) => typeof s === "string" && s)
+        .join(" › ");
+}
+/** Where the memory ACTUALLY landed — never the classifier's suggestion. */
+function appliedLabel(result) {
+    const fromChain = hierarchyLabel(result?.hierarchy);
+    if (fromChain)
+        return fromChain;
+    // Older backend without `hierarchy`: fall back to the real FK column. Still
+    // the applied destination — NOT classified_universe (that is a proposal).
+    const uni = result?.universe_id;
+    return typeof uni === "string" && uni ? uni : "";
+}
+/**
+ * Render the memory_store response.
+ *
+ * Hard rule: the ONLY thing reported as the destination is where the memory was
+ * actually written (`hierarchy` / `universe_id`). `classified_*` and
+ * `proposed_hierarchy` are the auto-classifier's SUGGESTION and are always
+ * labelled as such — never as the destination. Reporting a pending suggestion
+ * as the destination is what made an explicit `universe_id` look ignored when
+ * the write had in fact honoured it.
+ */
+function renderStoreResult(result) {
+    const id = result?.id;
+    const status = result?.classification_status;
+    const head = `✓ Salva`;
+    const applied = appliedLabel(result);
+    const pending = status === "proposed" || status === "universe_only";
+    // Anchored: a real destination exists. Report it, and only then mention a
+    // still-pending suggestion (which cannot have been applied, by definition).
+    if (applied) {
+        let out = `${head} em: ${applied}`;
+        if (pending) {
+            const sug = hierarchyLabel(result?.proposed_hierarchy) || suggestionLabel(result);
+            if (sug && sug !== applied) {
+                out += `\n  ↳ sugestão pendente (NÃO aplicada): ${sug} — revise com memory_classification_pending`;
+            }
+        }
+        return out;
+    }
+    // Not anchored anywhere: the suggestion is all we have to offer.
+    if (pending) {
+        const sug = hierarchyLabel(result?.proposed_hierarchy) || suggestionLabel(result);
+        const conf = confidenceLabel(result?.classification_confidence);
+        if (sug) {
+            const confTxt = conf ? `, confiança ${conf}` : "";
+            return `${head} · sem destino aplicado · sugestão: ${sug} (auto${confTxt}) — aprove com memory_classification_approve`;
+        }
+        return `${head} · sem destino aplicado e sem sugestão confiável — use memory_classification_pending para revisar`;
+    }
+    // Defensive: older backend without classification fields, or no hierarchy at all.
+    return `${head}\nID: ${id}\nType: ${result?.memory_type}\nScope: ${result?.scope}`;
+}
 const handlers = {
     // ==========================================================================
     // Core Memory
     // ==========================================================================
-    async memory_store(args, { memoryClient, cpClient, resolvedUserId }) {
+    async memory_store(args, { memoryClient, resolvedUserId }) {
         const createdByUser = args.created_by_user_id || resolvedUserId || undefined;
         const userId = args.user_id || resolvedUserId || undefined;
         const meta = args.metadata || {};
         const universeId = args.universe_id || meta.universe_id || undefined;
-        // Context-first default: when the caller does NOT pass an explicit `scope`,
-        // memories are associated with a CONTEXT (universe). The backend resolves
-        // the universe_id from the agent when none is supplied. `organization` and
-        // `user` are only used when explicitly requested by the caller. When the
-        // agent has no resolvable universe, we fall back to `agent` scope and help
-        // future categorization by returning the list of available universes.
-        const explicitScope = args.scope;
-        const resolvedScope = explicitScope || "universe";
-        const baseInput = {
-            agent_id: args.agent_id,
-            content: args.content,
-            memory_type: args.memory_type,
-            importance: args.importance,
-            user_id: userId,
-            created_by_user_id: createdByUser,
-            metadata: args.metadata,
-            context_id: args.context_id,
-            credential_ref: args.credential_ref,
-            universe_id: universeId,
-        };
+        // Human-in-the-loop classification: the backend classifies the memory by
+        // content at write time and returns a SUGGESTION (classification_status
+        // "proposed"). Nothing is moved automatically — the user reviews via
+        // memory_classification_pending and approves with
+        // memory_classification_approve. The MCP layer no longer injects an
+        // implicit "universe" scope nor surfaces "available universes"; scope,
+        // universe_id and context_id are forwarded ONLY when the caller sets them
+        // (explicit overrides → classification_status "manual").
+        try {
+            const result = await memoryClient.storeMemory({
+                agent_id: args.agent_id,
+                content: args.content,
+                memory_type: args.memory_type,
+                importance: args.importance,
+                user_id: userId,
+                created_by_user_id: createdByUser,
+                metadata: args.metadata,
+                context_id: args.context_id,
+                credential_ref: args.credential_ref,
+                universe_id: universeId,
+                scope: args.scope,
+            });
+            return { content: [{ type: "text", text: renderStoreResult(result) }] };
+        }
+        catch (error) {
+            const apiErr = handleApiError(error);
+            if (apiErr)
+                return apiErr;
+            throw error;
+        }
+    },
+    // ==========================================================================
+    // Auto-classification (human-in-the-loop)
+    // ==========================================================================
+    async memory_classification_pending(args, { memoryClient }) {
+        let result;
+        try {
+            result = await memoryClient.getPendingClassifications(args.limit);
+        }
+        catch (error) {
+            const apiErr = handleApiError(error);
+            if (apiErr)
+                return apiErr;
+            throw error;
+        }
+        const items = Array.isArray(result) ? result : (result?.items || result?.pending || []);
+        if (!items || items.length === 0) {
+            return { content: [{ type: "text", text: "Nenhuma sugestão de classificação aguardando aprovação." }] };
+        }
+        let formatted = `Sugestões aguardando aprovação (${items.length}):\n\n`;
+        items.forEach((m, i) => {
+            const label = suggestionLabel(m);
+            const conf = confidenceLabel(m.confidence);
+            const preview = typeof m.content === "string"
+                ? (m.content.length > 120 ? m.content.slice(0, 120) + "…" : m.content)
+                : "";
+            formatted += `${i + 1}. (id: ${m.id})`;
+            if (conf)
+                formatted += ` · confiança ${conf}`;
+            formatted += `\n   sugestão: ${label}\n`;
+            if (preview)
+                formatted += `   ${preview}\n`;
+            formatted += `\n`;
+        });
+        formatted += `Aprove com memory_classification_approve(memory_id) — passe universe_id/context_id para corrigir o destino.`;
+        return { content: [{ type: "text", text: formatted }] };
+    },
+    async memory_classification_approve(args, { memoryClient }) {
+        const memoryId = args.memory_id;
+        const override = {};
+        if (args.universe_id)
+            override.universe_id = args.universe_id;
+        if (args.context_id)
+            override.context_id = args.context_id;
+        let result;
+        try {
+            result = await memoryClient.approveClassification(memoryId, override);
+        }
+        catch (error) {
+            const apiErr = handleApiError(error);
+            if (apiErr)
+                return apiErr;
+            throw error;
+        }
+        const dest = destinationLabel(result) || suggestionLabel(result);
+        const overridden = Boolean(override.universe_id || override.context_id);
+        let text = `✓ Classificação aprovada`;
+        if (dest)
+            text += ` · ${dest}`;
+        if (overridden)
+            text += ` (destino corrigido pelo usuário)`;
+        text += `\nID: ${memoryId}`;
+        return { content: [{ type: "text", text }] };
+    },
+    async memory_reclassify(args, { memoryClient }) {
+        const memoryId = args.memory_id;
+        const rerunAuto = args.rerun_auto;
+        const universeId = args.universe_id;
+        const contextId = args.context_id;
         try {
-            const result = await memoryClient.storeMemory({ ...baseInput, scope: resolvedScope });
+            // Correction = approve with an override (or reject to re-run the
+            // backend's auto-classifier when no explicit target is given).
+            if (universeId || contextId) {
+                const result = await memoryClient.approveClassification(memoryId, {
+                    universe_id: universeId,
+                    context_id: contextId,
+                });
+                const dest = destinationLabel(result) || suggestionLabel(result);
+                let text = `✓ Reclassificada`;
+                if (dest)
+                    text += ` · ${dest}`;
+                text += ` (destino definido pelo usuário)\nID: ${memoryId}`;
+                return { content: [{ type: "text", text }] };
+            }
+            if (rerunAuto) {
+                const result = await memoryClient.rejectClassification(memoryId);
+                const dest = suggestionLabel(result);
+                let text = `✓ Sugestão anterior descartada; reclassificação automática solicitada`;
+                if (dest)
+                    text += ` · nova sugestão: ${dest}`;
+                text += `\nID: ${memoryId}\nRevise em memory_classification_pending.`;
+                return { content: [{ type: "text", text }] };
+            }
             return {
                 content: [{
                         type: "text",
-                        text: `Memory stored successfully.\nID: ${result.id}\nType: ${result.memory_type}\nScope: ${result.scope}`,
+                        text: "memory_reclassify requer universe_id/context_id (destino corrigido) ou rerun_auto=true (reexecutar classificação automática).",
                     }],
+                isError: true,
             };
         }
         catch (error) {
-            // Fallback: scope was implicitly "universe" but the agent has no
-            // resolvable universe (backend returns 400 "must be linked to a
-            // universe"). Retry as `agent` scope and surface available universes.
-            const status = error?.response?.status;
-            const detail = String(error?.response?.data?.detail ?? "");
-            const isMissingUniverse = status === 400 &&
-                !explicitScope &&
-                !universeId &&
-                detail.includes("must be linked to a universe");
-            if (isMissingUniverse) {
-                try {
-                    const result = await memoryClient.storeMemory({ ...baseInput, scope: "agent" });
-                    let text = `Memory stored successfully.\nID: ${result.id}\nType: ${result.memory_type}\nScope: ${result.scope}`;
-                    // Enrich with available universes to help future categorization.
-                    try {
-                        const orgId = getResolvedTenantOrgId();
-                        if (orgId) {
-                            const list = await cpClient.listUniverses(orgId);
-                            const universes = Array.isArray(list) ? list : (list.universes || list.items || []);
-                            if (universes && universes.length > 0) {
-                                text += `\n\nDica: esta memória não foi associada a um universo (salva como memória do agente). Para categorizá-la, informe universe_id na próxima vez. Universos disponíveis:`;
-                                universes.forEach((u) => {
-                                    text += `\n- ${u.name} (id: ${u.id})`;
-                                });
-                            }
-                        }
-                    }
-                    catch {
-                        // Listing universes is best-effort; never break a successful store.
-                    }
-                    return { content: [{ type: "text", text }] };
-                }
-                catch (retryError) {
-                    const retryApiErr = handleApiError(retryError);
-                    if (retryApiErr)
-                        return retryApiErr;
-                    throw retryError;
-                }
-            }
             const apiErr = handleApiError(error);
             if (apiErr)
                 return apiErr;

package/dist/types/index.d.ts

@@ -106,6 +106,7 @@ export interface MemoryClientInterface {
         metadata?: Record<string, unknown>;
         context_id?: string;
         credential_ref?: string;
+        universe_id?: string;
     }): Promise<any>;
     searchMemories(data: {
         query_text: string;
@@ -121,6 +122,13 @@ export interface MemoryClientInterface {
         task_description: string;
         max_tokens?: number;
     }): Promise<any>;
+    getPendingClassifications(limit?: number): Promise<any>;
+    approveClassification(memoryId: string, data?: {
+        universe_id?: string;
+        context_id?: string;
+    }): Promise<any>;
+    rejectClassification(memoryId: string): Promise<any>;
+    approveClassificationBatch(ids: string[]): Promise<any>;
     reinforceMemory(memoryId: string, boost?: number): Promise<any>;
     weakenMemory(memoryId: string, penalty?: number): Promise<any>;
     getWorkingMemory(contextId: string): Promise<any>;

package/manifest.json

@@ -2,8 +2,8 @@
   "manifest_version": "0.3",
   "name": "frinus",
   "display_name": "Frinus — Memória Cognitiva",
-  "version": "3.1.0",
-  "description": "Memória cognitiva de longo prazo para o Claude (φρήν + νοῦς). 70 ferramentas de memória, sessões, agentes e conhecimento.",
+  "version": "3.4.1",
+  "description": "Memória cognitiva de longo prazo para o Claude (φρήν + νοῦς). 80 ferramentas de memória, sessões, agentes e conhecimento.",
   "long_description": "O Frinus dá ao Claude memória de longo prazo, identidade e inteligência persistente entre conversas. Conecta o Claude Desktop à plataforma Frinus (Memory Engine, Control Plane e Agent Service) via MCP. Basta colar sua chave de API pessoal — nada para instalar ou compilar.",
   "author": {
     "name": "Frinus",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frinus-mcp",
-  "version": "3.3.0",
+  "version": "3.4.1",
   "description": "Frinus - MCP Server for Cognitive Memory (φρήν + νοῦς). Long-term memory, sessions, agents and knowledge for Claude and any MCP client.",
   "type": "module",
   "main": "dist/index.js",