frinus-mcp 3.2.1 → 3.4.0

package/README.md

@@ -1,13 +1,32 @@
 # Frinus MCP Server
 
-> **φρήν + νοῦς** — The cognitive memory bridge between Claude agents and the [Frinus](https://github.com/frinus-ai) platform.
+> **φρήν + νοῦς** — Gives your Claude agent long-term, cognitive memory backed by the [Frinus](https://frinus.rdxsec.com.br) platform.
 
-MCP (Model Context Protocol) server that exposes **70 tools** spanning cognitive memory, working memory, sessions, agents, the L0–L3 knowledge hierarchy, orchestration tasks, and training pipelines. The server speaks stdio and is consumed by Claude Desktop, Claude Code, and any MCP-aware client.
+`frinus-mcp` is an MCP (Model Context Protocol) server. It is the **bridge** between your MCP client — Claude Code, Cursor, or Claude Desktop — and the **Frinus platform hosted at https://frinus.rdxsec.com.br**.
 
-- **Version:** 3.1.0
+It does **not** run on its own. It stores nothing locally: every tool call is forwarded over HTTPS to your Frinus account. So before it does anything useful you need two things:
+
+1. a **Frinus account** (free, no card), and
+2. a **Frinus API key** (`sk-frinus-...`).
+
+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
 - **Tools:** 70 (see [Tools Reference](#tools-reference))
-- **Backends:** Memory Engine (`:8001`) + Control Plane (`:8000`) + Agent Service (`:8002`)
-- **Public mirror:** https://github.com/frinus-ai/frinus-mcp
+- **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)
+
+## How it fits together
+
+```
++-------------------+        +--------------+        +----------------------------+
+| Your MCP client   | stdio  | frinus-mcp   | HTTPS  | Frinus platform            |
+| (Claude Code,     | <----> | (this server,| <----> | frinus.rdxsec.com.br       |
+|  Cursor, Desktop) |        |  via npx)    |        | (your memories live here)  |
++-------------------+        +--------------+        +----------------------------+
+```
+
+The server validates your API key against the platform at startup, resolves your account + organisation, and routes every tool call there. No API key → it refuses to start.
 
 ## Rule Zero — MCP is mandatory
 
@@ -20,70 +39,51 @@ The Frinus MCP **is** the agent's long-term memory, identity, and intelligence.
 
 The complete protocol set lives in the global `CLAUDE.md` (Frinus organisation), summarised below in [The 7 Protocols](#the-7-protocols).
 
-## Requirements
+## Before you start — account + API key
 
-- Node.js 18+
-- Frinus stack reachable (Memory Engine, Control Plane, Agent Service)
-- Personal API key (`sk-frinus-...`) tied to your tenant
+You need a Frinus account and an API key. Both are free to get.
 
-## Installation
+### 1. Create a free account
 
-**End users — no install needed.** Use the published package via `npx` (see config below), or the one-click `.mcpb` extension for Claude Desktop.
+Sign up at **https://frinus.rdxsec.com.br**. The **Free plan (R$0)** is enough to get started:
 
-**Developers / from source:**
+- 100 memories
+- 20 queries/day
+- no credit card required
+
+### 2. Generate an API key
+
+Once logged in, open your account **Settings → API Keys** and create a new key. You'll get a value shaped like:
 
-```bash
-npm install
-npm run build
+```
+sk-frinus-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 ```
 
-The build emits `dist/index.js`, ready to be wired into Claude Desktop / Claude Code.
+Copy it now — for security it's shown **only once**. This value goes into the `FRINUS_API_KEY` environment variable below. Treat it like a password; never commit it to a repo.
 
-## Distribution
+## Getting started (zero to first memory)
 
-| Channel | Client | User effort |
-|---------|--------|-------------|
-| **npm** (`npx -y frinus-mcp`) | Claude Code, Cursor, Codex, opencode | Paste config + API key |
-| **`.mcpb` bundle** | Claude Desktop | Double-click + paste API key |
-| **From source** | any | Clone + build + absolute path |
+Five minutes, four steps.
 
-URL defaults point at the Frinus SaaS, so only `FRINUS_API_KEY` is required. Override `MEMORY_SERVICE_URL` / `FRINUS_CP_URL` / `AGENT_SERVICE_URL` for self-hosted instances or local dev.
+### Step 1 — Create your account
 
-### Publishing (maintainers)
+Sign up at https://frinus.rdxsec.com.br (Free plan, no card). See [above](#1-create-a-free-account).
 
-```bash
-# 1) npm package — powers `npx -y frinus-mcp` everywhere
-npm version <patch|minor|major>
-npm publish                      # prepublishOnly runs the build
+### Step 2 — Generate your API key
 
-# 2) .mcpb bundle — powers the Claude Desktop one-click install
-npm run pack:mcpb                # -> frinus.mcpb
-gh release upload v<version> frinus.mcpb --repo frinus-ai/frinus-mcp --clobber
-# Frontend points at: releases/latest/download/frinus.mcpb
-```
+Settings → API Keys → create. Copy the `sk-frinus-...` value. See [above](#2-generate-an-api-key).
 
-## Environment Variables
+### Step 3 — Add the server to your client
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `FRINUS_API_KEY` | **required** | Personal API key (`sk-frinus-...`). Resolves tenant + user identity at boot. |
-| `MEMORY_SERVICE_URL` | `http://localhost:8001` | Memory Engine base URL |
-| `FRINUS_CP_URL` | `http://localhost:8000` | Control Plane base URL (universes, orgs, billing) |
-| `AGENT_SERVICE_URL` | `http://localhost:8002` | Agent Service base URL (agents, invocation, skills) |
-| `FRINUS_MEMORY_API_KEY` | — | Legacy fallback for `FRINUS_API_KEY` |
+You don't install anything — `npx` fetches and runs the package on demand. The only value you must provide is your API key; the platform URLs already default to production.
 
-Production endpoints (Frinus SaaS):
+**Claude Code (one-liner):**
 
 ```bash
-MEMORY_SERVICE_URL=https://frinus-memory.rdxsec.com.br
-FRINUS_CP_URL=https://frinus-api.rdxsec.com.br
-AGENT_SERVICE_URL=https://frinus-agents.rdxsec.com.br
-FRINUS_API_KEY=sk-frinus-...
+claude mcp add frinus --env FRINUS_API_KEY=sk-frinus-... -- npx -y frinus-mcp@latest
 ```
 
-## Claude Desktop / Claude Code Configuration
-
-Add the server to your MCP client configuration. **Recommended (npx, no install):**
+**Cursor / Claude Desktop / any client (config JSON):**
 
 ```json
 {
@@ -99,35 +99,45 @@ Add the server to your MCP client configuration. **Recommended (npx, no install)
 }
 ```
 
-Claude Code one-liner:
+Config file locations:
 
-```bash
-claude mcp add frinus --env FRINUS_API_KEY=sk-frinus-... -- npx -y frinus-mcp@latest
+- **Claude Code:** `~/.claude.json`, under `mcpServers`.
+- **Claude Desktop:** `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `~/.config/claude/claude_desktop_config.json` (Linux). Or use the one-click `.mcpb` extension and just paste your API key.
+- **Cursor:** `~/.cursor/mcp.json`, under `mcpServers`.
+
+Restart the client so it picks up the new server.
+
+> Replace `sk-frinus-...` with the real key from Step 2. You normally set **only** `FRINUS_API_KEY` — every backend URL already defaults to the hosted platform. See [Environment Variables](#environment-variables) for the full list and the self-host override.
+
+### Step 4 — Validate with your first memory
+
+In your client, ask the agent to store and recall something:
+
+```
+Store this in Frinus memory: "Our staging DB is reset every night at 02:00 UTC."
 ```
 
-From source (developers), point at the built entry and override URLs as needed:
+then in the same or a later session:
 
-```json
-{
-  "mcpServers": {
-    "frinus": {
-      "command": "node",
-      "args": ["/absolute/path/to/mcp/dist/index.js"],
-      "env": {
-        "FRINUS_API_KEY": "sk-frinus-...",
-        "MEMORY_SERVICE_URL": "http://localhost:8001",
-        "FRINUS_CP_URL": "http://localhost:8000",
-        "AGENT_SERVICE_URL": "http://localhost:8002"
-      }
-    }
-  }
-}
 ```
+What time does our staging DB reset?
+```
+
+Behind the scenes the agent calls `memory_store` then `memory_search` / `search_with_attention`. If the recall comes back, the bridge is live. You can confirm the same memory appears in the web app at https://frinus.rdxsec.com.br.
 
-Claude Desktop config path: `~/.config/claude/claude_desktop_config.json` (Linux) / `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS).
-Claude Code config path: `~/.claude.json` under `mcpServers`.
+## Environment Variables
+
+In normal use you set **only** `FRINUS_API_KEY`. The service URLs already point at the hosted platform — leave them alone unless you self-host (see [Advanced — self-host](#advanced--self-host--local-dev)).
+
+| Variable | Default (hosted platform) | Description |
+|----------|---------------------------|-------------|
+| `FRINUS_API_KEY` | **required** | Your personal API key (`sk-frinus-...`). Resolves account + organisation at boot. |
+| `MEMORY_SERVICE_URL` | `https://frinus-memory.rdxsec.com.br` | Memory Engine base URL |
+| `FRINUS_CP_URL` | `https://frinus-api.rdxsec.com.br` | Control Plane base URL (account, orgs, API keys, billing) |
+| `AGENT_SERVICE_URL` | `https://frinus-agents.rdxsec.com.br` | Agent Service base URL (agents, invocation, skills) |
+| `FRINUS_MEMORY_API_KEY` | — | Legacy fallback for `FRINUS_API_KEY` |
 
-On startup the server validates the API key via `/auth/me` and resolves the tenant org ID + logged-in user. Failures abort the process with `[FATAL]` so the client surfaces the error.
+On startup the server validates the API key against the platform and resolves your organisation + logged-in user. If validation fails it aborts with `[FATAL]` so the client surfaces the error — re-check the key from Settings → API Keys.
 
 ## The 7 Protocols
 
@@ -409,6 +419,46 @@ Operational guidelines:
 
 Tenant isolation is database-per-tenant. The MCP resolves your tenant org ID from the API key at boot — you never pass `org_id` manually.
 
+## Advanced — self-host / local dev
+
+Everything above targets the hosted platform at https://frinus.rdxsec.com.br, which is what almost everyone wants. If you run your own Frinus stack (or develop the MCP against a local backend), build from source and override the three URLs:
+
+```bash
+git clone https://github.com/frinus-ai/frinus-mcp && cd frinus-mcp
+npm install
+npm run build      # emits dist/index.js
+```
+
+```json
+{
+  "mcpServers": {
+    "frinus": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp/dist/index.js"],
+      "env": {
+        "FRINUS_API_KEY": "sk-frinus-...",
+        "MEMORY_SERVICE_URL": "http://localhost:8001",
+        "FRINUS_CP_URL": "http://localhost:8000",
+        "AGENT_SERVICE_URL": "http://localhost:8002"
+      }
+    }
+  }
+}
+```
+
+### Publishing (maintainers)
+
+```bash
+# 1) npm package — powers `npx -y frinus-mcp` everywhere
+npm version <patch|minor|major>
+npm publish                      # prepublishOnly runs the build
+
+# 2) .mcpb bundle — powers the Claude Desktop one-click install
+npm run pack:mcpb                # -> frinus.mcpb
+gh release upload v<version> frinus.mcpb --repo frinus-ai/frinus-mcp --clobber
+# Frontend points at: releases/latest/download/frinus.mcpb
+```
+
 ## Development
 
 ```

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

@@ -0,0 +1,25 @@
+/**
+ * Resolved MCP client identity.
+ *
+ * The MCP client sends its `clientInfo: { name, version }` during the
+ * `initialize` handshake. We normalize the raw `name` into a small, stable
+ * set of buckets and expose it as the `X-Client` header so the Control Plane
+ * can attribute the `mcp_connected` PostHog event to the right client
+ * ("claude_code", "cursor", "desktop", "codex", "unknown").
+ *
+ * Module-level singleton (getter/setter), mirroring `resolvedTenantOrgId` in
+ * memory-client.ts: it is captured by an Axios request interceptor at
+ * construction time and read lazily on each request, so a single mutable
+ * module value is the least-surprising shape here.
+ */
+export type ResolvedClient = "claude_code" | "cursor" | "desktop" | "codex" | "unknown";
+/**
+ * Normalize a raw `clientInfo.name` into a stable bucket.
+ *
+ * Order matters: the more specific "claude-code" check must run before the
+ * generic "claude" → desktop fallback, so Claude Code is never misclassified
+ * as the desktop app.
+ */
+export declare function normalizeClient(rawName?: string | null): ResolvedClient;
+export declare function setResolvedClient(rawName?: string | null): void;
+export declare function getResolvedClient(): ResolvedClient;

package/dist/client/client-info.js

@@ -0,0 +1,48 @@
+/**
+ * Resolved MCP client identity.
+ *
+ * The MCP client sends its `clientInfo: { name, version }` during the
+ * `initialize` handshake. We normalize the raw `name` into a small, stable
+ * set of buckets and expose it as the `X-Client` header so the Control Plane
+ * can attribute the `mcp_connected` PostHog event to the right client
+ * ("claude_code", "cursor", "desktop", "codex", "unknown").
+ *
+ * Module-level singleton (getter/setter), mirroring `resolvedTenantOrgId` in
+ * memory-client.ts: it is captured by an Axios request interceptor at
+ * construction time and read lazily on each request, so a single mutable
+ * module value is the least-surprising shape here.
+ */
+let resolvedClient = "unknown";
+/**
+ * Normalize a raw `clientInfo.name` into a stable bucket.
+ *
+ * Order matters: the more specific "claude-code" check must run before the
+ * generic "claude" → desktop fallback, so Claude Code is never misclassified
+ * as the desktop app.
+ */
+export function normalizeClient(rawName) {
+    if (!rawName)
+        return "unknown";
+    const name = rawName.toLowerCase();
+    if (name.includes("claude-code") || name.includes("claudecode")) {
+        return "claude_code";
+    }
+    if (name.includes("cursor")) {
+        return "cursor";
+    }
+    if (name.includes("codex")) {
+        return "codex";
+    }
+    // Generic Claude clients (Claude Desktop, claude-ai, etc.) — must come after
+    // the claude-code check above.
+    if (name.includes("claude") || name.includes("claude-ai") || name.includes("desktop")) {
+        return "desktop";
+    }
+    return "unknown";
+}
+export function setResolvedClient(rawName) {
+    resolvedClient = normalizeClient(rawName);
+}
+export function getResolvedClient() {
+    return resolvedClient;
+}

package/dist/client/cp-client.js

@@ -3,6 +3,7 @@
  */
 import axios from "axios";
 import { getResolvedTenantOrgId } from "./memory-client.js";
+import { getResolvedClient } from "./client-info.js";
 export class CpClient {
     client;
     constructor(baseURL, apiKey) {
@@ -16,6 +17,7 @@ export class CpClient {
             const orgId = getResolvedTenantOrgId();
             if (orgId)
                 config.headers['X-Tenant-ID'] = orgId;
+            config.headers['X-Client'] = getResolvedClient();
             return config;
         });
     }

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/index.js

@@ -17,6 +17,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextpro
 import { MemoryClient, getResolvedUserEmail, getResolvedUserId, setResolvedTenantOrgId, setResolvedUserEmail, setResolvedUserId, getResolvedTenantOrgId, } from "./client/memory-client.js";
 import { AgentClient } from "./client/agent-client.js";
 import { CpClient } from "./client/cp-client.js";
+import { getResolvedClient, setResolvedClient } from "./client/client-info.js";
 import { InteractionCapture } from "./capture/interaction-capture.js";
 import { TOOLS } from "./tools/definitions.js";
 import { dispatchTool } from "./tools/handlers.js";
@@ -95,6 +96,17 @@ async function main() {
         }
         return toolResult;
     });
+    // Resolve the connecting MCP client's identity for the X-Client header.
+    // `getClientVersion()` is only populated after the `initialize` handshake,
+    // so we read it from the `oninitialized` callback (fired on the client's
+    // `notifications/initialized`), not right after `connect()`.
+    server.oninitialized = () => {
+        const rawName = server.getClientVersion()?.name;
+        setResolvedClient(rawName);
+        // Logged once for calibration against real clients (stderr, not stdout —
+        // stdout is the MCP transport).
+        console.error(`[Client] clientInfo.name=${JSON.stringify(rawName ?? null)} normalized=${getResolvedClient()}`);
+    };
     // Start server
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/tools/definitions.js

@@ -9,6 +9,13 @@ 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") 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 scope/universe_id/context_id explicitly sets the destination directly
+(no suggestion needed).
+
 Memory types:
 - episodic: Specific experiences and events (what happened)
 - semantic: General knowledge and facts (what I know)
@@ -38,7 +45,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. Omit to let the backend auto-classify and return a suggestion (status 'proposed'). When set, it overrides classification (status 'manual'): 'organization' (org-wide), 'user' (private), 'universe' (department-shared), 'agent' (agent-only).",
                 },
                 importance: {
                     type: "number",
@@ -58,7 +65,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 associate the memory with explicitly (overrides auto-classification → status 'manual'). Omit to let the backend suggest one.",
                 },
                 context_id: {
                     type: "string",
@@ -156,6 +163,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,255 @@ 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 "";
+}
+/**
+ * Render the memory_store response. New backend: shows the auto-classification
+ * suggestion (proposed) or final destination (manual/approved) enxuto, no
+ * intrusive "Dica/Universos disponíveis" block. Old backend (no classification
+ * fields): minimal ID/Type/Scope, also WITHOUT any hint.
+ */
+function renderStoreResult(result) {
+    const id = result?.id;
+    const status = result?.classification_status;
+    const head = `✓ Salva`;
+    // Defensive: older backend without classification fields.
+    if (!status) {
+        return `Memory stored successfully.\nID: ${id}\nType: ${result?.memory_type}\nScope: ${result?.scope}`;
+    }
+    if (status === "proposed") {
+        const uni = universeName(result?.classified_universe);
+        const ctx = contextName(result?.classified_context);
+        const conf = confidenceLabel(result?.confidence);
+        // High/medium-confidence node identified.
+        if (uni && ctx) {
+            const confTxt = conf ? `, confiança ${conf}` : "";
+            return `${head} · sugestão: ${suggestionLabel(result)} (auto${confTxt}) — aprove com memory_classification_approve`;
+        }
+        // Universe-only suggestion (no specific node).
+        if (uni) {
+            return `${head} · sugestão de universo: ${uni} (nó específico não identificado) — aprove com memory_classification_approve`;
+        }
+        // Low / no confidence: no reliable suggestion.
+        return `${head} · sem sugestão confiável — use memory_classification_pending para revisar`;
+    }
+    // manual / approved: show final destination without "sugestão".
+    const dest = destinationLabel(result);
+    if (dest)
+        return `${head} · classificada em: ${dest}`;
+    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({ ...baseInput, scope: resolvedScope });
+            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 {
+            // 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frinus-mcp",
-  "version": "3.2.1",
+  "version": "3.4.0",
   "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",