get_cluster_insights

Instructions

Implementation Reference

• src/memory-manager.js:868-905 (handler)

  Main handler implementation that retrieves detailed analytics for a memory cluster. Performs a complex SQL query with joins across memory_clusters, memory_cluster_members, and memories tables to aggregate statistics including total memories, average importance, last memory access, recent memories count, average membership strength, and memory types distribution.

  async getClusterInsights(clusterId) {
    try {
      const insights = await this.db
        .select({
          id: schema.memoryClusters.id,
          name: schema.memoryClusters.name,
          clusterType: schema.memoryClusters.clusterType,
          description: schema.memoryClusters.description,
          importanceScore: schema.memoryClusters.importanceScore,
          totalMemories: sql`COUNT(${schema.memoryClusterMembers.memoryId})`.as('total_memories'),
          avgImportance: sql`AVG(${schema.memories.importance})`.as('avg_importance'),
          lastMemoryAccess: sql`MAX(${schema.memories.lastAccessed})`.as('last_memory_access'),
          recentMemories: sql`COUNT(CASE WHEN ${schema.memories.createdAt} > CURRENT_TIMESTAMP - INTERVAL '7 days' THEN 1 END)`.as('recent_memories'),
          avgMembershipStrength: sql`AVG(${schema.memoryClusterMembers.membershipStrength})`.as('avg_membership_strength'),
          memoryTypes: sql`array_agg(DISTINCT ${schema.memories.type})`.as('memory_types')
        })
        .from(schema.memoryClusters)
        .leftJoin(
          schema.memoryClusterMembers,
          eq(schema.memoryClusters.id, schema.memoryClusterMembers.clusterId)
        )
        .leftJoin(
          schema.memories,
          and(
            eq(schema.memoryClusterMembers.memoryId, schema.memories.id),
            eq(schema.memories.status, 'active')
          )
        )
        .where(eq(schema.memoryClusters.id, clusterId))
        .groupBy(schema.memoryClusters.id)
        .limit(1);
  
      return insights[0] || null;
    } catch (error) {
      console.warn('Cluster insights query failed:', error.message);
      return null;
    }
  }

• src/tools/memory-tools.js:348-360 (schema)

  Tool schema definition specifying the input validation. Requires a cluster_id parameter (UUID string) and provides description for getting detailed analytics for a memory cluster.

    name: "get_cluster_insights",
    description: "Get detailed analytics for a memory cluster",
    inputSchema: {
      type: "object",
      properties: {
        cluster_id: {
          type: "string",
          description: "UUID of the cluster"
        }
      },
      required: ["cluster_id"]
    }
  },

• mcp.js:374-386 (registration)

  MCP tool registration in the tools list, defining the tool name, description, and input schema for the get_cluster_insights tool.

    name: "get_cluster_insights",
    description: "Get detailed analytics for a memory cluster",
    inputSchema: {
      type: "object",
      properties: {
        cluster_id: {
          type: "string",
          description: "UUID of the cluster"
        }
      },
      required: ["cluster_id"]
    }
  },

• mcp.js:645-647 (registration)

  Tool routing handler in the switch statement that calls memoryManager.getClusterInsights() with the cluster_id argument and returns JSON-serialized results.

  case "get_cluster_insights":
    const clusterInsights = await memoryManager.getClusterInsights(args.cluster_id);
    return { content: [{ type: "text", text: JSON.stringify(clusterInsights, null, 2) }] };

• src/db/schema.js:37-56 (schema)

  Database schema definition for memory_clusters table that stores cluster metadata including id, name, clusterType, description, importanceScore, and other fields used by the insights query.

  export const memoryClusters = pgTable("memory_clusters", {
  	id: uuid().defaultRandom().primaryKey().notNull(),
  	createdAt: timestamp("created_at", { withTimezone: true, mode: 'string' }).default(sql`CURRENT_TIMESTAMP`),
  	updatedAt: timestamp("updated_at", { withTimezone: true, mode: 'string' }).default(sql`CURRENT_TIMESTAMP`),
  	clusterType: clusterType("cluster_type").notNull(),
  	name: text().notNull(),
  	description: text(),
  	centroidEmbedding: vector("centroid_embedding", { dimensions: 1536 }),
  	emotionalSignature: jsonb("emotional_signature"),
  	keywords: text().array(),
  	importanceScore: doublePrecision("importance_score").default(0),
  	coherenceScore: doublePrecision("coherence_score"),
  	lastActivated: timestamp("last_activated", { withTimezone: true, mode: 'string' }),
  	activationCount: integer("activation_count").default(0),
  	worldviewAlignment: doublePrecision("worldview_alignment"),
  }, (table) => [
  	index("memory_clusters_centroid_embedding_idx").using("ivfflat", table.centroidEmbedding.asc().nullsLast().op("vector_cosine_ops")),
  	index("memory_clusters_cluster_type_importance_score_idx").using("btree", table.clusterType.asc().nullsLast().op("enum_ops"), table.importanceScore.desc().nullsFirst().op("float8_ops")),
  	index("memory_clusters_last_activated_idx").using("btree", table.lastActivated.desc().nullsFirst().op("timestamptz_ops")),
  ]);