frinus-mcp 3.2.0 → 3.2.1

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

@@ -39,6 +39,7 @@ export declare class MemoryClient implements MemoryClientInterface {
         metadata?: Record<string, unknown>;
         context_id?: string;
         credential_ref?: string;
+        universe_id?: string;
     }): Promise<any>;
     searchMemories(data: {
         query_text: string;

package/dist/client/memory-client.js

@@ -86,10 +86,12 @@ export class MemoryClient {
             agent_id: data.agent_id,
             content: data.content,
             memory_type: data.memory_type || "episodic",
-            scope: data.scope || "organization",
             importance: data.importance || 0.5,
             metadata: data.metadata,
         };
+        // The handler is the source of truth for scope; only send it when defined.
+        if (data.scope)
+            payload.scope = data.scope;
         if (data.user_id)
             payload.user_id = data.user_id;
         if (data.created_by_user_id)
@@ -98,6 +100,8 @@ export class MemoryClient {
             payload.context_id = data.context_id;
         if (data.credential_ref)
             payload.credential_ref = data.credential_ref;
+        if (data.universe_id)
+            payload.universe_id = data.universe_id;
         const response = await this.client.post("/memories", payload);
         return response.data;
     }

package/dist/tools/definitions.js

@@ -38,7 +38,7 @@ Scopes:
                 scope: {
                     type: "string",
                     enum: ["user", "agent", "universe", "organization"],
-                    description: "Visibility scope: user (private), agent (agent-only), universe (department), organization (org-wide). Default: 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.",
                 },
                 importance: {
                     type: "number",
@@ -56,6 +56,10 @@ Scopes:
                     type: "object",
                     description: "Metadata adicional (tags, universe, idioma, etc.)",
                 },
+                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.",
+                },
                 context_id: {
                     type: "string",
                     description: "Optional UUID of a hierarchy node (universe, concept, theme, topic, or point). When provided, the memory is automatically linked to this node and all its ancestors. Takes precedence over universe_id for hierarchy placement.",

package/dist/tools/handlers.js

@@ -200,39 +200,33 @@ const handlers = {
     // ==========================================================================
     // Core Memory
     // ==========================================================================
-    async memory_store(args, { memoryClient, resolvedUserId }) {
+    async memory_store(args, { memoryClient, cpClient, 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,
+        };
         try {
-            const createdByUser = args.created_by_user_id || resolvedUserId || undefined;
-            const userId = args.user_id || resolvedUserId || undefined;
-            // Auto-scope inference: if scope not provided, pick the narrowest
-            // scope justified by the available context. Caller can always pass
-            // an explicit `scope` to override this heuristic.
-            const meta = args.metadata || {};
-            const universeId = args.universe_id || meta.universe_id || undefined;
-            let resolvedScope = args.scope;
-            if (!resolvedScope) {
-                if (userId || createdByUser) {
-                    resolvedScope = "user";
-                }
-                else if (universeId) {
-                    resolvedScope = "universe";
-                }
-                else {
-                    resolvedScope = "organization";
-                }
-            }
-            const result = await memoryClient.storeMemory({
-                agent_id: args.agent_id,
-                content: args.content,
-                memory_type: args.memory_type,
-                scope: resolvedScope,
-                importance: args.importance,
-                user_id: userId,
-                created_by_user_id: createdByUser,
-                metadata: args.metadata,
-                context_id: args.context_id,
-                credential_ref: args.credential_ref,
-            });
+            const result = await memoryClient.storeMemory({ ...baseInput, scope: resolvedScope });
             return {
                 content: [{
                         type: "text",
@@ -241,6 +235,45 @@ const handlers = {
             };
         }
         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/package.json

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